Using JSONC

September 02, 2026

If you’ve ever worked on a project with large JSON configuration files, you’ve probably run into the same frustration: the config works, but it’s hard to understand why it’s shaped the way it is.

As configurations grow, you start dealing with:

  • Many keys and deeply nested objects/arrays

  • Similar-looking sections with subtle differences

  • Unclear naming that hides intent

Then the questions begin:

  • Why was this value chosen for that key?

  • Why does this object look almost like that other object, but behave differently?

  • Where is the “documentation” for this config supposed to live?

Enter JSONC (JSON with Comments)

JSONC stands for JSON with Comments. It’s essentially JSON that allows you to add comments directly inside the file—exactly what you need to make a configuration self-explanatory while keeping it close to the code that consumes it.

JSON itself doesn’t allow comments, which is why large JSON configs often become difficult to maintain. JSONC addresses that gap by letting you annotate the configuration with intent, caveats, and usage notes.

Learn more: https://jsonc.org/

How to work with JSONC

In most cases, the approach is:

  1. Write config as JSONC (add // and /* ... */ comments where needed).

  2. Parse it into valid JSON by stripping comments before using it at runtime.

Many tools already support JSONC out of the box, especially for configuration files.

File extension options

You can use either of these approaches:

  • Use .jsonc for clarity and editor support.

  • Keep .json, but configure your editor to treat it as JSONC.

For example, in VS Code, you can tell the editor to interpret certain .json files as JSONC using .vscode/settings.json at the root of your project.

Where you’ll see JSONC in the wild

You’ve likely interacted with JSONC-style configs already, for example:

  • VS Code: settings.json

  • TypeScript: tsconfig.json

  • Cloudflare Wrangler: wrangler.jsonc

A fascinating detail: the TypeScript compiler itself supports comments in tsconfig.json—which is one reason JSONC is so practical for real-world configuration.

Bottom line: If your configuration is getting large and confusing, JSONC is an easy win. It keeps documentation next to the values it explains, reduces tribal knowledge, and makes future changes much safer.

  • All
  • Configuration
  • Documentation
  • JavaScript

Using JSONC

September 02, 2026

If you’ve ever worked on a project with large JSON configuration files, you’ve probably run into the same frustration: the config works, but it’s hard to understand why it’s shaped the way it is.

As configurations grow, you start dealing with:

  • Many keys and deeply nested objects/arrays

  • Similar-looking sections with subtle differences

  • Unclear naming that hides intent

Then the questions begin:

  • Why was this value chosen for that key?

  • Why does this object look almost like that other object, but behave differently?

  • Where is the “documentation” for this config supposed to live?

Enter JSONC (JSON with Comments)

JSONC stands for JSON with Comments. It’s essentially JSON that allows you to add comments directly inside the file—exactly what you need to make a configuration self-explanatory while keeping it close to the code that consumes it.

JSON itself doesn’t allow comments, which is why large JSON configs often become difficult to maintain. JSONC addresses that gap by letting you annotate the configuration with intent, caveats, and usage notes.

Learn more: https://jsonc.org/

How to work with JSONC

In most cases, the approach is:

  1. Write config as JSONC (add // and /* ... */ comments where needed).

  2. Parse it into valid JSON by stripping comments before using it at runtime.

Many tools already support JSONC out of the box, especially for configuration files.

File extension options

You can use either of these approaches:

  • Use .jsonc for clarity and editor support.

  • Keep .json, but configure your editor to treat it as JSONC.

For example, in VS Code, you can tell the editor to interpret certain .json files as JSONC using .vscode/settings.json at the root of your project.

Where you’ll see JSONC in the wild

You’ve likely interacted with JSONC-style configs already, for example:

  • VS Code: settings.json

  • TypeScript: tsconfig.json

  • Cloudflare Wrangler: wrangler.jsonc

A fascinating detail: the TypeScript compiler itself supports comments in tsconfig.json—which is one reason JSONC is so practical for real-world configuration.

Bottom line: If your configuration is getting large and confusing, JSONC is an easy win. It keeps documentation next to the values it explains, reduces tribal knowledge, and makes future changes much safer.

  • All
  • Configuration
  • Documentation
  • JavaScript