Como adiciono comentários ao package.json para a instalação do npm?

Eu tenho um arquivo package.json simples e quero adicionar um comentário. Existe uma maneira de fazer isso ou existem hacks para fazer isso funcionar?

{
  "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 como quebra de npm. Eu também tentei // comentários de estilo.

Este foi recentemente discutido na lista de discussão node.js .

De acordo com Isaac Schlueter, que criou o npm:

... a tecla "//" nunca será usada pelo npm para qualquer finalidade e é reservada para comentários ... Se você quiser usar um comentário de várias linhas, poderá usar uma matriz ou vários "//" chaves.

Ao usar suas ferramentas habituais (npm, fios, etc), várias chaves "//" serão removidas. Isso sobrevive:

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

Isso não vai sobreviver:

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

Aqui está outro truque para adicionar comentários em JSON. Desde a:

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

É equivalente a

{"a": 2}

Você pode fazer algo como:

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

Após desperdiçar uma hora em soluções complexas e hacky, encontrei uma solução simples e válida para comentar minha seção de dependências volumosas package.json. Bem 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 maneira, agora é muito fácil para mim rastrear esses pares de dependências / comentários no diff do git commit ou no editor enquanto estiver trabalhando package.json.

E não há ferramentas extras envolvidas, apenas JSON simples e válido.

Espero que isso ajude alguém.

Muitas idéias interessantes.

O que tenho feito é o seguinte:

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

Dessa forma, eu 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

Meus 2 centavos para esta discussão :)

O NPS (scripts de pacote de nós) resolveu esse problema para mim. Permite colocar seus scripts do NPM em um arquivo JS separado, onde você pode adicionar muitos comentários e qualquer outra lógica JS necessária. https://www.npmjs.com/package/nps

Amostra do package-scripts.jsde um dos meus projetos

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'
  }
}

Acabei de fazer uma instalação local npm install nps -save-deve coloquei isso nos meus package.jsonscripts.

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

Você sempre pode abusar do fato de que chaves duplicadas são substituídas. Isto é o que eu acabei de escrever:

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

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

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

No entanto, não está claro se o JSON permite chaves duplicadas (consulte A sintaxe JSON permite chaves duplicadas em um objeto? Parece funcionar com o npm, por isso, corro o risco.

O truque recomendado é usar "//"chaves (da lista de discussão nodejs ). Quando o testei, ele não funcionou com as seções "dependências". Além disso, o exemplo na postagem usa vários"//" chaves, o que implica que o npm não rejeita arquivos JSON com chaves duplicadas. Em outras palavras, o hack acima deve sempre ser bom.

Atualização: Uma desvantagem irritante do hack de chave duplicada é quenpm install --save elimina silenciosamente todas as duplicatas. Infelizmente, é muito fácil esquecer isso e seus comentários bem-intencionados desaparecem.

O "//"hack ainda é o mais seguro que parece. No entanto, os comentários com várias linhas também serão removidos npm install --save.

Eu tenho uma ideia engraçada de hack.

Crie o nome do pacote npm adequadamente como divisor de comentários dependenciese devDependenciesbloqueie no package.json, por exemplox----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 : É necessário adicionar a última linha divisória do comentário com a versão válida, como *no bloco.

Inspirado por esta discussão, aqui está o que estamos usando :

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

Até agora, a maioria dos "hacks" aqui sugerem abusar do JSON. Mas, em vez disso, por que não abusar da linguagem de script subjacente?

Editar A resposta inicial foi colocar a descrição à direita usando # add comments herepara envolvê-la; no entanto, isso não funciona no Windows, porque os sinalizadores (por exemplo, npm run myframework - --myframework-flags) seriam ignorados. Alterei minha resposta para fazê-lo funcionar em todas as plataformas e adicionei alguns recuos 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"
  }
}

Isso vai:

1. Não viole a conformidade com JSON (ou pelo menos não é um hack, e seu IDE não emitirá avisos por fazer coisas estranhas e perigosas)
2. Funciona em várias plataformas (testado no macOS e no Windows, assumindo que funcionaria bem no Linux)
3. Não atrapalha a execução npm run myframework -- --help
4. Produzirá informações significativas ao executar npm run (que é o comando real a ser executado para obter informações sobre os scripts disponíveis)
5. Apresenta um comando de ajuda mais explícito (caso alguns desenvolvedores não estejam cientes de que o npm run apresenta essa saída)
6. Mostrará os comandos E sua descrição ao executar o próprio comando
7. É um pouco legível ao abrir package.json(usando lessou seu IDE favorito)

Aqui está minha opinião sobre os comentários em package.json/bower.json :

Eu tenho package.json.jsque contém um script que exporta o real package.json. A execução do script substitui o antigo package.jsone me diz quais alterações foram feitas, perfeitas para ajudar você a acompanhar as alterações automáticasnpm feitas. Dessa forma, eu posso definir programaticamente quais pacotes eu quero usar.

A tarefa mais recente do grunhido está aqui: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Acabei scriptsassim:

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

Minha intenção aqui não é esclarecer uma linha, apenas ter algum tipo de delimitador entre meus scripts para back-end, front-end, tudo etc.

Eu não sou um grande fã de 1a, 1b, 1c, 2a, ... mas as teclas são diferentes e eu não tenho nenhum problema assim.

Como essa resposta explica, a //chave foi reservada, para que possa ser usada convencionalmente para comentários. O problema com o //comentário é que ele não pode ser usado dependenciese devDependenciescomo dependência regular com uma string como restrição de versão:

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

desencadeia um erro,

npm ERR! código EINVALIDPACKAGENAME

npm ERR! Nome de pacote inválido "//": o nome pode conter apenas caracteres compatíveis com URL

Embora chaves com valores não-string sejam consideradas dependências inválidas e ignoradas com eficiência:

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

Uma dependência em si pode ser comentada da mesma maneira:

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

Como as dependências são classificadas quando o package.json é modificado pelo NPM, é impraticável colocar um comentário acima da dependência a que se refere:

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

A chave de comentário deve ser nomeada de acordo, se se referir a uma linha específica, para não ser movida:

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

Um comentário aplicável a dependência específica pode ser adicionado como parte do semver:

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

Observe que, se a primeira parte anterior ORnão corresponder, um comentário pode ser analisado, por exemplo1.x .

Essas soluções alternativas são compatíveis com todas as versões atuais do NPM (6 e inferiores).

Como a maioria dos desenvolvedores está familiarizada com a documentação baseada em tags / anotações, a convenção que comecei a usar é semelhante. Aqui está uma amostra:

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

Nota: Para os dependencies, devDependenciesseções, etc, as anotações de comentário não pode ser adicionado diretamente acima das dependências de pacotes individuais dentro do objeto de configuração uma vez npmestá esperando a chave para ser o nome de um pacote de npm. Daí a razão para o@comment dependencies .

Nota: Em certos contextos, como no objeto de scripts, alguns editores / IDEs podem reclamar da matriz. No contexto de scripts, o VS Code espera uma sequência para o valor - não uma matriz.

Gosto da maneira no estilo anotação / tag de adicionar comentários ao JSON porque o @símbolo se destaca das declarações normais.

Para resumir todas essas respostas:

1. Adicione um único campo de nível superior chamado //que contém uma sequência de comentários. Isso funciona, mas é péssimo, porque você não pode colocar comentários perto do que eles estão comentando.

2. Adicione vários campos de nível superior começando com // , por exemplo, //dependenciesque contém uma sequência de comentários. Isso é melhor, mas ainda permite que você faça comentários de nível superior. Você não pode comentar dependências individuais.

3. Adicione echocomandos ao seu scripts. Isso funciona, mas é péssimo porque você só pode usá-lo scripts.

Essas soluções também não são muito legíveis. Eles acrescentam uma tonelada de ruído visual e os IDEs não os destacam como comentários.

Eu acho que a única solução razoável é gerar o package.jsonde outro arquivo. A maneira mais simples é escrever seu JSON como Javascript e usar o Node para gravá-lo package.json. Salve este arquivo como package.json.mjs, chmod +xe então você pode simplesmente executá-lo para gerar seu arquivo 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));

Ele usa a //chave para avisar as pessoas de editá-lo. \x40generatedé deliberado. Ele se transforma @generatedempackage.json e significa que alguns sistemas de revisão de código entrará em colapso esse arquivo por padrão.

É uma etapa extra no seu sistema de compilação, mas supera todos os outros hacks aqui.

Como as chaves de comentário duplicadas são removidas, executando as ferramentas package.json (npm, yarn, etc), passei a usar uma versão hash 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 o meu IDE como chave raiz, mas dentro dependenciesdele reclama-se a expectativa de um valor de sequência.

Outro truque. Eu criei um script para ler package.jsoncomo o contexto de um modelo de guidão.

Código abaixo, caso alguém considere essa abordagem útil:

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;
  });
});

arquivo de modelo de guidão 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"

}}}

Para o npm package.json, foram encontradas 2 maneiras (depois de ler esta conversa):

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

Mas com a atualização ou reinstalação do pacote com "--save" ou "--save-dev, comente como" ^ 4.1.0! comentário "no local correspondente será excluído. E tudo isso quebrou a auditoria da NPM.

Minha opinião sobre a frustração de não haver comentários no JSON. Crio novos nós, nomeados para os nós a que eles se referem, mas prefixados com sublinhados. Isso é imperfeito, mas funcional.

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