Como faço para adicionar comentários ao pacote.json para npm install?

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

É equivalente a

{"a": 2}

Podes fazer algo como:

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

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

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

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

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

1. 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)
2. Works cross platform (testada em macOS e windows, assumindo que funcionaria muito bem no Linux)
3. não se mete no caminho da corrida npm run myframework -- --help
4. 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)
5. irá mostrar tanto os comandos como a sua descrição ao executar o próprio comando
6. é de certa forma legível ao abrir package.json (Usando less ou o seu IDE favorito)

Muitas ideias interessantes.

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

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