如何为package.json添加注释以进行npm install？

Question

我有一个简单的package.json文件，我想添加一条评论。有没有办法做到这一点，还是有任何黑客可以使这项工作？

{
  "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 */
  }
}

上面的示例评论不适用于npm中断。我也试过//风格评论。

Answer 1

最近在node.js mailing list。

中对此进行了讨论

创建npm的Isaac Schlueter表示：

  

... npm永远不会将“//”键用于任何目的，并保留用于注释...如果要使用多行注释，可以使用数组或多个“ //“钥匙。

使用常用工具（npm，纱线等）时，将删除多个“//”键。幸存下来：

{ "//": [ 
  "first line", 
  "second line" ] } 

这将无法生存：

{ "//": "this is the first line of a comment", 
  "//": "this is the second line of the comment" } 

Answer 2

这是另一个在JSON中添加注释的黑客攻击。时间：

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

相当于

{"a": 2}

您可以执行以下操作：

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

Answer 3

在复杂和hacky解决方案上浪费了一个小时之后，我发现了package.json中评论我庞大的依赖关系部分的简单而有效的解决方案。就像这样：

{
  "name": "package name",
  "version": "1.0",
  "description": "package description",
  "scripts": {
    "start": "npm install && node server.js"
  },
  "scriptsComments": {
    "start": "Runs development build on a local server configured by server.js"
  },
  "dependencies": {
    "ajv": "^5.2.2"
  },
  "dependenciesComments": {
    "ajv": "JSON-Schema Validator for validation of API data"
  }
}

当以相同的方式排序时，我现在很容易在使用package.json时在git commit diffs或编辑器中跟踪这些依赖关系/注释对。

没有额外的工具，只是简单而有效的JSON。

希望这有助于任何人。

Answer 4

您始终可以滥用重复密钥被覆盖的事实。这就是我刚刚写的：

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

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

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

然而，目前尚不清楚JSON是否允许重复密钥（参见 Does JSON syntax allow duplicate keys in an object?。它似乎适用于npm，所以我冒了风险。

推荐的黑客是使用"//"密钥（来自nodejs mailing list）。当我测试它时，它不适用于＆＃34;依赖＆＃34;但是，部分。此外，帖子中的示例使用多个"//"键，这意味着npm不会拒绝具有重复键的JSON文件。换句话说，上面的黑客应该总是很好。

更新：重复密钥破解的一个恼人的缺点是npm install --save默默地消除了所有重复项。不幸的是，它很容易被忽视，你的善意评论也不见了。

"//"黑客仍然是最安全的。但是，npm install --save也会删除多行注释。

Answer 5

NPS（Node Package Scripts）为我解决了这个问题。允许您将NPM脚本放入单独的JS文件中，您可以在其中添加注释以及您需要的任何其他JS逻辑。 https://www.npmjs.com/package/nps

我的某个项目的package-scripts.js示例

module.exports = {
  scripts: {
    // makes sure e2e webdrivers are up to date
    postinstall: 'nps webdriver-update',

    // run the webpack dev server and open it in browser on port 7000
    server: 'webpack-dev-server --inline --progress --port 7000 --open',

    // start webpack dev server with full reload on each change
    default: 'nps server',

    // start webpack dev server with hot module replacement
    hmr: 'nps server -- --hot',

    // generates icon font via a gulp task
    iconFont: 'gulp default --gulpfile src/deps/build-scripts/gulp-icon-font.js',

    // No longer used
    // copyFonts: 'copyfiles -f src/app/glb/font/webfonts/**/* dist/1-0-0/font'
  }
}

我刚刚进行了本地安装npm install nps -save-dev并将其放入我的package.json脚本中。

"scripts": {
    "start": "nps",
    "test": "nps test"
}

Answer 6

我有一个有趣的黑客想法。

适当创建npm包名称作为package.json中dependencies和devDependencies块的注释分隔符，例如x----x----x

{
    "name": "app-name",
    "dependencies": {
        "x----x----x": "this is the first line of a comment",
        "babel-cli": "6.x.x",
        "babel-core": "6.x.x",
        "x----x----x": "this is the second line of a comment",
        "knex": "^0.11.1",
        "mocha": "1.20.1",
        "x----x----x": "*"
    }
}

注意：必须在块中添加带有*等有效版本的最后一条评论分隔线。

Answer 7

许多有趣的想法。

我一直在做的是：

{
  ...
  "scripts": {
    "about": "echo 'Say something about this project'",
    "about:clean": "echo 'Say something about the clean script'",
    "clean": "do something",
    "about:build": "echo 'Say something about building it'",
    "build": "do something",
    "about:watch": "echo 'Say something about how watch works'",
    "watch": "do something",
  }
  ...
}

这样我就可以读取脚本本身的“伪注释”，并运行类似下面的内容，在终端中查看某种帮助：

npm run about
npm run about:watch

我讨论的2点：）

Answer 8

到目前为止，大多数＆＃34; hacks＆＃34;这里建议滥用JSON。但相反，为什么不滥用底层脚本语言？

编辑初始响应是使用<dimen name="design_navigation_icon_size" tools:override="true"></dimen> 将描述放在右边以进行包装;但是，这在Windows上不起作用，因为标志（例如npm run myframework - --myframework-flags）将被忽略。我更改了我的响应，使其适用于所有平台，并添加了一些缩进以便于阅读。

# add comments here

这将：

1. 不破坏JSON合规性（或者至少它不是黑客攻击，并且你的IDE不会因为做出奇怪，危险的事情而给你警告）
2. 跨平台工作（在macOS和windows上测试，假设它在Linux上运行正常）
3. 不妨碍{ "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" } }
的运行
4. 运行npm run myframework -- --help时输出有意义的信息（这是运行的实际命令以获取有关可用脚本的信息）
5. 提供更明确的帮助命令（如果某些开发人员不知道npm run会出现这样的输出）
6. 运行命令本身时将显示命令及其描述
7. 只需打开npm run（使用package.json或您喜欢的IDE）即可阅读

Answer 9

这是我对package.json / bower.json内的评论的看法：

我的package.json.js包含导出实际package.json的脚本。运行该脚本会覆盖旧的package.json并告诉我它所做的更改，非常适合帮助您跟踪所做的自动更改npm。这样我甚至可以以编程方式定义我想要使用的包。

最新的grunt任务在这里： https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Answer 10

总结所有这些答案：

1. 添加一个名为//的单个顶级字段，其中包含注释字符串。这行得通，但是很烂，因为您不能在评论中添加评论。

2. 添加多个顶级字段以 //开头，例如//dependencies包含注释字符串。这样比较好，但是仍然只允许您进行顶级评论。您不能评论各个依赖项。

3. 向您的echo添加scripts命令。可以，但是很烂，因为您只能在scripts中使用它。

这些解决方案也不是很可读。它们会增加大量的视觉噪音，并且IDE不会将语法突出显示为注释。

我认为唯一合理的解决方案是从另一个文件生成package.json。最简单的方法是将JSON编写为JavaScript，然后使用Node.js将其写入package.json。将此文件另存为package.json.mjs，chmod +x，然后可以运行它来生成package.json。

#!/usr/bin/env node

import { writeFileSync } from "fs";

const config = {
  // TODO: Think of better name.
  name: "foo",
  dependencies: {
    // Bar 2.0 does not work due to bug 12345.
    bar: "^1.2.0",
  },
  // Look at these beautify comments. Perfectly syntax highlighted, you
  // can put them anywhere and there no risk of some tool removing them.
};

writeFileSync("package.json", JSON.stringify({
    "//": "This file is \x40generated from package.json.mjs; do not edit.",
    ...config
  }, null, 2));

它使用//键来警告人们不要对其进行编辑。 \x40generated是故意的。它在@generated中变成了package.json，这意味着某些代码检查系统默认会折叠该文件。

这是构建系统中的一个额外步骤，但它击败了这里的所有其他黑客。

Answer 11

我做了一些你们可能喜欢的事情：

名称中的// //表示对我的评论：

  "//":"Main and typings are used till ES5",
  "//main": "build/index",
  "//typings": "build/index",

Answer 12

受此主题启发，we are using如下：

{
  "//dependencies": {
    "crypto-exchange": "Unified exchange API"
  },
  "dependencies": {
    "crypto-exchange": "^2.3.3"
  },
  "//devDependencies": {
    "chai": "Assertions",
    "mocha": "Unit testing framwork",
    "sinon": "Spies, Stubs, Mocks",
    "supertest": "Test requests"
  },
  "devDependencies": {
    "chai": "^4.1.2",
    "mocha": "^4.0.1",
    "sinon": "^4.1.3",
    "supertest": "^3.0.0"
  }
}

Answer 13

我最后得到的是scripts：

  "scripts": {
    "//-1a": "---------------------------------------------------------------",
    "//-1b": "---------------------- from node_modules ----------------------",
    "//-1c": "---------------------------------------------------------------",
    "ng": "ng",
    "prettier": "prettier",
    "tslint": "tslint",
    "//-2a": "---------------------------------------------------------------",
    "//-2b": "--------------------------- backend ---------------------------",
    "//-2c": "---------------------------------------------------------------",
    "back:start": "node backend/index.js",
    "back:start:watch": "nodemon",
    "back:build:prod": "tsc -p backend/tsconfig.json",
    "back:serve:prod": "NODE_ENV=production node backend/dist/main.js",
    "back:lint:check": "tslint -c ./backend/tslint.json './backend/src/**/*.ts'",
    "back:lint:fix": "yarn run back:lint:check --fix",
    "back:check": "yarn run back:lint:check && yarn run back:prettier:check",
    "back:check:fix": "yarn run back:lint:fix; yarn run back:prettier:fix",
    "back:prettier:base-files": "yarn run prettier './backend/**/*.ts'",
    "back:prettier:fix": "yarn run back:prettier:base-files --write",
    "back:prettier:check": "yarn run back:prettier:base-files -l",
    "back:test": "ts-node --project backend/tsconfig.json node_modules/jasmine/bin/jasmine ./backend/**/*spec.ts",
    "back:test:watch": "watch 'yarn run back:test' backend",
    "back:test:coverage": "echo TODO",
    "//-3a": "---------------------------------------------------------------",
    "//-3b": "-------------------------- frontend ---------------------------",
    "//-3c": "---------------------------------------------------------------",
    "front:start": "yarn run ng serve",
    "front:test": "yarn run ng test",
    "front:test:ci": "yarn run front:test --single-run --progress=false",
    "front:e2e": "yarn run ng e2e",
    "front:e2e:ci": "yarn run ng e2e --prod --progress=false",
    "front:build:prod": "yarn run ng build --prod --e=prod --no-sourcemap --build-optimizer",
    "front:lint:check": "yarn run ng lint --type-check",
    "front:lint:fix": "yarn run front:lint:check --fix",
    "front:check": "yarn run front:lint:check && yarn run front:prettier:check",
    "front:check:fix": "yarn run front:lint:fix; yarn run front:prettier:fix",
    "front:prettier:base-files": "yarn run prettier \"./frontend/{e2e,src}/**/*.{scss,ts}\"",
    "front:prettier:fix": "yarn run front:prettier:base-files --write",
    "front:prettier:check": "yarn run front:prettier:base-files -l",
    "front:postbuild": "gulp compress",
    "//-4a": "---------------------------------------------------------------",
    "//-4b": "--------------------------- cypress ---------------------------",
    "//-4c": "---------------------------------------------------------------",
    "cy:open": "cypress open",
    "cy:headless": "cypress run",
    "cy:prettier:base-files": "yarn run prettier \"./cypress/**/*.{js,ts}\"",
    "cy:prettier:fix": "yarn run front:prettier:base-files --write",
    "cy:prettier:check": "yarn run front:prettier:base-files -l",
    "//-5a": "---------------------------------------------------------------",
    "//-5b": "--------------------------- common ----------------------------",
    "//-5c": "---------------------------------------------------------------",
    "all:check": "yarn run back:check && yarn run front:check && yarn run cy:prettier:check",
    "all:check:fix": "yarn run back:check:fix && yarn run front:check:fix && yarn run cy:prettier:fix",
    "//-6a": "---------------------------------------------------------------",
    "//-6b": "--------------------------- hooks -----------------------------",
    "//-6c": "---------------------------------------------------------------",
    "precommit": "lint-staged",
    "prepush": "yarn run back:lint:check && yarn run front:lint:check"
  },

我的意图不是澄清一行，只是为了在我的脚本之间设置某种分隔符，用于后端，前端，所有等等。

我不是1a，1b，1c，2a，......的忠实粉丝，但关键是不同的，我没有任何问题。

Answer 14

另一个黑客。我创建了一个脚本来读取package.json作为车把模板的上下文。

下面的代码，以防有人觉得这种方法有用：

const templateData = require('../package.json');
const Handlebars = require('handlebars');
const fs = require('fs-extra');
const outputPath = __dirname + '/../package-json-comments.md';
const srcTemplatePath = __dirname + '/package-json-comments/package-json-comments.hbs';

Handlebars.registerHelper('objlist', function() {
  // first arg is object, list is a set of keys for that obj
  const obj = arguments[0];
  const list = Array.prototype.slice.call(arguments, 1).slice(0,-1);

  const mdList = list.map(function(k) {
    return '* ' + k + ': ' + obj[k];
  });

  return new Handlebars.SafeString(mdList.join("\n"));
});

fs.readFile(srcTemplatePath, 'utf8', function(err, srcTemplate){
  if (err) throw err;
  const template = Handlebars.compile(srcTemplate);
  const content = template(templateData);

  fs.writeFile(outputPath, content, function(err) {
    if (err) throw err;
  });
});

车把模板文件package-json-comments.hbs

### Dependency Comments
For package: {{ name }}: {{version}}

#### Current Core Packages
should be safe to update
{{{objlist dependencies
           "@material-ui/core"
           "@material-ui/icons"
           "@material-ui/styles"
}}}

#### Lagging Core Packages
breaks current code if updated
{{{objlist dependencies
           "amazon-cognito-identity-js"
}}}

#### Major version change
Not tested yet
{{{objlist dependencies
           "react-dev-utils"
           "react-redux"
           "react-router"
           "redux-localstorage-simple"

}}}

Answer 15

由于删除了重复的注释键，运行了package.json工具（npm，yarn等），我开始使用哈希版本，可以更好地阅读多行和键，如

"//": {
  "alpaca": "we use the bootstrap version",
  "eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
  "moment-with-locales": "is part of moment"
},

根据我的IDE作为根密钥“有效”，但在dependencies内，它会抱怨期望字符串值。

Answer 16

由于大多数开发人员都熟悉基于标签/注释的文档，因此我开始使用的约定是相似的。这是一种味道：

{
  "@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'/'tag' to ensure the keys are unique.",
    "That is, using just \"@comment\" would not be sufficient to keep keys unique if you need to add another comment at the same level.",
    "Because JSON doesn't allow a multi-line string or understand a line continuation operator/character, 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.",
      "When using npm, as opposed to yarn, to run the script, be sure to add ` -- ` before adding the options.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "start": "...",

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

注意：对于dependencies，devDependencies等部分，由于npm需要键，因此注释注释不能直接添加到配置对象内各个程序包依赖项的上方。是npm软件包的名称。因此，@comment dependencies的原因。

注意：在某些情况下，例如在脚本对象中，某些编辑器/ IDE可能会抱怨该数组。在脚本上下文中，VS Code期望使用字符串作为值，而不是数组。

我喜欢将注释添加到JSON的注释/标签样式方式，因为@符号在常规声明中脱颖而出。

Answer 17

对于npm的package.json，我发现了两种方法（阅读此对话后）：

  "devDependencies": {
    "del-comment": [
      "some-text"
    ],
    "del": "^5.1.0 ! inner comment",
    "envify-comment": [
      "some-text"
    ],
    "envify": "4.1.0 ! inner comment"
  }

但是使用“ --save”或“ --save-dev”更新或重新安装软件包时，将出现诸如“ ^ 4.1.0”的注释！相应位置的“注释”将被删除。所有这些都会破坏npm审核。

Answer 18

我喜欢这样：

  "scripts": {
    "⏬⏬⏬ Jenkins Build - in this order ⏬⏬⏬                                                                                                  ": "",
    "purge": "lerna run something",
    "clean:test": "lerna exec --ignore nanana"
}

命令名称中有多余的空格，因此在Visual Studio Code的 NPM脚本插件中，您的外观会更好。

Answer 19

如this answer所述，//键是保留键，因此可以按常规方式用于注释。 //注释的问题在于，它不能在dependencies和devDependencies中作为带有字符串作为版本约束的常规依赖项使用：

"dependencies": {
  "//": "comment"
}

触发错误，

  

npm错误！代码EINVALIDPACKAGENAME

     

npm错误！无效的包名称“ //”：名称只能包含URL友好的名称   字符

尽管具有非字符串值的键被认为是无效的依赖关系，并被有效地忽略：

"dependencies": {
  "//": ["comment"]
}

依赖项本身可以用相同的方式注释掉：

"dependencies": {
  "foo": ["*", "is not needed now"],
}

由于在NPM修改package.json时对依赖项进行了排序，因此在其引用的依赖项之上放置注释是不切实际的：

"dependencies": {
  "bar": "*",
  "//": ["should be removed in 1.x release"]
  "foo": "*",
}

如果注释键指向特定行，则应相应命名，因此不会被移动：

"dependencies": {
  "bar": "*",
  "foo": "*",
  "foo //": ["should be removed in 1.x release"]
}

适用于特定依赖项的注释可以作为semver的一部分添加：

"dependencies": {
  "bar": "*",
  "foo": "* || should be removed in 1.x release"
}

请注意，如果OR之前的第一部分不匹配，则可以解析注释，例如1.x。

这些变通办法与所有当前NPM版本（6及更低版本）兼容。

Answer 20

我对JSON中没有评论感到沮丧。我创建了新的节点，以它们引用的节点命名，但以下划线为前缀。这不完美，但功能齐全。

orElseThrow