# How Fastfetch Parses JSONC Configuration Files: A Deep Dive into the Source Code

> Explore how Fastfetch parses JSONC configuration files using the yyjson library. Discover its strict three-phase pipeline and internal C structure transformation.

- Repository: [fastfetch-cli/fastfetch](https://github.com/fastfetch-cli/fastfetch)
- Tags: deep-dive
- Published: 2026-03-30

---

**Fastfetch uses the yyjson library with configurable read flags to parse JSONC files, allowing both comments and trailing commas while transforming the document tree into internal C structures through a strict three-phase pipeline.**

Fastfetch supports JSON with Comments (JSONC) configuration files to give users flexibility when customizing system information displays. According to the fastfetch-cli/fastfetch source code, the parser handles `.jsonc`, `.json5`, and standard `.json` extensions through a dedicated pipeline implemented in [`src/fastfetch.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.c) and the JSON config engine. Understanding this parsing mechanism helps diagnose configuration errors and leverage advanced features like conditional modules.

## The Three-Phase JSONC Parsing Pipeline

Fastfetch processes configuration files through three distinct logical phases, each handled by specific functions in the codebase.

### Phase 1: Resolving File Paths and Parser Flags

When you invoke `fastfetch --config <path>`, the function `optionParseConfigFile()` in [`src/fastfetch.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.c) (lines 39-73) executes first. It constructs an absolute file path, automatically appending the `.jsonc` extension if you omit one, and selects the appropriate `yyjson_read_flag` based on the file extension. For JSONC files, it sets `YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS`, while JSON5 files use `YYJSON_READ_JSON5` and strict JSON uses `0`.

### Phase 2: Loading the Document into yyjson

The `parseJsoncFile()` function (lines 61-85 of [`src/fastfetch.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.c)) calls `yyjson_read_file()` or `yyjson_read_fp()` for stdin, passing the flags determined in Phase 1. This function aborts execution with a descriptive error if the file cannot be opened or contains malformed JSON. It also validates that the root element is an object, returning *"Invalid JSON config format"* if the top-level structure is incorrect.

### Phase 3: Converting JSON to Internal Structures

After successful loading, Fastfetch converts the YYJSON document into `FFOptions*` structures. The function `ffOptionsParseGeneralJsonConfig()` in [`src/options/general.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/options/general.c) (lines 9-67) handles the `"general"` object, while similar functions manage `"logo"` and `"display"`. For the `"modules"` array, `printJsonConfig()` in [`src/common/impl/jsonconfig.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/jsonconfig.c) (lines 90-118) iterates through each element, applies optional `condition` filters, and dispatches to `parseModuleJsonObject()`. This routine invokes each module's specific `parseJsonObject()` implementation and extracts common arguments via `ffJsonConfigParseModuleArgs()` (lines 15-38 of [`jsonconfig.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/jsonconfig.c)).

## Why JSONC Works: Comments and Trailing Commas

JSONC is not a standardized format, but Fastfetch leverages yyjson's permissive parsing capabilities. When a file ends with `.jsonc`, the parser enables two critical flags:

```c
yyjson_read_flag flag = strictJson
    ? 0
    : jsonc
    ? YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS
    : YYJSON_READ_JSON5;

```

This configuration allows both `//` and `/* */` style comments as well as trailing commas after the last element in arrays or objects. The parser silently discards these artifacts during the `yyjson_read_file()` call in `parseJsoncFile()`, treating the remainder as standard JSON.

## Module Configuration and Conditional Logic

### Walking the Modules Array

The generic JSON config engine in [`src/common/impl/jsonconfig.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/jsonconfig.c) handles module discovery through `printJsonConfig()`. It expects a `"modules"` key containing an array of strings (module types) or objects (full configuration). For each module object, the engine checks for a `condition` property that can restrict execution to specific operating systems or environments before instantiation.

### Extracting Module Arguments

Once Fastfetch identifies a module, `parseModuleJsonObject()` looks up the module's metadata in the `ffModuleInfos[]` array and calls its specific JSON parser. Common arguments like `key`, `format`, and `outputColor` are extracted through `ffJsonConfigParseModuleArgs()` (lines 15-38), ensuring consistent handling of presentation options across all modules.

## Practical Configuration Examples

### Creating a Valid JSONC Config File

Fastfetch accepts comments and trailing commas in `.jsonc` files:

```jsonc
{
  // General section – comments are ignored
  "general": {
    "thread": true,          // enable multithreading
    "processingTimeout": 8000
  },

  /* Modules – an array of objects or strings */
  "modules": [
    "os",                    // short form (type only)
    {
      "type": "cpu",         // full form
      "condition": { "system": "Linux" },
      "key": "CPU",
      "format": " {frequency}GHz"
    },
  ]
}

```

Save this as `~/.config/fastfetch/config.jsonc` or pass it explicitly:

```bash
fastfetch --config ~/myconfig.jsonc

```

### Automatic Config Discovery

If you omit the `--config` flag, Fastfetch searches standard directories via `listConfigPaths()` in [`src/fastfetch.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.c) (lines 30-37). It checks for `fastfetch/config.jsonc` under your XDG config home:

```bash
export XDG_CONFIG_HOME="$HOME/.config"
mkdir -p "$XDG_CONFIG_HOME/fastfetch"
cp myconfig.jsonc "$XDG_CONFIG_HOME/fastfetch/config.jsonc"
fastfetch  # Automatically loads the configuration

```

### Generating a Configuration Skeleton

To export the default configuration as JSON:

```bash
fastfetch --gen-config --format json

```

This invokes `ffPrintJsonConfig()` (lines 44-56 of [`src/common/impl/jsonconfig.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/jsonconfig.c)), which serializes the internal `FFOptions` structures into a JSON document suitable for editing and reuse as a JSONC template.

## Summary

- **Fastfetch** parses JSONC through a three-phase pipeline: path resolution (`optionParseConfigFile`), document loading (`parseJsoncFile`), and structure mapping (various `ffOptionsParse*` functions).
- The **yyjson** library handles comment stripping and trailing comma tolerance when the `YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS` flags are set for `.jsonc` files.
- **Module configuration** relies on [`src/common/impl/jsonconfig.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/common/impl/jsonconfig.c) to iterate the `"modules"` array, evaluate conditions, and dispatch to module-specific parsers via `parseModuleJsonObject()`.
- Configuration files are resolved automatically from XDG directories or specified explicitly via the `--config` command-line argument.

## Frequently Asked Questions

### What file extensions does Fastfetch support for configuration files?

Fastfetch recognizes `.jsonc`, `.json5`, and `.json` extensions. When you omit an extension, it defaults to appending `.jsonc`. The extension determines the parser flags: standard JSON enforces strict syntax, JSONC allows comments and trailing commas, and JSON5 permits additional ECMAScript syntax features.

### Why does Fastfetch report "Invalid JSON config format"?

This error originates in `parseJsoncFile()` when the root element of your configuration file is not a JSON object (curly braces). Ensure your file starts with `{` and ends with `}`, even if empty. The function also returns this error if yyjson fails to parse the document due to syntax errors like unclosed strings or missing commas.

### How does Fastfetch handle comments in JSONC files?

Fastfetch delegates comment handling to the yyjson library. When parsing `.jsonc` files, it passes the `YYJSON_READ_ALLOW_COMMENTS` flag to `yyjson_read_file()`, which silently discards both single-line (`//`) and multi-line (`/* */`) comments before constructing the document tree. This happens during Phase 2 of the parsing pipeline in [`src/fastfetch.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.c).

### Can I use environment variables in Fastfetch configuration files?

The JSONC parser itself does not expand environment variables during the initial parse phase. However, specific string values within modules may be interpreted by Fastfetch's internal logic after parsing. For dynamic configuration paths, use the `--config` flag with shell expansion or place your config in the standard XDG directories that Fastfetch searches automatically via `listConfigPaths()`.