How do I add comments to package.json for npm install?


Here is another hack for adding comments in JSON. Since:

{"a": 1, "a": 2}

Is equivalent to

{"a": 2}

You can do something like:

  "devDependencies": "'mocha' not needed as should be globally installed",
  "devDependencies" :  {
    "should": "*"

I've got a simple package.json file and I want to add a comment. Is there a way to do this, or are there any hacks to make this work?

  "name": "My Project",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "express": "3.x",
    "mongoose": "3.x"
  "devDependencies" :  {
    "should": "*"
    /* "mocha": "*" not needed as should be globally installed */

The example comment above doesn't work as npm breaks. I've also tried // style comments.

Here's my take on comments within package.json / bower.json:

I have package.json.js that contains a script that exports the actual package.json. Running the script overwrites the old package.json and tells me what changes it made, perfect to help you keep track of automatic changes npm made. That way I can even programatically define what packages I want to use.

The latest grunt task is here:

So far, most "hacks" here suggest to abuse JSON. But instead, why not abuse the underlying scripting language?

Edit The initial response was putting the description on the right using # add comments here to wrap it; however, this does not work on Windows, because flags (e.g. npm run myframework -- --myframework-flags) would be ignored. I changed my response to make it work on all platforms, and added some indents for readability purposes.

 "scripts": {
    "help": "       echo 'Display help information (this screen)';          npm run",
    "myframework": "echo 'Run myframework binary';                          myframework",
    "develop": "    echo 'Run in development mode (with terminal output)';  npm run myframework"
    "start": "      echo 'Start myFramework as a daemon';                   myframework start",
    "stop":  "      echo 'Stop the myFramework daemon';                     myframework stop"
    "test": "echo \"Error: no test specified\" && exit 1"

This will:

  1. Not break JSON compliance (or at least its not a hack, and your IDE will not give you warnings for doing strange, dangerous stuff)
  2. Works cross platform (tested on macOS and windows, assuming it would work just fine on Linux)
  3. Does not get in the way of running npm run myframework -- --help
  4. Will output meaningful info when running npm run (which is the actual command to run to get information about available scripts)
  5. Presents a more explicit help command (in case some devs are not aware that npm run presents such output)
  6. Will show both the commands AND its description when running the command itself
  7. Is somewhat readable when just opening package.json (using less or your favorite IDE)

You can always abuse the fact that duplicated keys are overwritten. This is what I just wrote:

"dependencies": {
  "grunt": "...",
  "grunt-cli": "...",

  "api-easy": "# Here is the pull request:",
  "api-easy": "git://..."

  "grunt-vows": "...",
  "vows": "..."

However, it is not clear whether JSON allows duplicated keys (see Does JSON syntax allow duplicate keys in an object?. It seems to work with npm, so I take the risk.

The recommened hack is to use "//" keys (from the nodejs mailing list). When I tested it, it did not work with "dependencies" sections, though. Also, the example in the post uses multiple "//" keys, which implies that npm does not reject JSON files with duplicated keys. In other words, the hack above should always be fine.

Update: One annoying disadvantage of the duplicated key hack is that npm install --save silently eliminates all duplicates. Unfortunately, it is very easy to overlook it and your well-intentioned comments are gone.

The "//" hack is still the safest as it seems. However, multi-line comments will be removed by npm install --save, too.