Discussion on: How to add comments to package.json?

[Danny Hurlburt]

The convention I have started using is the following:

{
  "@comment dependencies": [
    "These are the comments for the `dependencies` section.",
    "The name of the section being commented is included in the key after the `@comment` 'annotation' to ensure the keys are unique.",
    "That is, using just \"@comment\" would not be sufficient if you need to add another comment at the same level.",
    "Because JSON doesn't allow a multiline string or understand a line continuation operator, just use an array for each line of the comment.",
    "Since this is embedded in JSON, the keys should be unique.",
    "Otherwise JSON validators, such as ones built into IDE's, will complain.",
    "Or some tools, such as running `npm install something --save`, will rewrite the `package.json` file but with duplicate keys removed.",
    "",
    "@package react - Using an `@package` 'annotation` could be how you add comments specific to particular packages."
  ],
  "dependencies": {
    ...
  },
  "scripts": {
    "@comment build": "This comment is about the build script.",
    "build": "...",

    "@comment start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "start": "...",

    "@comment test": "This comment is about the test script.",
    "test": "..."
  }
}

Note: For the dependencies, devDependencies, etc sections, the comment annotations can't be added directly above the individual package dependencies inside the configuration object since npm is expecting the key to be the name of an npm package. Hence the reason for the @comment dependencies.

Note: In certain contexts, such as in the scripts object, some editors/IDEs may complain about the array. In the scripts context, VS Code expects a string for the value -- not an array.

A top-level comment annotation can also be added similar to what Francesco presented.

{
  "@comment": {
    "dependencies": "we use jQuery because of reasons",
    "repository": "our beloved repo",
    "license": "we love MIT, so why not",
    "devDependencies": {
      "@babel/core": "it's @ version 7.2.2 because of...",
      "gulp-rename": "why not"
    }
  }
}

However, I like keeping the comment as close as possible to what it applies to.

[Remi Kristelijn]

I really like this idea; it should be a standard. Let's discuss and vote up in npm / cli / issues / #677

[Danny Hurlburt]

I have changed a few things in how I add comments to package.json. Here is an example of the new convention I am following:

{
  "@comment dependencies": [
    "These are the comments for the `dependencies` section.",
    "The name of the section being commented is included in the key after the `@comment` 'annotation' to ensure the keys are unique.",
    "That is, using just \"@comment\" would not be sufficient if you need to add another comment at the same level.",
    "Because JSON doesn't allow a multiline string or understand a line continuation operator, just use an array for each line of the comment.",
    "Since this is embedded in JSON, the keys should be unique.",
    "Otherwise JSON validators, such as ones built into IDE's, will complain.",
    "Or some tools, such as running `npm install something --save`, will rewrite the `package.json` file but with duplicate keys removed.",
    "The section below is an object with properties where each property matches the NPM package's name.",
    "The comment about the package is the value of the property. This property may be a single string or an array of strings.",
    {
      "react": "Comment about this package."
    }
  ],
  "dependencies": {
    ...
  },
  "@comment scripts": {
    "build: [
      "This comment is about the build script. It may be a string or any array of strings.",
      "In the old convention, the comment was within `scripts`, next to the script it applied to.",
      "In this new convention, it is in its own section.",
      "This was done so that the comments don't appear as a script to a tool that reads the `scripts` section."
    ],
    "start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
  },
  "scripts": {
    "build": "...",
    "start": "...",
    "test": "..."
  }
}