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

380

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.

Will Shaver
fuente
posible duplicado de ¿Puedo comentar un archivo JSON?
Yehuda Katz
17
@YehudaKatz: no creo que sea un duplicado, ya que esta pregunta es específica de los package.jsonarchivos y hay una package.jsonrespuesta específica en la lista de correo de NodeJS.
Mark Evans
2
Uno de los principales desarrolladores de npm se ha negado a considerar el soporte de comentarios en package.json. Por favor comente sobre ese tema, tal vez podamos mostrar cuán útiles pueden ser los comentarios.
Dan Dascalescu
55
Una sola etiqueta <sarcasmo />. JSON5 admite comentarios json5.org
Cristian E.

Respuestas:

450

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" } 
Igor Soarez
fuente
58
¿hay alguna manera de documentar qué es cada entrada en la sección 'dependencias'? el truco "//" no funciona cuando es un atributo de 'dependencias'.
rynop
8
Tenga en cuenta que el uso de múltiples comentarios como en el primer ejemplo le { "//": "first", "//": "second"}impide usar npm versiony otras utilidades de línea de comandos que generalmente reparan JSON completo y descartan las claves duplicadas en el proceso.
jakub.g
6060
Hay que tener en cuenta que "//" solo se puede utilizar en la raíz del package.jsonobjeto. Por ejemplo, { "dependencies": { "//": "comment?" }}no es válido pero { "//": "comment!", "dependencies":{}}es válido.
david_p
52
Incluso Douglas Crockford no tiene problemas para poner comentarios en los archivos de configuración JSON. La situación con NPM es tonta por decir lo menos.
Muhammad Rehan Saeed
55
en mi experiencia, la "//"clave y su valor se borran eventualmente. ¿Hay alguna manera de tener comentarios permanentes?
pruett
116

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": "*"
  }
}
Jonathan Warden
fuente
12
Esto también funciona en el nivel de paquete específico. Por ejemplo. "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x". Entonces, sí, "qué asco" como dice ColinE, y también "gracias" como dice ColinE.
juanpaco
22
Sin embargo, tenga en cuenta que este truco evita que cambie el package.jsonprograma de forma programática, por ejemplo, npm version 1.2.3para cambiar la versión: las entradas redundantes se eliminarán del JSON resultante.
jakub.g
16
Este es un mal consejo, porque el orden en que se interpreta un objeto no está garantizado. Por ejemplo, en algunas situaciones, su ejemplo podría terminar con un ser 1 en lugar de 2.
Jo Sprague
66
@mpen El riesgo es que no hay garantía de que el código que analiza el JSON lo haga secuencialmente.
Jo Sprague
77
Para el registro, el RFC dice explícitamente: "Cuando los nombres dentro de un objeto no son únicos, el comportamiento del software que recibe dicho objeto es impredecible. Muchas implementaciones solo informan el apellido / par de valores. Otras implementaciones informan un error o fallan para analizar el objeto, y algunas implementaciones informan todos los pares de nombre / valor, incluidos los duplicados. "
Alan Tam
106

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.

gkond
fuente
1
De esta manera tiene más sentido y mantiene las cosas limpias.
Hitesh Sahu
44
Gracias por una solución no hacky que es técnicamente válida y semánticamente útil.
Roy Tinker
55
Para comentarios sobre guiones, por qué no proporcionar guiones de "ayuda", p"scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
Pico
1
@ pico gracias! El único inconveniente que veo es que los guiones reales se mezclarán con comentarios.
gkond
1
@gkond gracias por esto. Tiene más sentido para mí.
Robin Winslow
20

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

Felipe N Moura
fuente
inteligente, me gusta
KorreyD 05 de
14

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

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.

Philipp Claßen
fuente
1
El "//"hack no funciona dentro de devDependencies. NPM intenta resolver una ruta UNC.
Dmitry S.
Gracias por actualizar la oración pero nuevamente no puede comentar mochaatributo. Solo puede agregar más de uno y será utilizado por npm al final.
vusan el
Odio admitirlo, pero me gusta más que el "//"
roocell
9

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.

Liao San Kai
fuente
66
yay, en realidad está disponible: npmjs.com/package/x----x----x
revelt
99
Estaba encantado con esta respuesta, pero después de ejecutar npm install(usando npm 5) mis claves duplicadas se eliminaron automáticamente :(
Eric Majerus
@EricMajerus oops ~, npm5 también me rompe el corazón :(
Liao San Kai
8

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"
  }
}
este es mi diseño
fuente
7

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)
Marc Trudel
fuente
Argh, en realidad en Windows simplemente ignoraría las banderas, por lo que 3. no es cierto: /
Marc Trudel
Haga que Windows cmd sea compatible con: en &&lugar de ;hacerlo, el primer comando se convierte en:"help": "echo 'Display help information (this screen)' && npm run",
phil_lgr
1
Sí, eso es lo que terminé haciendo. ¡Buena atrapada!
Marc Trudel
3
Solo funciona en la scriptssección. package.jsonEs muchas otras cosas.
Rolf
Correcto. Por otra parte, ¿qué más sentirías la necesidad de documentar allí?
Marc Trudel
6

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

Marzab
fuente
Creo que esta es la respuesta "correcta" en muchos sentidos (tarea para eliminar comentarios con parches de diferencias para tener en cuenta los cambios posteriores a la eliminación); sin embargo, tengo la sensación de que el peso agregado de una tarea difícil no es lo que algunas personas son después, para proyectos pequeños, probablemente sea mejor mantener un archivo externo para comentarios y usar scrpts de NPM (evita las tareas de compilación por completo). Para proyectos grandes, probablemente esté utilizando algún tipo de corredor de tareas, por lo que este enfoque parece sólido. Entre los dos, creo que quizás adaptar la sugerencia "//" al gusto (evitando los puntos de dolor particulares) es lo mejor que se puede hacer.
Enull 01 de
1
Me gusta esta idea, pero como alguien preguntó de manera general, ¿qué pasa con el caso en el que está modificando el paquete original.json a través de npm install --saveo --save-dev?
Isochronous
sí, sigo perdiendo esos comentarios; no hay una buena solución, solía mirar git diffs y actualizar mi archivo .js después de la actualización
MarZab
1

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.

maxime1992
fuente
1

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

Estus Flask
fuente
1

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.

Danny Hurlburt
fuente
1

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

Timmmm
fuente
0

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.

Clemens Tolboom
fuente
Sí b / c Realmente no se puede pero la //clave de todo el mundo, en realidad no es un buen sustituto de los comentarios, especialmente cuando los comentarios pueden tener buen resaltado de sintaxis con un editor etc
Alexander Mills
0

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"

}}}
forforf
fuente
0

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.

Alex Gurin
fuente
¿No intentaría instalar paquetes con el nombre del-commenty envify-comment?
Beni Cherniavsky-Paskin
-1

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"
}
rmirabelle
fuente
usar start_commentsería mejor, porque entonces se ordenará alfabéticamente
Alexander Mills