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

380

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.

Will Shaver
fonte
possível duplicata de Posso comentar um arquivo JSON?
precisa saber é o seguinte
17
@YehudaKatz - Não acho que seja uma duplicata, pois esta pergunta é específica para package.jsonarquivos e há uma package.jsonresposta específica na lista de discussão do NodeJS.
Mark Evans
2
Um dos principais desenvolvedores do npm se recusou a considerar o suporte a comentários package.json. Por favor, comente sobre essa questão - talvez possamos mostrar como os comentários podem ser úteis.
Dan Dascalescu
5
Uma única tag <sarcasm />. JSON5 suporta comentários json5.org
Cristian E.

Respostas:

450

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" } 
Igor Soarez
fonte
58
existe uma maneira de documentar o que é cada entrada na seção 'dependências'? o truque "//" não funciona quando é um atributo de 'dependências'.
rynop
8
Observe que o uso de vários comentários, como no primeiro exemplo, { "//": "first", "//": "second"}impede o uso de npm versionoutros utilitários de linha de comando que geralmente analisam JSON inteiro e descartam as chaves duplicadas em processo.
Jkub.g
60
É preciso estar ciente de que "//" só pode ser usado na raiz do package.jsonobjeto. Por exemplo, { "dependencies": { "//": "comment?" }}é inválido, mas { "//": "comment!", "dependencies":{}}é válido.
David_p 7/07
52
Mesmo Douglas Crockford não tem nenhum problema em colocar comentários nos arquivos de configuração JSON. A situação com o NPM é tola para dizer o mínimo.
Muhammad Rehan Saeed
5
na minha experiência, a "//"chave e seu valor são apagados eventualmente. existe uma maneira de ter comentários permanentes?
pruett
116

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": "*"
  }
}
Jonathan Warden
fonte
12
Isso também funciona no nível do pacote específico. Por exemplo. "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x". Então, sim, "eca", como diz o ColinE, e também "obrigado", como diz o ColinE.
juanpaco
22
Observe que esse hack impede que você altere de package.jsonmaneira programática, digamos, npm version 1.2.3para aumentar a versão - as entradas redundantes serão removidas do JSON resultante.
Jkub.g
16
Este é um mau conselho, porque a ordem em que um objeto é interpretado não é garantida. Por exemplo, em algumas situações, o seu exemplo pode acabar com um ser 1 em vez de 2.
Jo Sprague
6
@mpen O risco é que não há garantia de que o código que analisa o JSON o faça sequencialmente.
Jo Sprague
7
Para o registro, a RFC diz explicitamente: "Quando os nomes em um objeto não são exclusivos, o comportamento do software que recebe esse objeto é imprevisível. Muitas implementações relatam apenas o par sobrenome / valor. Outras implementações relatam um erro ou falha para analisar o objeto, e algumas implementações relatam todos os pares nome / valor, incluindo duplicatas. "
Alan Tam
106

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.

gkond
fonte
11
Dessa forma, faz mais sentido e mantém as coisas limpas.
Hitesh Sahu 05/10
4
Obrigado por uma solução não-hacky que é tecnicamente válida e semanticamente útil.
Roy Tinker
5
Para comentários sobre scripts, por que não fornecer scripts de "ajuda", por exemplo "scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
pico de
11
@peak obrigado! A única desvantagem que vejo é que os scripts reais serão misturados com comentários.
gkond
11
@gkond obrigado por isso. Faz mais sentido para mim.
Robin Winslow
20

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 :)

Felipe N Moura
fonte
inteligente, eu gosto disso
KorreyD
14

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"
}
Jim Doyle
fonte
13

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.

Philipp Claßen
fonte
11
O "//"hack não funciona dentro de devDependencies. O NPM tenta resolver um caminho UNC.
Dmitry S.
Obrigado pela atualização da frase, mas novamente ele não pode comentar o mochaatributo. Apenas ele pode adicionar mais de um e será usado pelo npm no final.
vusan
Eu odeio admitir isso - mas eu gosto disso melhor do que o "//"
roocell
9

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.

Liao San Kai
fonte
6
sim, ele está realmente disponível: npmjs.com/package/x----x----x
revelt
9
Fiquei empolgado com essa resposta, mas depois que eu corri npm install(usando o npm 5) minhas chaves duplicadas foram removidas automaticamente :(
Eric Majerus
@EricMajerus oops ~, npm5 quebrar meu coração também :(
Liao San Kai
8

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"
  }
}
thisismydesign
fonte
7

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)
Marc Trudel
fonte
Argh, na verdade, no Windows seria simplesmente ignorar bandeiras, de modo 3. Não é verdade: /
Marc Trudel
Torne o Windows cmd compatível com: em &&vez de, ;para que o primeiro comando se torne:"help": "echo 'Display help information (this screen)' && npm run",
phil_lgr 5/17
11
Sim, foi o que acabei fazendo. Boa pegada!
Marc Trudel
3
Funciona apenas na scriptsseção package.jsonHá muitas outras coisas.
Rolf
Corrigir. Então, novamente, o que mais você sentiria a necessidade de documentar lá?
Marc Trudel
6

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

MarZab
fonte
Eu acho que essa é a resposta "correta" de várias maneiras (tarefa de remover comentários com correções diferenciais para explicar as alterações pós-remoção) - no entanto, tenho a sensação de que o peso adicional de uma tarefa difícil não é o que algumas pessoas são after, Para projetos pequenos, provavelmente é melhor manter um arquivo externo para comentários e usar os scrpts do NPM (evita tarefas de criação por completo). Para projetos grandes, você provavelmente está usando algum tipo de executor de tarefas, portanto essa abordagem parece sólida. Entre os dois, acho que talvez adaptar a sugestão "//" ao paladar (evitando os pontos de dor específicos) seja o melhor que pode ser feito.
Enull
11
Eu gosto dessa idéia, mas como alguém perguntou no essencial, e o caso em que você está modificando o pacote.json original por meio de npm install --saveou --save-dev?
Isócrono
sim, eu continuo perdendo esses comentários; não há nenhuma boa solução, eu costumava olhar para diffs git e atualizar meu js arquivo após atualização
MarZab
1

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.

maxime1992
fonte
1

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).

Estus Flask
fonte
1

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.

Danny Hurlburt
fonte
1

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.

Timmmm
fonte
0

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.

Clemens Tolboom
fonte
sim b / c você não pode realmente mas a //chave em todos os lugares, não é realmente um bom substituto para comentários, especialmente quando os comentários podem ter bom destaque de sintaxe com um editor etc.
Alexander Mills
0

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"

}}}
forforf
fonte
0

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.

Alex Gurin
fonte
isso não tentaria instalar pacotes nomeados del-commente envify-comment?
Beni Cherniavsky-Paskin
-1

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"
}
rmirabelle
fonte
usar start_commentseria melhor, porque então ele vai pedir em ordem alfabética
Alexander Mills