Why Can Some JSON Files Have Comments?

If you have written TypeScript, this file probably looks very familiar:

{
  /* Visit https://aka.ms/tsconfig to read more about this file */
  "compilerOptions": {
    "target": "ES2022",
    "strict": true
  }
}

Wait...

Isn’t JSON supposed to forbid comments?

According to the JSON standard, examples like these are invalid:

// This is a single-line comment
{
  "name": "ChatGPT"
}
{
  /*
   This is a block comment
  */
  "name": "ChatGPT"
}

So why can configuration files such as tsconfig.json, settings.json, and launch.json use comments without any drama? Let’s unpack the reason.

Why Does JSON Not Allow Comments?

JSON, short for JavaScript Object Notation, was designed first as a data interchange format.

Simple, consistent, and easy to parse.

That is why the official JSON specification, RFC 8259, does not include comments. Standard JSON only allows these values:

• Object
• Array
• String
• Number
• Boolean
• null

Everything else, including comments, trailing commas, and single-quoted strings, is outside the standard.

A standard JSON parser will reject a file like this:

{
  // User name
  "name": "Tom",
}

Why Are Comments Useful Anyway?

JSON does not support comments, but configuration files often need them badly.

Without comments, a config may look like this:

{
  "strict": true,
  "module": "NodeNext",
  "target": "ES2022"
}

For someone new to the project, strict may be unclear, and target: ES2022 may raise more questions than it answers.

With comments, the same intent becomes much easier to read:

{
  // Enable strict mode. Keeping this true is recommended.
  "strict": true,
  // Emit ES2022 code.
  "target": "ES2022"
}

Comments help configuration files in a few practical ways:

• They reduce the learning curve because options can explain themselves.
• They help teams communicate why a setting exists, not just what the value is.
• They preserve maintenance context for unusual project choices.
• They improve the editing experience because many IDEs display and preserve those notes.

So while JSON itself does not support comments, real-world configuration often benefits from them.

Why Can tsconfig.json Use Comments?

The answer is simple: it is not strict JSON. TypeScript does not feed tsconfig.json directly to a standard JSON parser. It uses an extended format called JSONC, short for JSON with Comments.

JSONC adds a small set of features on top of JSON:

• Single-line comments with //
• Block comments with /* */

For example:

{
  // Output target
  "target": "ES2022",
  /*
    Whether strict mode is enabled
  */
  "strict": true
}

The TypeScript compiler removes the comments first, then parses the remaining text like ordinary JSON.

So even though the filename is tsconfig.json, its contents are closer to tsconfig.jsonc. The .json extension remains mostly for ecosystem compatibility.

JSONC Is Not the Only Extension: Meet JSON5

The two most common JSON extensions you will see are JSONC and JSON5.

1. JSONC

JSONC is intentionally conservative. It supports line comments and block comments while staying very close to standard JSON. Trailing commas are not encouraged by the core format, even though some implementations may tolerate them.

{
  // User name
  "name": "Tom"
}

Typical JSONC use cases include TypeScript tsconfig.json, VS Code settings.json, launch.json, and VS Code extension configuration files.

2. JSON5

JSON5 goes further. In addition to comments, it supports single quotes, trailing commas, unquoted object keys, hexadecimal numbers, Infinity, and NaN.

{
  // User
  name: 'Tom',
  age: 18,
  skills: [
    'JS',
    'TS',
  ],
}

At that point, it starts to feel much closer to a JavaScript object literal. Many frontend tools support JSON5, including Babel, parts of the Next.js ecosystem, and various Node.js toolchains.

Which Tools Support JSONC?

JSONC support is common in modern developer tooling. If you work in frontend development, you will probably touch JSONC sooner or later.

How Do You Convert JSONC to Standard JSON?

If you need to send JSONC to an API, database, or any program that only accepts standard JSON, you need to strip comments first.

Option 1: Use an npm package

Microsoft’s jsonc-parser package can handle JSONC, and strip-json-comments can remove comments before you parse or serialize the result.

npm install jsonc-parser
npm install strip-json-comments

Option 2: Use an online tool

If you only need to clean a config file occasionally, an online tool is often faster than adding another dependency.

Summary

When people first see comments inside tsconfig.json, it can look strange. The key idea is simple: standard JSON does not allow comments; TypeScript uses JSONC; JSONC makes configuration files easier to read and maintain; JSON5 adds even more JavaScript-style syntax.

For developers, comments in configuration files have become normal across modern toolchains. Understanding JSON, JSONC, and JSON5 helps you choose the right format for each situation.

The next time you see a comment inside tsconfig.json, you do not need to wonder why. It is not strict JSON. It is JSONC.