如何为 package.json 添加注释以进行 npm 安装？答案

【问题标题】：How do I add comments to package.json for npm install?如何为 package.json 添加注释以进行 npm 安装？
【发布时间】：2012-12-22 16:41:01
【问题描述】：

我有一个简单的 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 中断时不起作用。我也试过 // 样式 cmets。

【问题讨论】：

Can I comment a JSON file? 的可能重复项
@YehudaKatz - 我不认为这是重复的，因为这个问题是针对 package.json 文件的，并且在 NodeJS 邮件列表上有一个 package.json 特定的答案。
核心 npm 开发人员之一有 refused 考虑在 package.json 中支持 cmets。请对此问题发表评论 - 也许我们可以展示 cmets 的用处。
一个标签。 JSON5 支持 cmets json5.org
更一般地说，Can comments be used in JSON?（规范问题）

标签： comments npm

【解决方案1】：

最近在Node.js mailing list 上讨论了这个问题。

根据创建 npm 的 Isaac Schlueter 所说：

... "//" 键永远不会被 npm 用于任何目的，并且是为 cmets 保留的... 如果您想使用多行注释，您可以使用数组或多个 " //" 键。

使用常用工具（npm、yarn 等）时，多个“//”键将被删除。这仍然存在：

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

这将无法生存：

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

【讨论】：

有没有办法记录“依赖”部分中的每个条目是什么？ “//”技巧在其属性为“依赖项”时不起作用。
请注意，在第一个示例中使用多个 cmets { "//": "first", "//": "second"} 会阻止您使用 npm version 和其他命令行实用程序，这些实用程序通常会重新解析整个 JSON 并丢弃正在处理的重复键。
必须知道，“//”只能在package.json 对象的根处使用。例如{ "dependencies": { "//": "comment?" }} 无效但{ "//": "comment!", "dependencies":{}} 有效。
即使是 Douglas Crockford 也可以将 cmets 放入 JSON 配置文件中。 NPM 的情况至少可以说是愚蠢的。
根据我的经验，"//" 键及其值最终会被清除。有没有办法拥有永久的 cmets？

【解决方案2】：

在复杂而老套的解决方案上浪费了一个小时后，我找到了既简单又有效的解决方案，可以在 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"
  }
}

当以相同的方式排序时，我现在可以很容易地在 Git 提交差异或编辑器中跟踪这些依赖项/cmets 对，同时使用文件 package.json。

并且不涉及额外的工具，只是简单有效的 JSON。

【讨论】：

感谢技术上有效且语义上有用的非 hacky 解决方案。
关于脚本的cmets，为什么不提供“帮助”脚本，例如"scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
@peak 谢谢！我看到的唯一缺点是实际脚本将与 cmets 混合。
为我工作......我将它与使用数组 [] 结合起来用于多行 cmets。就像@Igor Soarez 的回答一样。

【解决方案3】：

免责声明：您可能不应该使用此 hack。请参阅下面的 cmets。

这是在 JSON 中添加 cmets 的另一个技巧。自：

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

相当于

{"a": 2}

你可以这样做：

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

【讨论】：

这也适用于特定的包级别。例如。 "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x"。所以，是的，正如 ColinE 所说的“糟糕”，以及 ColinE 所说的“谢谢”。
请注意，尽管此 hack 会阻止您以编程方式更改 package.json，例如通过 npm version 1.2.3 来提升版本 - 多余的条目将从生成的 JSON 中删除。跨度>
这是个坏建议，因为无法保证对象的解释顺序。例如，在某些情况下，您的示例可能以 1 而不是 2 结束。
@mpen 风险在于无法保证解析 JSON 的代码会按顺序执行。
作为记录，RFC 明确表示：“当对象中的名称不唯一时，接收此类对象的软件的行为是不可预测的。许多实现报告姓氏/值仅对。其他实现会报告错误或无法解析对象，并且某些实现会报告所有名称/值对，包括重复项。"

【解决方案4】：

我一直在这样做：

{
  ...
  "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",
  }
  ...
}

这样，我既可以读取脚本本身中的“pseudo-cmets”，并且也可以运行类似以下的内容，以在终端中查看某种帮助：

npm run about
npm run about:watch

【讨论】：

在我看来，这是最好的选择，因为它允许用户在不需要实际打开package.json 的情况下获取有关命令的信息。

【解决方案5】：

NPS（节点包脚本）为我解决了这个问题。它允许您将 NPM 脚本放入单独的 JavaScript 文件中，您可以在其中添加大量 cmets 和您需要的任何其他 JavaScript 逻辑。 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"
}

【讨论】：

这是我最喜欢的答案。而且我用[nps]做的比较多，可以用js代码来控制命令的流向。

【解决方案6】：

受此线程的启发，这是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"
  }
}

【讨论】：

我更喜欢这个，虽然邮件列表说“//”是保留的，这意味着“//”没有保留

【解决方案7】：

您总是可以滥用重复键被覆盖的事实。这是我刚刚写的：

"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）。但是，当我对其进行测试时，它不适用于“依赖项”部分。此外，帖子中的示例使用了多个 "//" 键，这意味着 npm 不会拒绝具有重复键的 JSON 文件。换句话说，上面的 hack 应该总是没问题的。

更新：重复密钥破解的一个恼人的缺点是npm install --save 会默默地消除所有重复项。不幸的是，它很容易被忽视，而你好心的 cmets 已经消失了。

"//" hack 看起来仍然是最安全的。不过多行的 cmets 也会被npm install --save 移除。

【讨论】：

"//" hack 在 devDependencies 中不起作用。 NPM 尝试解析 UNC 路径。
感谢更新语句，但它再次无法评论 mocha 属性。只是它可以添加多个，最后会被 npm 使用。
我不想承认——但我比“//”更喜欢这个

【解决方案8】：

我有一个有趣的 hack 想法。

为文件 package.json 中的 dependencies 和 devDependencies 块创建一个合适的 npm 包名称作为注释分隔符，例如 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": "*"
    }
}

注意：您必须在最后一行添加有效版本的评论分隔线，例如块中的*。

【讨论】：

是的，它实际上是可用的：npmjs.com/package/x----x----x
对这个答案很兴奋，但是在我运行 npm install（使用 npm 5）之后，我的重复键被自动删除了 :(
@EricMajerus 哎呀~，npm5 也伤透了我的心 :(

【解决方案9】：

到目前为止，这里的大多数“黑客”都建议滥用 JSON。但是，为什么不滥用底层脚本语言呢？

编辑最初的反应是把描述放在右边，用# add comments here包裹它；但是，这在 Windows 上不起作用，因为标志（例如，npm run myframework -- --myframework-flags）将被忽略。我更改了我的回复以使其适用于所有平台，并添加了一些缩进以提高可读性。

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

这将：

不破坏 JSON 合规性（或者至少它不是黑客攻击，并且您的 IDE 不会因为您执行奇怪、危险的事情而向您发出警告）
跨平台工作（在 macOS 和 Windows 上测试，假设它可以在 Linux 上正常工作）
不妨碍运行npm run myframework -- --help
在运行npm run 时将输出有意义的信息（这是运行以获取可用脚本信息的实际命令）
提供更明确的帮助命令（以防某些开发人员不知道 npm run 提供此类输出）
在运行命令本身时将同时显示命令和其描述
刚打开 package.json（使用 less 或您最喜欢的 IDE）时有点可读性

【讨论】：

Argh，实际上在 Windows 上它只会忽略标志，所以 3. 不正确：/
使其 windows cmd 兼容：&& 而不是 ;，因此第一个命令变为："help": "echo 'Display help information (this screen)' && npm run",
是的，这就是我最终所做的。好收获！
它只适用于scripts 部分。 package.json 有很多其他的东西。
正确。再说一遍，你觉得还有什么需要在里面记录的？

【解决方案10】：

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

{
  "@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 IDEs, 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": {
    ...
  },
  "@comment scripts": {
    "build": "This comment is about the build script.",
    "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."
    ],
    "test": "This comment is about the test script.",
  },
  "scripts": {
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

注意：对于dependencies、devDependencies等部分，注释注释不能直接添加到配置对象内的单个包依赖项之上，因为npm希望键是名称一个 npm 包。这就是@comment dependencies 的原因。

我喜欢将 cmets 添加到 JSON 的注释/标记样式方式，因为 @ 符号从普通声明中脱颖而出。

较早的推荐

以下是我之前的推荐。它为脚本内联 cmets，但我开始意识到这些 cmets 在某些工具中显示为“命令”（在 VS Code > Explorer > NPM 脚本部分）。最新的建议没有受此问题的影响，但脚本 cmets 不再位于同一位置。

{
  "@comment dependencies": [
    ...
  ],
  "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": "..."
  }
}

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

【讨论】：

这是我遇到的最好的解决方案，因为它允许将每个评论与特定的键相关联。这比 "//" 方法更好地将事物置于上下文中，因此注释可以存在于它所引用的对象外部而不会造成任何混淆。这对于记录该工具需要严格规则（例如 eslint）的配置树非常有用，如果它发现任何外来的东西就会失败。

【解决方案11】：

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

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

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

【讨论】：

我认为这在很多方面都是“正确”的答案（使用差异补丁剥离 cmets 以解决剥离后变化的任务）——但是，我觉得增加的重量grunt task 不是某些人所追求的，对于小型项目，可能最好保留一个外部文件以供评论并使用 NPM scrpts（完全避免构建任务）。对于大型项目，您可能正在使用某种形式的任务运行器，因此这种方法似乎很可靠。在这两者之间，我认为也许根据口味调整“//”建议（避免一个人的特定痛点）是可以做到的最好的。
我喜欢这个想法，但正如有人问的要点，您通过npm install --save 或--save-dev 修改原始package.json 的情况如何？
是的，我一直想念那些 cmets；没有好的解决方案，我曾经查看 git diffs 并在更新后更新我的 .js 文件

【解决方案12】：

总结所有这些答案：

添加一个名为// 的单个顶级 字段，其中包含一个注释字符串。这行得通，但很糟糕，因为你不能将 cmets 放在他们正在评论的东西附近。
添加多个顶级字段以//开头，例如//dependencies 包含注释字符串。这更好，但它仍然只允许您制作顶级 cmets。您不能评论单个依赖项。
将echo 命令添加到您的scripts。这可行，但很糟糕，因为您只能在 scripts 中使用它。

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

我认为唯一合理的解决方案是从另一个文件生成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 是故意的。它在package.json 中变成了@generated，这意味着一些代码审查系统会默认折叠该文件。

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

【讨论】：

我确实喜欢这种方法，但是又出现了运行npm i ... 并在源文件中保持依赖关系最新的问题

【解决方案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……的忠实粉丝，但按键不同，我完全没有这样的问题。

【讨论】：

【解决方案14】：

正如this answer 解释的那样，// 键是保留的，因此它可以按惯例用于 cmets。 // 注释的问题在于它不实用，因为它不能多次使用。 package.json 自动更新会删除重复键：

"//": "this comment about dependencies stays",
"dependencies": {}
"//": "this comment disappears",
"devDependencies": {}

另一个问题是 // 注释不能在 dependencies 和 devDependencies 中使用，因为它被视为常规依赖项：

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

npm 错误！代码 EINVALIDPACKAGENAME

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

一种适用于 NPM 但不适用于 Yarn 的解决方法是使用非字符串值：

"dependencies": {
  "foo": ["unused package"],
}

在 NPM 和 Yarn 中有效的解决方法是作为 semantic versioning 的一部分添加的评论：

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

请注意，如果OR 之前的第一部分不匹配，则可以解析来自评论的版本，例如1.x.

需要注释但未安装的软件包应移至另一个键，例如dependencies //:

"dependencies //": {
  "baz": "unused package",
}

【讨论】：

【解决方案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 内它抱怨需要一个字符串值。

【讨论】：

是的，b/c 你真的不能，但// 键无处不在，它并不是 cmets 的一个很好的替代品，尤其是当 cmets 可以使用编辑器等进行很好的语法突出显示时。

【解决方案16】：

对于 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！相应位置的comment”将被删除。这一切都会破坏npm审计。

【讨论】：

这不会尝试安装名为 del-comment 和 envify-comment 的软件包吗？

【解决方案17】：

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

这个//在名字里面意味着它是对我的评论：

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

【讨论】：

【解决方案18】：

另一个黑客

我创建了一个脚本来读取文件 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() {
  // The first argument is an object, and the 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"

}}}

【讨论】：

【解决方案19】：

我喜欢这个：

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

命令名称中有多余的空格，所以在 Visual Studio Code 的 NPM Scripts 插件中你会更好看。

【讨论】：

或许终于找到了合理的使用emojis的方式？

【解决方案20】：

我对 JSON 中没有 cmets 的挫败感的看法。我创建了新节点，以它们引用的节点命名，但带有下划线前缀。这是不完美的，但很实用。

{
  "name": "myapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "react": "^16.3.2",
    "react-dom": "^16.3.2",
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "__start": [
        "a note about how the start script works"
    ],
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject"
  },
  "__proxy": [
    "A note about how proxy works",
    "multilines are easy enough to add"
  ],
  "proxy": "http://server.whatever.com:8000"
}

【讨论】：

使用start_comment 会更好，因为它会按字母顺序排列