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

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 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 (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) 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 (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 (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).

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:

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 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:

{
  // 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:

fastfetch --config ~/myconfig.jsonc

Automatic Config Discovery

If you omit the --config flag, Fastfetch searches standard directories via listConfigPaths() in src/fastfetch.c (lines 30-37). It checks for fastfetch/config.jsonc under your XDG config home:

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:

fastfetch --gen-config --format json

This invokes ffPrintJsonConfig() (lines 44-56 of 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 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.

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().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}