Cómo puedo añadir comentarios al paquete.json para la instalación de npm?

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

{"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 hacky me he encontrado una solución bastante simple, elegante y válida para comentar mi sección de dependencias voluminosas en package.json. 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 ordenan 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 con package.json.

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

Espero que esto ayude a alguien.

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 (ver ¿La sintaxis JSON permite claves duplicadas en un objeto?. Parece que funciona con npm, así que me arriesgo.

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

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

El hackeo "//" sigue siendo el más seguro como parece. Sin embargo, los comentarios multilínea serán eliminados por npm install --save, demasiado.

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

Muestra del package-scripts.js de uno 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-dev y puse esto en mis scripts package.json.

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

Tengo una idea graciosa.

Cree el nombre del paquete npm adecuadamente como divisor de comentarios para dependencies y devDependencies bloque en el paquete.json, por ejemplo 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 : Debe agregar la línea divisora del último comentario con una versión válida como * en el bloque.

Aquí está mi opinión sobre los comentarios dentro package.json / bower.json:

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

La última tarea de grunt está aquí: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

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 here para envolverla; sin embargo, esto no funciona en Windows, porque las banderas (por ejemplo, npm run myframework my myframework-flags) serían ignoradas. Cambié mi respuesta para que funcionara en todas las plataformas y agregué algunas sangrías para facilitar la lectura.

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

Esto will:

1. No romper 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 funcionaría bien en Linux)
3. No se interpone en el camino de correr npm run myframework -- --help
4. Generará información significativa al ejecutar npm run (que es el comando real a ejecutar para obtener información sobre los scripts disponibles)
5. Presenta una ayuda más explícita comando (en caso de que algunos desarrolladores no sean conscientes de que la ejecución de npm presenta dicha salida)
6. Mostrará tanto los comandos COMO su descripción al ejecutar el comando en sí
7. Es algo legible al abrir package.json (usando less o su IDE favorito)

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 propio script, Y también ejecutar algo como lo siguiente, para ver algún tipo de ayuda en terminal:

npm run about
npm run about:watch

Mis 2cents para esta discusión:)

Terminé con un scripts así:

  "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 delimitadores entre mis scripts para backend, frontend, all, etc.

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

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

Como las claves de comentario duplicadas se eliminan del paquete en ejecución.herramientas json (npm, yarn, etc.) Llegué a usar una versión con hash que permite una mejor lectura como múltiples líneas y teclas 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 se queja esperando un valor de cadena.