Most of the tools we use daily in the Node.js ecosystem utilize config files that support various formats such as .js/cjs/mjs, .yaml/toml, or .json. I usually prefer to work with simple text formats like JSON over JavaScript because it spares me the hassle of navigating the ESM versus CJS battle for the correct file extension and export specifier. Even better, if the config publishes a JSON schema, then you get type safety without having to rely on JSDoc or TypeScript types.
4 Steps to Allow Comments in JSON
- Create a
.vscodefolder in your workspace root. - Create a
settings.jsonfile in.vscodefolder. - Create a
"files.associations"top-level object - Create a property for each file name that you want to treat as JSON comments.
The biggest downside to using JSON for config files is, in my opinion, its lack of support for comments. I want to explain why I enabled a certain feature or disabled a certain rule.
Why Doesn’t JSON Support Comments?
JSON was initially designed to be a simple and compact data exchange format, inspired directly by JavaScript’s object literal syntax. Comments were deliberately left out by the creator Douglas Crockford because he believed adding comments would affect the interoperability. This decision remains a controversy to this day and resulted in a new format being created: JSON with Comments (.jsonc).
How to Use JSON With Comments for Configs
I know most tools still accept comments in JSON files because they don’t use the native JSON.parse function, which errors on comments, but instead use custom packages like JSON5 that support comments.
My new go-to linter, Biome.js, solves this by accepting a biome.jsonc (JSON with comments) as a config file. However, other build tools like Turbo only accept a plain turbo.json file, even though they allow for comments embedded in the JSON. When you open this file in VS Code, you will encounter numerous errors because of the comments.
VS Code opens this file based on its file extension in JSON language mode (see the language indicator in the bottom bar). Interestingly, if you open tsconfig.json, you will notice that VS Code interprets this file as JSON with comments even if it doesn’t contain any comments.
VS Code allows you to associate a file name with a certain language. These file associations are defined in the .vscode/settings.json file:
// .vscode/settings.json
{
"files.associations": {
"turbo.json": "jsonc"
}
}
Now, opening the turbo.json file again will automatically use the right language (JSON with comments). However, keep in mind that you should verify if your tool actually supports JSON with comments. For example, Node.js doesn’t support comments in package.json, and doing so will break your package and potentially all dependent packages.
Frequently Asked Questions
How do you allow comments in JSON?
- Create a
.vscodefolder in your workspace root. - Create a
settings.jsonfile in.vscodefolder. - Create a
"files.associations"top-level object. - Create a property for each file name that you want to treat as JSON comments.
Why doesn’t JSON allow comments?
JSON comments were deliberately left out by the creator Douglas Crockford because he believed comments affected interoperability. However, the format JSON with comments (.jsonc) was created to resolve this issue.
