Come faccio ad aggiungere commenti a package.json per l'installazione di npm?

Ho un semplice file package.json e voglio aggiungere un commento. C'è un modo per farlo, o ci sono degli hack per farlo funzionare?

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

Il commento di esempio sopra non funziona come npm si rompe. Ho anche provato i commenti // style.

Questo è stato recentemente discusso nella mailing list node.js .

Secondo Isaac Schlueter che ha creato npm:

... il tasto "//" non verrà mai utilizzato da npm per nessun motivo ed è riservato ai commenti ... Se si desidera utilizzare un commento a più righe, è possibile utilizzare un array o più "//" chiavi.

Quando si usano i soliti attrezzi (npm, filo, ecc.) Verranno rimosse più chiavi "//". Questo sopravvive:

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

Questo non sopravviverà:

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

Ecco un altro trucco per aggiungere commenti in JSON. Da:

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

È equivalente a

{"a": 2}

Puoi fare qualcosa del tipo:

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

Dopo aver sprecato un'ora in soluzioni complesse e confuse, ho trovato una soluzione semplice e valida per commentare la mia sezione sulle dipendenze ingombranti in package.json. Proprio come questo:

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

Se ordinato allo stesso modo, ora è molto facile per me tenere traccia di queste coppie di dipendenze / commenti in git commit diffs o in editor mentre lavoro con package.json.

E non sono necessari strumenti aggiuntivi, solo JSON semplice e valido.

Spero che questo aiuti chiunque.

Molte idee interessanti.

Quello che ho fatto è questo:

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

In questo modo posso sia leggere i "pseudo-commenti" nello script stesso, sia anche eseguire qualcosa di simile al seguente, per vedere un qualche tipo di aiuto nel terminale:

npm run about
npm run about:watch

I miei 2 centesimi per questa discussione :)

NPS (Node Package Scripts) ha risolto questo problema per me. Consente di inserire gli script NPM in un file JS separato, in cui è possibile aggiungere commenti in abbondanza e qualsiasi altra logica JS necessaria. https://www.npmjs.com/package/nps

Esempio di package-scripts.jsuno dei miei progetti

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

Ho appena fatto un'installazione locale npm install nps -save-deve l'ho inserito nei miei package.jsonscript.

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

Puoi sempre abusare del fatto che le chiavi duplicate vengono sovrascritte. Questo è quello che ho appena scritto:

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

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

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

Tuttavia, non è chiaro se JSON consenta chiavi duplicate (vedi La sintassi JSON consente chiavi duplicate in un oggetto?. Sembra funzionare con npm, quindi corro il rischio.

L'hack raccomandato è di usare le "//"chiavi (dalla mailing list di nodejs ). Tuttavia, quando l'ho provato, non ha funzionato con le sezioni "dipendenze". Inoltre, l'esempio nel post usa più "//"chiavi, il che implica che npm non rifiuta i file JSON con chiavi duplicate. In altre parole, l'hack sopra dovrebbe sempre andare bene.

Aggiornamento: uno fastidioso svantaggio dell'hack chiave duplicato è quellonpm install --save elimina silenziosamente tutti i duplicati. Sfortunatamente, è molto facile trascurarlo e i tuoi commenti ben intenzionati sono spariti.

L' "//"hack è ancora il più sicuro come sembra. Tuttavia, anche i commenti su più righe verranno rimossi npm install --save.

Ho un'idea divertente di hack.

Crea il nome del pacchetto npm opportunamente come divisore di commenti dependenciese devDependenciesblocca, ad esempio, in package.jsonx----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 : è necessario aggiungere la riga del divisore dell'ultimo commento con una versione valida come *nel blocco.

Ispirato da questa discussione, ecco cosa stiamo 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"
  }
}

Finora, la maggior parte degli "hack" qui suggerisce di abusare di JSON. Ma invece, perché non abusare del linguaggio di scripting sottostante?

Modifica La risposta iniziale è stata quella di mettere la descrizione sulla destra usando # add comments hereper avvolgerla; tuttavia, ciò non funziona su Windows, poiché i flag (ad esempio npm eseguono myframework - --myframework-flags) verrebbero ignorati. Ho modificato la mia risposta per farlo funzionare su tutte le piattaforme e ho aggiunto alcuni rientri a fini di leggibilità.

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

Questo sarà:

1. Non infrangere la conformità JSON (o almeno non è un hack, e il tuo IDE non ti darà avvisi per fare cose strane e pericolose)
2. Funziona su più piattaforme (testato su macOS e Windows, supponendo che funzionerebbe bene su Linux)
3. Non ostacola la corsa npm run myframework -- --help
4. Produrrà informazioni significative durante l'esecuzione npm run (che è il comando effettivo da eseguire per ottenere informazioni sugli script disponibili)
5. Presenta un comando di aiuto più esplicito (nel caso in cui alcuni sviluppatori non siano a conoscenza del fatto che npm run presenta tale output)
6. Mostrerà entrambi i comandi E la sua descrizione quando si esegue il comando stesso
7. È in qualche modo leggibile quando si apre package.json(usando lesso il tuo IDE preferito)

Ecco la mia opinione sui commenti in package.json/ bower.json:

Ho package.json.jsche contiene uno script che esporta l'effettivo package.json. L'esecuzione dello script sovrascrive il vecchio package.jsone mi dice quali modifiche ha apportato, perfetto per aiutarti a tenere traccia delle modifiche automatichenpm . In questo modo posso anche definire programmaticamente quali pacchetti voglio usare.

L'ultima grunt task è qui: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Ho finito con un scriptssimile:

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

Il mio intento qui non è di chiarire una riga, ma solo di avere una sorta di delimitatori tra i miei script per backend, frontend, tutti, ecc.

Non sono un grande fan di 1a, 1b, 1c, 2a, ... ma i tasti sono diversi e non ho nessun problema del genere.

Come spiega questa risposta , la //chiave era riservata, quindi può essere utilizzata in modo convenzionale per i commenti. Il problema con il //commento è che non può essere utilizzato dependenciese devDependenciescome dipendenza regolare con una stringa come vincolo di versione:

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

genera un errore,

npm ERR! codice EINVALIDPACKAGENAME

npm ERR! Nome pacchetto "//" non valido: il nome può contenere solo caratteri compatibili con URL

Sebbene le chiavi con valori non stringa siano considerate dipendenze non valide e ignorate in modo efficiente:

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

Una dipendenza stessa può essere commentata allo stesso modo:

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

Poiché le dipendenze vengono ordinate quando package.json viene modificato da NPM, non è pratico posizionare un commento sopra una dipendenza a cui fa riferimento:

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

La chiave di commento deve essere denominata di conseguenza se si riferisce a una riga specifica, quindi non verrà spostata:

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

Un commento applicabile a una dipendenza specifica può essere aggiunto come parte del semver:

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

Si noti che se la prima parte prima ORnon corrisponde, è possibile analizzare un commento, ad es 1.x.

Queste soluzioni alternative sono compatibili con tutte le versioni attuali di NPM (6 e precedenti).

Poiché la maggior parte degli sviluppatori ha familiarità con la documentazione basata su tag / annotazione, la convenzione che ho iniziato a utilizzare è simile. Ecco un assaggio:

{
  "@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: per le dependencies, devDependenciessezioni, ecc, il commento annotazioni non può essere aggiunto direttamente al di sopra delle singole dipendenze dei pacchetti all'interno dell'oggetto di configurazione in quanto npmsi aspetta la chiave per essere il nome di un pacchetto di NPM. Da qui la ragione per il @comment dependencies.

Nota: in alcuni contesti, ad esempio nell'oggetto script, alcuni editor / IDE potrebbero lamentarsi dell'array. Nel contesto degli script, VS Code prevede una stringa per il valore, non un array.

Mi piace il modo in stile annotazione / tag di aggiungere commenti a JSON perché il @simbolo si distingue dalle normali dichiarazioni.

Per riassumere tutte queste risposte:

1. Aggiungi un singolo campo di livello superiore chiamato //che contiene una stringa di commento. Funziona ma fa schifo perché non puoi mettere commenti vicino alla cosa su cui stanno commentando.

2. Aggiungi più campi di livello superiore a partire da // , ad esempio, //dependenciesche contiene una stringa di commento. Questo è meglio, ma ti permette ancora di fare solo commenti di alto livello. Non puoi commentare singole dipendenze.

3. Aggiungi echocomandi al tuo scripts. Funziona ma fa schifo perché puoi usarlo solo in scripts.

Anche queste soluzioni non sono tutte molto leggibili. Aggiungono un sacco di rumore visivo e gli IDE non la sintassi li evidenzieranno come commenti.

Penso che l'unica soluzione ragionevole sia quella di generare il package.jsonda un altro file. Il modo più semplice è scrivere il tuo JSON come Javascript e usare Node per scriverlo package.json. Salva questo file come package.json.mjs, chmod +xe quindi puoi semplicemente eseguirlo per generare il tuo 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));

Usa la //chiave per avvisare le persone di modificarlo. \x40generatedè deliberato. Si trasforma in @generatedin package.jsone significa che alcuni sistemi di revisione del codice comprimeranno quel file per impostazione predefinita.

È un ulteriore passaggio nel tuo sistema di generazione, ma batte tutti gli altri hack qui.

Mentre le chiavi duplicate dei commenti vengono rimosse eseguendo gli strumenti package.json (npm, thread, ecc.) Sono arrivato a utilizzare una versione con hash che consente una lettura migliore come più righe e chiavi come

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

che è "valido" secondo il mio IDE come chiave di root, ma al dependenciessuo interno si lamenta di aspettarsi un valore di stringa.

Un altro trucco. Ho creato uno script da leggere package.jsoncome contesto per un modello di manubrio.

Codice di seguito nel caso in cui qualcuno trovi utile questo approccio:

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

file modello manubrio 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"

}}}

Per npm package.json hanno trovato 2 modi (dopo aver letto questa conversazione):

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

Ma con l'aggiornamento o la reinstallazione del pacchetto con "--save" o "--save-dev, commenta come" ^ 4.1.0! comment "nel posto corrispondente verrà cancellato. E tutto ciò interromperà l'audit npm.

La mia opinione sulla frustrazione di non avere commenti in JSON. Creo nuovi nodi, denominati per i nodi a cui si riferiscono, ma con prefisso di sottolineatura. Questo è imperfetto, ma funzionale.

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