我有一个简单的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休息。 我也试过//样式的注释。
这最近已在讨论Node.js的邮件列表 。
根据艾萨克Schlueter的是谁创造NPM：
......在“//”键永远不会被NPM可用于任何目的，并保留征求意见...如果你想使用多行注释，你可以使用数组或多个“//”键。
当使用常规工具（NPM，丝等）多个“//”键将被删除。 这种生存：
{ "//": [
"first line",
"second line" ] }
这将无法生存：
{ "//": "this is the first line of a comment",
"//": "this is the second line of the comment" }
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": "*"
}
}
在复杂和哈克解决方案，浪费一小时后，我发现自己在评论我笨重的依赖性节一个非常简单的，优雅的和有效的解决方案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的承诺不同之处或在编辑器工作时package.json 。
而且没有额外的工具参与，只是简单和有效的JSON。
希望这可以帮助任何人。
您可以随时滥用这种重复键被覆盖的事实。 这是我刚写的：
"dependencies": {
"grunt": "...",
"grunt-cli": "...",
"api-easy": "# Here is the pull request: https://github.com/...",
"api-easy": "git://..."
"grunt-vows": "...",
"vows": "..."
}
但是，目前尚不清楚JSON是否允许重复键（见不JSON语法允许重复键对象中的？ 。这似乎与故宫工作，所以我冒这个险。
该recommened黑客是使用"//"键（从的NodeJS邮件列表 ）。 当我测试了它，它并没有与“依赖性”的部分工作，虽然。 此外，在后的例子中使用多个"//"键，这意味着NPM并不拒绝具有重复键JSON文件。 换句话说，上述黑客应该总是被罚款。
更新：复制的钥匙破解的一个恼人的缺点是， npm install --save默默地消除了所有重复。 不幸的是，它很容易被忽视，而你的善意意见都没有了。
在"//"黑客仍然是最安全的，因为它似乎。 然而，多行注释将被删除npm install --save了。
NPS（节点软件包脚本）解决了这个问题对我来说。 让你把你的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"
}
我有一个有趣的黑客的想法。
创建NPM包名称适当地作为用于评论分频器dependencies和devDependencies中的package.json块，例如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": "*"
}
}
注意 ：必须最后评论分隔线添加具有类似有效版本*块。
很多有趣的想法。
我一直在做的是这样的：
{
...
"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分钱小费此讨论:)
到目前为止，大多数“黑客”在这里建议滥用JSON。 而是，为什么不滥用潜在的脚本语言？
编辑最初的反应是把描述使用权# add comments here把它包起来; 然而，这并不在Windows上工作，因为标志（如故宫运行myframework - --myframework-标志）将被忽略。 我改变了我的反应，使其在所有平台上工作，并增加了可读性一些缩进。
{
"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"
}
}
这将：
npm run myframework -- --help npm run （这是实际的命令来运行，以获得有关可用脚本的信息） package.json （使用less或者您喜欢的IDE） 下面是我采取的内部意见package.json / bower.json ：
我有package.json.js包含出口的实际脚本package.json 。 运行该脚本将覆盖旧package.json ，并告诉我，它所做的修改，完善，以帮助您跟踪自动更改npm制造。 这样，我甚至可以编程定义什么包我想使用。
最新的咕噜任务是在这里： https://gist.github.com/MarZab/72fa6b85bc9e71de5991
我结束了一个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，巨大的风扇......但关键是不同的，我没有任何问题都这样。
至于被删除运行的package.json工具（NPM，纱线等），重复的评论钥匙我来使用散列版本，它允许更好的阅读为多行和键，如
"//": {
"alpaca": "we use the bootstrap version",
"eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
"moment-with-locales": "is part of moment"
},
这是“有效”根据我的IDE的根密钥，但内dependencies它抱怨期待一个字符串值。
另一个黑客。 我创建了一个脚本来读取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"
}}}
通过这个线程启发，这里就是我们使用 ：
{
"//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"
}
}
我承担起在JSON没有意见挫折。 我创建新的节点，命名为他们指的是节点，但用下划线前缀。 这是不完美的，但功能。
{
"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"
}
由于这个答案解释， //键被保留，所以它可以以传统的征求意见中。 这个问题//评论是，它不能被使用dependencies ，并devDependencies一个用字符串作为版本约束规则的依赖：
"dependencies": {
"//": "comment"
}
触发一个错误，
NPM ERR！ 代码EINVALIDPACKAGENAME
NPM ERR！ 无效的包名“//”：名称只能包含URL友好字符
虽然与非字符串值的键被认为是无效的依赖，有效地忽略了：
"dependencies": {
"//": ["comment"]
}
一个依赖本身可以注释掉以同样的方式：
"dependencies": {
"foo": ["*", "is not needed now"],
}
从什么时候开始的package.json由NPM修改相关性进行排序，这是不切实际的地方它是指依赖上述评论：
"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或更低）兼容。
