strip-json-comments makes JSON with comments parseable again

Comments in JSON, and why the fix is whitespace

The problem the package solves is that JSON has no comment syntax, and `JSON.parse` rejects a file that contains one. The README shows what becomes possible:

{
	// Rainbows
	"unicorn": /* ❤ */ "cake"
}

The mechanism is a text transformation rather than a parse and reserialise. The module will replace single-line comments and multi-line block comments with whitespace, and the README states the reason directly: this allows JSON error positions to remain as close as possible to the original source.

That is the design decision worth understanding, because a parser that removed comments and re-serialised would produce a shorter string with different offsets. If the file is broken, the parser error would then point at a line and column that no longer corresponds to anything the author can find. Replacing comments with spaces keeps every byte position after the comment unchanged, so a syntax error is reported where it actually is in the file the human wrote.

The practical consequence is that a config with a typo reports the typo's real location, and a config with a comment on the same line as the error does not shift the reported column.

One function, two options

The API is deliberately tiny. `stripJsonComments(jsonString, options?)` accepts a string with JSON and returns a string without comments.

There are two options, and both have defaults that matter.

`trailingCommas` is a boolean, default `false`, and it strips trailing commas in addition to comments. Trailing commas are the other common way a hand-edited JSON file stops being valid JSON, and the default keeps the function focused on the thing its name says.

`whitespace` is a boolean, default `true`, and it replaces comments and trailing commas with whitespace instead of stripping them entirely. So with the defaults, the output is the same length as the input and the comment characters are gone, and with `whitespace: false` the comments and commas are removed and the string gets shorter.

The two options interact, and the combination that keeps offsets intact is the default one: comments replaced by whitespace, and trailing commas left alone unless you ask for them. If your file has trailing commas and you want the error positions preserved, turn `trailingCommas` on and leave `whitespace` on.

Installing and using it

The install is a single npm command:

npm install strip-json-comments

And the usage is a call around the string you want to parse:

import stripJsonComments from 'strip-json-comments';

const json = `{
	// Rainbows
	"unicorn": /* ❤ */ "cake"
}`;

JSON.parse(stripJsonComments(json));
//=> {unicorn: 'cake'}

Two things about the shape of that example are worth noting. The import is a default import from an ES module, which follows from the package metadata, where the type is module and the exports field points at `./index.js`. And the result of the call is fed straight into `JSON.parse`, which is the point of the exercise: the module produces valid JSON, and the standard parser does the rest.

There is also a CLI for this module, strip-json-comments-cli, for the cases where the file has to be converted on disk rather than in memory, and there are Gulp, Grunt and Broccoli plugins for the same job inside a build.

An ESM package with no dependencies and a Node floor

The package manifest is short, and it settles the questions you would otherwise have to guess at.

	"type": "module",
	"exports": "./index.js",
	"types": "./index.d.ts",
	"sideEffects": false,
	"engines": {
		"node": ">=14.16"
	},
	"scripts": {
		"test": "xo && ava && tsd",

So the module is ESM only, with no CommonJS entry point, and it needs Node 14.16 or newer. The `sideEffects: false` flag tells a bundler that importing it has no side effects, which is what lets a bundler tree-shake it away when it is unused. The `files` array ships only `index.js` and `index.d.ts`, and the TypeScript declarations are tested with `tsd` rather than merely written.

The licence is MIT, the author is Sindre Sorhus, and the package declares a funding link to his GitHub sponsors page.

The one practical consequence of the ESM only design is worth flagging for anyone adopting it into an existing CommonJS codebase. There is no `require` entry point, so a CommonJS project has to reach it through dynamic import, or the surrounding project has to move to modules. That is a one line change for a modern project and a genuine obstacle for an older one.

The test and benchmark setup tells you what is checked

The development dependencies are the usual Sindre Sorhus set, and the scripts show what is actually verified.

The test script runs `xo` for linting, `ava` for the unit tests and `tsd` for the type definition tests, in that order, and a failure in any of them stops the run. The benchmark is separate and uses `matcha` against a `benchmark.js` file in the repository root, run with `npm run bench`.

The repository also carries fixtures you would expect: `sample.json` and `sample-big.json` for the test and benchmark runs, `index.test-d.ts` for the type tests, and `test.js` for the unit tests.

What the README does not spell out is worth knowing, because it is the natural question for a text transformer. It does not document how a comment sequence inside a string literal is treated, and it does not claim to validate the result. So the place to confirm the edge cases is the fixtures and the test file, not the readme.

Where this sits, and what it is not

The honest framing of this package is that it is a narrow, well-behaved text transformation, and its narrowness is a feature.

What it is not is a JSONC parser. It does not build a document, it does not validate, and it will happily return a string that is still not valid JSON, which `JSON.parse` will then reject on the next line. If your requirement is a config format that permits comments and you need the tool to tell you that the rest of the file is broken, you want a parser that understands the extended format, and this module is not that.

It is also not a general purpose JSON editor or formatter. There is a sibling project, strip-css-comments, for the same trick on CSS, and the CLI and build plugin variants of this one. The related list in the README is short for that reason.

The alternative approach, when you need more than a text pass, is to keep the configuration in a format with a real parser and validate it at load time, so a broken file is reported with a file name and a position rather than as a JSON parse error at the point of use. The difference in approach is the difference between transforming text and understanding a document, and for a file that a human edits by hand, the second one tells you more when something is wrong.

Editorial conclusion

Adopt strip-json-comments when your configuration files carry comments and something downstream insists on strict JSON, particularly when a human needs to see accurate error positions in a broken config. Do not adopt it as a JSONC parser, because it does not validate anything and it will not tell you that the result is not valid JSON. Verify first that the files you feed it contain only comments in positions JSON tolerates, that the whitespace default is what you want, since switching it off changes the offsets, and that the version you install is v5.0.3, an ESM only package requiring Node 14.16 or newer.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/strip-json-comments on GitHub