What's the proper way to include comments in package.json files?

Other Questions NPM
1

I’m working on a Node.js project and need to document some configuration choices in my package.json file. I tried adding standard JavaScript comments but npm throws errors when I run commands.

Here’s what I attempted:

{
  "name": "web-application",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "react": "^18.0.0",
    "axios": "^1.0.0"
  },
  "devDependencies": {
    "jest": "^29.0.0"
    // "eslint": "^8.0.0" - disabled for now
  }
}

Both // and /* */ comment styles cause npm to fail. Are there any workarounds or alternative approaches to add explanatory notes directly in the package.json? I want to document why certain packages are included or excluded without breaking the JSON format. Any suggestions would be helpful.

2

yep, json doesn’t allow comments. instead, try adding a _comment field. for example: _comment: "eslint is disabled for now". npm skips it, but you get to keep track of your notes. alternatively, consider putting details in a README.md.

3

JSON doesn’t allow comments, so you’re stuck with workarounds. The // key trick works well as a fake comment field in package.json. It looks like a real comment, unlike those underscore prefixes. Just drop "//": "eslint disabled due to configuration conflicts" right next to your dependencies. I’ve also used the scripts section for docs by adding stuff like "info:dependencies": "echo 'React for UI, Axios for HTTP requests'". Team members can run it with npm, so it’s executable documentation. Some people stuff notes into the keywords array too, but don’t do that if you’re publishing the package.

4

I’ve had good luck with a separate package-comments.json file next to your main package.json. Keeps everything organized without making the actual package file messy. You can mirror your package.json structure and add detailed notes about dependencies, scripts, or config decisions. Some teams get creative with the description field - toss in quick notes about major dependencies. Works great for smaller projects. The underscore prefix thing works too, but I like external docs better when you’re dealing with larger codebases that need tons of comments.