Using JSONC for Configs: When Comments Make or Break Your Build

Why JSONC Matters for Configuration Files

When a team ships a configuration file, the first question is: how do we keep it readable for humans without breaking the parser that a runtime expects?

Standard JSON (RFC 8259) is strict: no comments, no trailing commas. That strictness makes it ideal for data interchange, but it forces teams to maintain separate documentation or rely on comments in code that never see the runtime.

JSONC (JSON with comments) solves the readability problem by allowing // and /* */ annotations while remaining a superset of JSON. The file can be parsed by a comment‑aware tool, and then stripped before being fed to a strict JSON parser.

Supported Tools and Ecosystem

• VS Code – syntax highlighting and IntelliSense for JSONC.
• Prettier – formats JSONC files, preserving comment positions.
• ESLint (jsonc plugin) – linting rules that enforce a single style across a repo.
• Node packages – strip-json-comments, jsonc-parser.
• jq – can be used with a custom filter to remove comments.

These tools let you keep a single file format that is both machine‑readable and human‑friendly.

Concrete Example: Stripping Comments Before Runtime

Suppose we have config.jsonc:

{
  // Database connection details
  "db": {
    "host": "localhost", // The host machine
    "port": 5432,
    /* Use SSL in production */
    "ssl": true
  },
  "featureFlags": {
    "newUI": false
  }
}

Running it through strip-json-comments in a Node script produces pure JSON:

// strip-config.js
const fs = require('fs');
const strip = require('strip-json-comments');
const raw = fs.readFileSync('config.jsonc', 'utf8');
const json = JSON.parse(strip(raw));
fs.writeFileSync('config.json', JSON.stringify(json, null, 2));

Now config.json can be safely loaded by any strict JSON parser:

const config = require('./config.json');
console.log(config.db.host); // "localhost"

Verification Checklist

1. Run the comment‑stripping tool and inspect the output file – it should contain only valid JSON tokens.
2. Feed the stripped file to a linter configured for RFC 8259 (e.g., eslint --ext .json with jsonc plugin disabled).
3. Use a runtime parser (e.g., JSON.parse or Jackson ObjectMapper) to load the file; no exceptions should occur.

Trade‑offs and Limitations

• Build‑time dependency: Every consumer must run a strip step or use a library that supports comments. In CI pipelines, this adds another script and potential failure point.
• Inconsistent tooling: If some parts of the project use JSONC and others pure JSON, linting rules must enforce a single style to avoid confusion.
• Parser compatibility: Some languages or frameworks ship with a strict JSON parser that will reject comments outright. In those cases, JSONC is only useful for development-time tooling.

When to Adopt JSONC

Choose JSONC when:

• Teams need to annotate configuration files without maintaining separate docs.
• The build pipeline can accommodate a comment‑stripping step.
• All developers use tooling that understands JSONC (VS Code, Prettier, ESLint).

Actionable Closing

To get started:

1. Add strip-json-comments to your devDependencies and create a script that strips .jsonc files into .json.
2. Configure ESLint with the jsonc parser and enforce a rule that disallows mixed styles.
3. Document the process in your README so new contributors know to edit .jsonc and run the strip step before committing.

With these steps, you keep the readability of comments while satisfying the strictness required by production runtimes.