Como faço para adicionar comentários ao pacote.json para npm install?
{
"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 */
}
}
O Comentário de exemplo acima não funciona à medida que o MPN se quebra. Eu também tentei / / estilo comentários.
12 answers
Isto foi discutido recentemente no nó .js mailing list.
De acordo com Isaac Schlueter, que criou o npm:... a chave "/ / " nunca será usada por npm para qualquer finalidade, e está reservada para Comentários ... Se você quiser usar um comentário de várias linhas, você pode usar um array ou várias teclas"//".
Ao usar as suas ferramentas habituais (npm, fio, etc), várias teclas "//" serão removidas. Isto sobrevive:
{ "//": [
"first line",
"second line" ] }
Isto não vai resultar. sobreviver:
{ "//": "this is the first line of a comment",
"//": "this is the second line of the comment" }
{"a": 1, "a": 2}
É equivalente a
{"a": 2}
Podes fazer algo como:
{
"devDependencies": "'mocha' not needed as should be globally installed",
"devDependencies" : {
"should": "*"
}
}
package.json
. Assim:
{
"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"
}
}
Quando ordenado da mesma forma, agora é muito fácil para mim rastrear estes pares de dependências/comentários, seja no git commit diffs ou no editor enquanto trabalho com package.json
.
E nenhuma ferramenta extra envolvida, apenas JSON simples e válido.
Espero que isto ajude alguém."dependencies": {
"grunt": "...",
"grunt-cli": "...",
"api-easy": "# Here is the pull request: https://github.com/...",
"api-easy": "git://..."
"grunt-vows": "...",
"vows": "..."
}
No entanto, não é claro se o JSON permite chaves duplicadas (ver a sintaxe do JSON permite chaves duplicadas num objecto?. Parece funcionar com o MPN, por isso corro o risco.
O hack reiniciado é usar as chaves {[[1]} (da lista de correio nodejs ). Quando eu testei, ele não funcionou com seções de "dependências", no entanto. Além disso, o exemplo na o post usa várias teclas "//"
, o que implica que o npm não rejeita ficheiros JSON com chaves duplicadas. Em outras palavras, o hack acima deve ser sempre bom.
Update: uma desvantagem irritante do hack de chave duplicado é que npm install --save
elimina silenciosamente todos os duplicados. Infelizmente, é muito fácil ignorá-lo e os seus comentários bem intencionados desapareceram.
npm install --save
, muito.
O NPS ('Node Package Scripts') resolveu este problema por mim. Permite - lhe colocar os seus scripts NPM num ficheiro JS separado, onde poderá adicionar comentários abundantes e qualquer outra lógica JS que necessite. https://www.npmjs.com/package/nps
Amostra do package-scripts.js
de um dos meus projectos
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'
}
}
Fiz uma instalação local npm install nps -save-dev
e coloquei isto nos meus scripts package.json
.
"scripts": {
"start": "nps",
"test": "nps test"
}
Crie o nome do pacote npm adequadamente como separador de comentários para dependencies
e devDependencies
no Pacote.json, por exemplo 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": "*"
}
}
Nota : deve adicionar a última linha do separador de comentários com uma versão válida como *
em bloco.
package.json
/ bower.json
:
Tenho package.json.js
que contém um guião que exporta o real {[[0]}. A execução do programa substitui o antigo package.json
e diz - me quais as alterações que ele fez, perfeito para o ajudar a controlar as alterações automáticas npm
feitas. Dessa forma, posso até programaticamente definir quais pacotes eu quero usar.
Editar a resposta inicial foi colocar a descrição à direita, usando # add comments here
para a embrulhar; contudo, isto não funciona no Windows, porque as opções (por exemplo, o MPN executa o meu quadro -- -- -- o meu quadro-bandeiras) seriam ignoradas. Eu mudei minha resposta para fazê-lo funcionar em todas as plataformas, e adicionei alguns travessões para fins de legibilidade.
{
"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"
}
}
Isto ... will:
- Não quebre a conformidade JSON (ou pelo menos não é um hack, e a sua IDE não lhe dará Avisos por fazer coisas estranhas e perigosas)
- Works cross platform (testada em macOS e windows, assumindo que funcionaria muito bem no Linux)
- não se mete no caminho da corrida
npm run myframework -- --help
- irá produzir informação significativa ao executar
npm run
(que é o comando real a executar para obter informações sobre os programas disponíveis)
Apresenta uma ajuda mais explícita comando (no caso de alguns devs não estarem cientes de que a execução do npm apresenta tal resultado)
- irá mostrar tanto os comandos como a sua descrição ao executar o próprio comando
- é de certa forma legível ao abrir
package.json
(Usandoless
ou o seu IDE favorito)
Muitas ideias interessantes.
O que tenho feito é isto:{
...
"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",
}
...
}
Desta forma posso ler os "pseudo-comentários" no próprio script, e também executar algo como o seguinte, para ver algum tipo de Ajuda no terminal:
npm run about
npm run about:watch
Os meus 2centes para esta discussão:]
Acabei com um scripts
Assim:
"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"
},
A minha intenção aqui não é esclarecer uma linha, apenas ter algum tipo de delimitador entre os meus guiões para infra-estrutura, interface, tudo, etc.
Não sou grande fã de 1a, 1b, 1c, 2a,.. mas as chaves são diferentes e eu não tenho nenhum problema assim.{
"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"
}
Como as teclas duplicadas dos comentários são removidas em execução do pacote.JSON tools (npm, fio, etc) eu vim a usar uma versão hashed que permite uma melhor leitura como várias linhas e chaves como
"//": {
"alpaca": "we use the bootstrap version",
"eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
"moment-with-locales": "is part of moment"
},
Que é' válido ' de acordo com a minha IDE como chave raiz, mas dentro de dependencies
queixa-se de esperar um valor de cadeia de caracteres.