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

package.json que es

Question

Tengo un archivo package.json simple y quiero agregar un comentario. ¿Hay una manera de hacer esto, o hay algún truco para hacer 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 como npm breaks. También he intentado // comentarios de estilo.

Answer 1

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

Tengo package.json.js que contiene un script que exporta el package.json real. La ejecución de la secuencia de comandos 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 esa manera, incluso puedo definir qué paquetes quiero usar.

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

Answer 2

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

Answer 3

Como las claves de comentarios duplicados se eliminan al ejecutar las herramientas package.json (npm, yarn, etc.) llegué a usar una versión con hash que permite una mejor lectura ya que varias 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 las dependencies se queja de que espera un valor de cadena.

Answer 4

Después de perder una hora en soluciones complejas y complejas, encontré una solución bastante simple, elegante y válida para comentar mi sección de dependencias voluminosas en package.json . Al igual que esto:

{
"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 se trabaja con package.json .

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

Espero que esto ayude a cualquiera.

Answer 5

Esto se ha discutido recientemente en la lista de correo de node.js.

Según Isaac Schlueter quien creó npm:

... la tecla "//" nunca será utilizada por npm para ningún propósito, y se reserva para comentarios ... Si desea usar un comentario de varias líneas, puede usar una matriz o varios "//" llaves.

Cuando utilice sus herramientas habituales (npm, hilados, 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" }

Answer 6

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

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 marcas (por ejemplo, npm run myframework - --myframework-flags) se ignorarán. 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"
}
}

Esta voluntad:

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

Answer 7

Mi opinión sobre la frustración de no comentar en JSON. Creo nuevos nodos, nombrados para los nodos a los que hacen referencia, pero con el prefijo subraya. 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"
}

Answer 8

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 en sí, 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 2centos para esta discusión :)

Answer 9

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

Answer 10

Siempre se 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, por lo que me arriesgo.

El truco recomendado es usar las teclas "//" (de la lista de correo de nodejs ). Sin embargo, cuando lo probé, no funcionaba con las secciones de "dependencias". Además, el ejemplo de la publicación utiliza varias teclas "//" , lo que implica que npm no rechaza los archivos JSON con claves duplicadas. En otras palabras, el truco anterior siempre debería estar bien.

Actualización: una desventaja molesta del hack de la clave duplicada 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 hack "//" sigue siendo el más seguro que parece. Sin embargo, los comentarios multilínea también serán eliminados por npm install --save .

Answer 11

Tengo una idea divertida de hackear.

Cree el nombre del paquete npm de manera adecuada como divisor de comentarios para las dependencies y devDependencies bloque en package.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 divisoria del último comentario con una versión válida como * en el bloque.

Answer 12

Terminé con un scripts como ese:

 "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, todos, etc.

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