¿Cómo agrego comentarios a package.json para la instalación de npm?

Tengo un archivo package.json simple y quiero agregar un comentario. ¿Hay alguna manera de hacer esto, o hay algún truco para que esto funcione?

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

El comentario de ejemplo anterior no funciona ya que npm se rompe. También he intentado // comentarios de estilo.

Esto ha sido recientemente discutido en la lista de correo Node.js .

Según Isaac Schlueter, quien creó npm:

... npm nunca utilizará la tecla "//" para ningún propósito, y está reservada para comentarios ... Si desea usar un comentario de varias líneas, puede usar una matriz o múltiples "//" llaves.

Cuando utilice sus herramientas habituales (npm, hilo, etc.) se eliminarán varias teclas "//". Esto sobrevive:

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

Esto no sobrevivirá:

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

Aquí hay otro truco para agregar comentarios en JSON. Ya que:

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

Es equivalente a

{"a": 2}

Puedes hacer algo como:

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

Después de perder una hora en soluciones complejas y extravagantes, he encontrado una solución simple y válida para comentar mi sección de dependencias voluminosas en package.json. Solo así:

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

Cuando se ordena de la misma manera, ahora es muy fácil para mí rastrear estos pares de dependencias / comentarios en git commit diffs o en el editor mientras trabajo package.json.

Y no hay herramientas adicionales involucradas, solo JSON simple y válido.

Espero que esto ayude a cualquiera.

Muchas ideas interesantes

Lo que he estado haciendo es esto:

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

De esta manera, puedo leer los "pseudo-comentarios" en el script mismo, Y también ejecutar algo como lo siguiente, para ver algún tipo de ayuda en la terminal:

npm run about
npm run about:watch

Mis 2 centavos para esta discusión :)

NPS (Node Package Scripts) resolvió este problema por mí. Le permite colocar sus scripts NPM en un archivo JS separado, donde puede agregar comentarios en abundancia y cualquier otra lógica JS que necesite. https://www.npmjs.com/package/nps

Muestra de package-scripts.jsuno de mis proyectos

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

Acabo de hacer una instalación local npm install nps -save-devy puse esto en mis package.jsonscripts.

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

Siempre puede abusar del hecho de que las claves duplicadas se sobrescriben. Esto es lo que acabo de escribir:

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

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

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

Sin embargo, no está claro si JSON permite claves duplicadas (consulte ¿La sintaxis JSON permite claves duplicadas en un objeto? Parece que funciona con npm, así que me arriesgo.

El truco recomendado es usar "//"claves (de la lista de correo de nodejs ). Sin embargo, cuando lo probé, no funcionó con las secciones de "dependencias". Además, el ejemplo en la publicación usa múltiples "//"claves, lo que implica que npm no rechaza los archivos JSON con claves duplicadas. En otras palabras, el truco anterior siempre debe estar bien.

Actualización: Una desventaja molesta del pirateo de claves duplicadas es que npm install --saveelimina silenciosamente todos los duplicados. Desafortunadamente, es muy fácil pasarlo por alto y sus comentarios bien intencionados se han ido.

El "//"truco sigue siendo el más seguro como parece. Sin embargo, los comentarios de varias líneas también se eliminarán npm install --save.

Tengo una idea divertida para hackear.

Cree el nombre del paquete npm adecuadamente como divisor de comentarios para dependenciesy devDependenciesbloquee en package.json, por ejemplox----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 : Debe agregar la última línea divisoria de comentarios con una versión válida como *en el bloque.

Inspirado en este hilo, esto es lo 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"
  }
}

Hasta ahora, la mayoría de los "hacks" aquí sugieren abusar de JSON. Pero en cambio, ¿por qué no abusar del lenguaje de scripting subyacente?

Editar La respuesta inicial fue poner la descripción a la derecha usando # add comments herepara envolverla; sin embargo, esto no funciona en Windows, porque las banderas (por ejemplo, npm ejecutan myframework - --myframework-flags) serían ignoradas. Cambié mi respuesta para que funcione en todas las plataformas, y agregué algunas sangrías para propósitos de legibilidad.

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

Esta voluntad:

1. No rompa el cumplimiento de JSON (o al menos no es un truco, y su IDE no le dará advertencias por hacer cosas extrañas y peligrosas)
2. Funciona multiplataforma (probado en macOS y Windows, suponiendo que funcione bien en Linux)
3. No se interpone en el camino npm run myframework -- --help
4. Producirá información significativa cuando se ejecute npm run(que es el comando real para ejecutar y obtener información sobre los scripts disponibles)
5. Presenta un comando de ayuda más explícito (en caso de que algunos desarrolladores no sean conscientes de que npm run presenta dicha salida)
6. Mostrará los comandos Y su descripción cuando ejecute el comando en sí
7. Es algo legible cuando solo se abre package.json(usando lesso su IDE favorito)

Esta es mi opinión sobre los comentarios dentro de package.json/ bower.json:

Tengo package.json.jsque contiene un script que exporta el real package.json. Ejecutar el script sobrescribe el antiguo package.jsony me dice qué cambios realizó, perfecto para ayudarlo a realizar un seguimiento de los cambios automáticos npmrealizados. De esa manera, incluso puedo definir programáticamente qué paquetes quiero usar.

La última tarea gruñona está aquí: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Terminé con algo scriptsasí:

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

Mi intención aquí no es aclarar una línea, solo tener algún tipo de delimitador entre mis scripts para backend, frontend, todos, etc.

No soy un gran fanático de 1a, 1b, 1c, 2a, ... pero las teclas son diferentes y no tengo ningún problema en absoluto.

Como explica esta respuesta , la //clave estaba reservada, por lo que puede usarse convencionalmente para comentarios. El problema con el //comentario es que no se puede utilizar en dependenciesy devDependenciescomo la dependencia regular con una cadena como la versión restricción:

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

desencadena un error,

npm ERR! código EINVALIDPACKAGENAME

npm ERR! Nombre de paquete "//" no válido: el nombre solo puede contener caracteres compatibles con URL

Aunque las claves con valores que no son cadenas se consideran dependencias no válidas y se ignoran de manera eficiente:

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

Una dependencia en sí misma puede comentarse de la misma manera:

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

Dado que las dependencias se ordenan cuando NPM modifica package.json, no es práctico colocar un comentario sobre una dependencia a la que hace referencia:

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

La clave de comentario debe nombrarse en consecuencia si se refiere a una línea específica, por lo que no se moverá:

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

Se puede agregar un comentario que sea aplicable a dependencias específicas como parte de semver:

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

Tenga en cuenta que si la primera parte anterior ORno coincide, se puede analizar un comentario, por ejemplo 1.x.

Estas soluciones son compatibles con todas las versiones actuales de NPM (6 y anteriores).

Como la mayoría de los desarrolladores están familiarizados con la documentación basada en etiquetas / anotaciones, la convención que comencé a usar es similar. Aquí hay una muestra:

{
  "@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 las dependencies, devDependenciessecciones, etc, las anotaciones de comentarios no se puede añadir directamente encima de las dependencias de los paquetes individuales dentro del objeto de configuración ya npmestá esperando la clave para ser el nombre de un paquete de NPM. De ahí la razón de la @comment dependencies.

Nota: En ciertos contextos, como en el objeto de secuencias de comandos, algunos editores / IDEs pueden quejarse de la matriz. En el contexto de los scripts, VS Code espera una cadena para el valor, no una matriz.

Me gusta la forma de anotación / estilo de etiqueta de agregar comentarios a JSON porque el @símbolo se destaca de las declaraciones normales.

Para resumir todas estas respuestas:

1. Agregue un solo campo de nivel superior llamado //que contiene una cadena de comentarios. Esto funciona pero apesta porque no puedes poner comentarios cerca de lo que comentan.

2. Agregue múltiples campos de nivel superior comenzando // , por ejemplo, //dependenciesque contiene una cadena de comentarios. Esto es mejor, pero solo te permite hacer comentarios de alto nivel. No puedes comentar dependencias individuales.

3. Agrega echocomandos a tu scripts. Esto funciona pero apesta porque solo puedes usarlo scripts.

Estas soluciones tampoco son todas muy legibles. Agregan una tonelada de ruido visual y los IDE no sintaxis los resaltan como comentarios.

Creo que la única solución razonable es generar el package.jsonarchivo desde otro archivo. La forma más simple es escribir su JSON como Javascript y usar Node para escribirlo package.json. Guarde este archivo como package.json.mjs, chmod +xy luego puede ejecutarlo para generar su 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));

Utiliza la //clave para advertir a las personas que no lo editen. \x40generatedes deliberado Se convierte @generateden package.jsony significa que algunos sistemas de revisión de código colapsarán ese archivo de manera predeterminada.

Es un paso adicional en su sistema de compilación, pero supera a todos los otros hacks aquí.

A medida que se eliminan las claves de comentario duplicadas ejecutando las herramientas package.json (npm, yarn, etc.) llegué a usar una versión hash que permite una mejor lectura como múltiples líneas y claves como

"//": {
  "alpaca": "we use the bootstrap version",
  "eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
  "moment-with-locales": "is part of moment"
},

que es 'válido' según mi IDE como clave raíz, pero dentro de dependenciesél se queja esperando un valor de cadena.

Otro truco. Creé un script para leer package.jsoncomo contexto para una plantilla de manillar.

Código a continuación en caso de que alguien encuentre útil este enfoque:

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

archivo de plantilla de manillar 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 npm package.json hemos encontrado 2 formas (después de leer esta conversación):

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

Pero con la actualización o reinstalación del paquete con "--save" o "--save-dev, comente como" ^ 4.1.0! comentario "en el lugar correspondiente se eliminará. Y todo esto romperá la auditoría npm.

Mi opinión sobre la frustración de no hacer comentarios en JSON. Creo nuevos nodos, nombrados por los nodos a los que se refieren, pero con prefijo de guiones bajos. Esto es imperfecto, pero 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"
}