Repository navigation
Support comments in package.json #8751
Description
Sorry if there's an existing issue for this but I only found #793 which is closed. I believe this is the status quo:
- Users really want this. Look at this StackOverflow question - over 600 upvotes!
- None of the current workarounds are very good.
- It would be a (minor) breaking change.
The current workarounds are:
- You can officially add a single top-level key
"//". This sucks because I want more than one comment! - Various hacks to put comments inside script commands. This sucks because it only works for scripts, and it's also terrible.
- Use duplicate keys. This sucks because JSON's duplicate key handling is not well defined, and NPM will delete the duplicate keys if it modifies
package.json. - Generate
package.jsonfrom another file. This is probably the best solution right now but it means you can'tnpm install -Dstuff and it's an extra step.
These all really suck. This is an age-old feature request wanted by many many people.
As far as I understand it the reason NPM "can't" be changed to just support package.json5 or package.jsonc is that third party tools would get confused when they try to read package.json and it's not there. I can think of two solutions:
- When you run
npm, as well as generatingpackage-lock.jsonit also generatespackage.json(and this should be.gitignored if you also havepackage.json{5,c}). Are there any third party tools that want to modifypackage.json? - Just ask those third party tools to support
package.json{5,c}too. This is clearly a smaller problem than not allowing comments in NPM's most important config file forever.
Reacted by Josef Budniakiewicz, Andrii Oriekhov, Patr, Alexander Cerutti, Henry, Aydoğan, Garrett Reynolds and JonasDoe
Reacted by Josef Budniakiewicz, Andrii Oriekhov and Garrett Reynolds
Activity
ljharb commentedon Nov 20, 2025
It's not just third-party tools, it's javascript itself. Before any format should be supported by anyone, parsing and serializing it should be built in to node, and broadly available (meaning, shipped for years first)
Timmmm commentedon Nov 20, 2025
Why? What third party tools would actually need to write to
package.json{c,5)?ljharb commentedon Nov 20, 2025
Tons of tools write to package.json, including all of the package managers.
Timmmm commentedon Nov 20, 2025
Ok but this would be entirely optional; you can still use
package.jsonif you need to work with those third party tools. Or they can be updated!Simbiat commentedon Nov 20, 2025
Hm, why not support JSON5 or JSONC and have logic which will check for JSON5/JSONC file first and then for JSON one, if it does not exist? That way you won't even need to break anything. In fact, you can even generate JSON file from JSON5 similar to what Caddy web server can do when you pass it certain types of configs.
ljharb commentedon Nov 22, 2025
@Timmmm if it is possible for users to do then it is mandatory for tools to support it.
@Simbiat for the same reason - there's no such thing as a built-in way to work with those formats in any platform.
Timmmm commentedon Nov 22, 2025
I don't see why. It would be nice, but certainly not mandatory.
Why is "built-in" a requirement? There's no built-in way to read JSON in many platforms.
ljharb commentedon Nov 23, 2025
Let me rephrase - if the tool wants to be relevant, it must support it.
The only platforms that matter for npm are browsers and node, which have provided a built-in way to read and write JSON for well over two decades.
v-mragunandhan24 commentedon Nov 24, 2025
@Timmmm Thanks for taking the time to share your idea! New ideas are always appreciated and are better suited for our RFC repo instead since that's the right place in order to get more attention from the rest of the team and the community.
Can you create an RRFC in that repo?
Timmmm commentedon Nov 24, 2025
Sure I started writing one but then I had a search and found a 5-year old one that is almost exactly what I would have written: npm/rfcs#291
Basically support
package.json5and automatically convert it topackage.jsonwhen you run npm commands (I think that could also be optional and controlled by a key inpackage.json5).It has overwhelming support. What would be the next step? Write an actual RFC?
v-mragunandhan24 commentedon Nov 27, 2025
@Timmmm Thanks Tim for creating the RFC. I'm closing this as this is transferred to RFC.
michalius commentedon Oct 28, 2026
I'd also like to express support for this feature.
The inability to document individual fields in
package.jsonis a real maintainability limitation, especially in monorepos where manifests often contain important architectural and tooling decisions.JSONC seems like a reasonable opt-in approach, as long as compatibility with Node.js and existing tooling is preserved.
I understand this issue has been redirected to npm/rfcs#291, and I agree that the broader discussion belongs there. Hopefully, a practical solution can eventually emerge from that proposal.