Wie füge ich package.json Kommentare für die npm-Installation hinzu?

Ich habe eine einfache package.json-Datei und möchte einen Kommentar hinzufügen. Gibt es eine Möglichkeit, dies zu tun, oder gibt es Hacks, um dies zum Laufen zu bringen?

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

Der obige Beispielkommentar funktioniert nicht, wenn npm unterbrochen wird. Ich habe auch versucht, Kommentare im // Stil zu verfassen.

Dies wurde kürzlich in der Mailingliste node.js erläutert .

Laut Isaac Schlueter, der npm erstellt hat:

... die Taste "//" wird von npm niemals für irgendeinen Zweck verwendet und ist für Kommentare reserviert ... Wenn Sie einen mehrzeiligen Kommentar verwenden möchten, können Sie entweder ein Array oder mehrere "//" verwenden. Schlüssel.

Bei Verwendung Ihrer üblichen Werkzeuge (npm, Garn usw.) werden mehrere "//" Schlüssel entfernt. Das überlebt:

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

Dies wird nicht überleben:

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

Hier ist ein weiterer Hack zum Hinzufügen von Kommentaren in JSON. Schon seit:

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

Ist äquivalent zu

{"a": 2}

Sie können so etwas tun wie:

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

Nachdem ich eine Stunde mit komplexen und hackigen Lösungen verbracht habe, habe ich sowohl eine einfache als auch eine gültige Lösung gefunden, um meinen Abschnitt über umfangreiche Abhängigkeiten in zu kommentieren package.json. Genau wie dieser:

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

Wenn ich auf die gleiche Weise sortiere, ist es für mich jetzt sehr einfach, diese Paare von Abhängigkeiten / Kommentaren entweder in Git Commit Diffs oder im Editor zu verfolgen, während ich mit arbeite package.json.

Und keine zusätzlichen Tools, nur einfaches und gültiges JSON.

Hoffe das hilft jedem.

Viele interessante Ideen.

Was ich getan habe, ist Folgendes:

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

Auf diese Weise kann ich sowohl die "Pseudokommentare" im Skript selbst lesen als auch Folgendes ausführen, um eine Art Hilfe im Terminal zu sehen:

npm run about
npm run about:watch

Meine 2 Cent für diese Diskussion :)

NPS (Node Package Scripts) hat dieses Problem für mich gelöst. Hiermit können Sie Ihre NPM-Skripte in eine separate JS-Datei einfügen, in der Sie zahlreiche Kommentare und jede andere JS-Logik hinzufügen können, die Sie benötigen. https://www.npmjs.com/package/nps

Beispiel package-scripts.jsaus einem meiner Projekte

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

Ich habe gerade eine lokale Installation durchgeführt npm install nps -save-devund diese in meine package.jsonSkripte eingefügt.

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

Sie können jederzeit die Tatsache missbrauchen, dass doppelte Schlüssel überschrieben werden. Das habe ich gerade geschrieben:

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

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

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

Es ist jedoch nicht klar, ob JSON doppelte Schlüssel zulässt (siehe Erlaubt die JSON-Syntax doppelte Schlüssel in einem Objekt? Es scheint mit npm zu funktionieren, daher gehe ich das Risiko ein.

Der empfohlene Hack besteht darin, "//"Schlüssel zu verwenden (aus der Mailingliste von nodejs ). Als ich es getestet habe, hat es jedoch nicht mit Abschnitten "Abhängigkeiten" funktioniert. Das Beispiel in diesem Beitrag verwendet außerdem mehrere "//"Schlüssel, was bedeutet, dass npm JSON-Dateien mit doppelten Schlüsseln nicht ablehnt. Mit anderen Worten, der obige Hack sollte immer in Ordnung sein.

Update: Ein ärgerlicher Nachteil des duplizierten Schlüssel-Hacks ist, dass npm install --savealle Duplikate stillschweigend entfernt werden. Leider ist es sehr leicht zu übersehen und Ihre gut gemeinten Kommentare sind weg.

Der "//"Hack ist immer noch der sicherste, wie es scheint. Mehrzeilige Kommentare werden jedoch auch von entfernt npm install --save.

Ich habe eine lustige Hack-Idee.

Erstellen Sie beispielsweise einen npm-Paketnamen als Kommentarteiler für dependenciesund devDependenciesblockieren Sie ihn beispielsweise 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": "*"
    }
}

HINWEIS : Die letzte Kommentarteilerzeile muss mit einer gültigen Version wie *im Block hinzugefügt werden .

Inspiriert von diesem Thread verwenden wir Folgendes :

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

Bisher schlagen die meisten "Hacks" hier vor, JSON zu missbrauchen. Aber warum nicht die zugrunde liegende Skriptsprache missbrauchen?

Bearbeiten Die erste Antwort bestand darin, die Beschreibung rechts # add comments herezu platzieren, um sie zu verpacken. Dies funktioniert jedoch nicht unter Windows, da Flags (z. B. npm run myframework - --myframework-flags) ignoriert werden. Ich habe meine Antwort geändert, damit sie auf allen Plattformen funktioniert, und aus Gründen der Lesbarkeit einige Einrückungen hinzugefügt.

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

Dieser Wille:

1. Nicht gegen die JSON-Konformität verstoßen (oder zumindest kein Hack, und Ihre IDE gibt Ihnen keine Warnungen für seltsame, gefährliche Dinge)
2. Funktioniert plattformübergreifend (unter MacOS und Windows getestet, vorausgesetzt, es funktioniert unter Linux einwandfrei)
3. Stört das Laufen nicht npm run myframework -- --help
4. Gibt beim Ausführen aussagekräftige Informationen aus npm run(dies ist der eigentliche Befehl, der ausgeführt werden muss, um Informationen zu verfügbaren Skripten abzurufen).
5. Stellt einen expliziteren Hilfebefehl dar (falls einige Entwickler nicht wissen, dass npm run eine solche Ausgabe darstellt)
6. Zeigt sowohl die Befehle als auch deren Beschreibung an, wenn der Befehl selbst ausgeführt wird
7. Ist beim Öffnen etwas lesbar package.json(mit lessoder Ihrer Lieblings-IDE)

Hier ist meine Meinung zu Kommentaren in package.json/ bower.json:

Ich habe package.json.jsdas enthält ein Skript, das das tatsächliche exportiert package.json. Durch das Ausführen des Skripts wird das alte überschrieben package.jsonund es wird mir mitgeteilt, welche Änderungen vorgenommen wurden. Dies ist ideal, um den Überblick über die automatisch vorgenommenen Änderungen npmzu behalten . Auf diese Weise kann ich sogar programmgesteuert definieren, welche Pakete ich verwenden möchte.

Die neueste Grunzaufgabe ist hier: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Am Ende hatte ich scriptsso etwas:

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

Meine Absicht hier ist nicht, eine Zeile zu klären, sondern nur eine Art Trennzeichen zwischen meinen Skripten für Backend, Frontend, alle usw. zu haben.

Ich bin kein großer Fan von 1a, 1b, 1c, 2a, ... aber die Tasten sind unterschiedlich und ich habe überhaupt kein Problem damit.

Wie in dieser Antwort erläutert, wurde der //Schlüssel reserviert, sodass er herkömmlicherweise für Kommentare verwendet werden kann. Das Problem mit //Kommentaren ist, dass sie nicht in dependenciesund devDependenciesals reguläre Abhängigkeit mit einer Zeichenfolge als Versionsbeschränkung verwendet werden können:

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

löst einen Fehler aus,

npm ERR! Code EINVALIDPACKAGENAME

npm ERR! Ungültiger Paketname "//": Name darf nur URL-freundliche Zeichen enthalten

Obwohl Schlüssel mit Nicht-Zeichenfolgenwerten als ungültige Abhängigkeiten betrachtet und effizient ignoriert werden:

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

Eine Abhängigkeit selbst kann auf die gleiche Weise auskommentiert werden:

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

Da Abhängigkeiten sortiert werden, wenn package.json von NPM geändert wird, ist es unpraktisch, einen Kommentar über eine Abhängigkeit zu setzen, auf die verwiesen wird:

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

Der Kommentarschlüssel sollte entsprechend benannt werden, wenn er sich auf eine bestimmte Zeile bezieht, damit er nicht verschoben wird:

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

Ein Kommentar, der auf bestimmte Abhängigkeiten anwendbar ist, kann als Teil von semver hinzugefügt werden:

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

Beachten Sie, dass ORein Kommentar analysiert werden kann , wenn der erste Teil zuvor nicht übereinstimmt, z 1.x.

Diese Problemumgehungen sind mit allen aktuellen NPM-Versionen (6 und niedriger) kompatibel.

Da die meisten Entwickler mit der auf Tags / Anmerkungen basierenden Dokumentation vertraut sind, ist die von mir verwendete Konvention ähnlich. Hier ist ein Vorgeschmack:

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

Hinweis: Für die dependencies, devDependenciesusw Abschnitte, die Kommentars Anmerkungen können nicht direkt über den einzelnen Paketabhängigkeiten in dem Konfigurationsobjekt hinzugefügt werden , da npmden Schlüssel erwartet der Name eines npm Paket zu sein. Daher der Grund für die @comment dependencies.

Hinweis: In bestimmten Kontexten, z. B. im Skriptobjekt, können sich einige Editoren / IDEs über das Array beschweren. Im Skriptkontext erwartet VS Code eine Zeichenfolge für den Wert - kein Array.

Ich mag die Annotation / Tag-Stil-Art, Kommentare zu JSON hinzuzufügen, weil sich das @Symbol von den normalen Deklarationen abhebt.

Um alle diese Antworten zusammenzufassen:

1. Fügen Sie ein einzelnes Feld der obersten Ebene hinzu// , das eine Kommentarzeichenfolge enthält. Dies funktioniert, ist aber zum Kotzen, weil Sie keine Kommentare in die Nähe des Kommentars setzen können.

2. Fügen Sie mehrere Felder der obersten Ebene hinzu , beginnend mit // , z. B. //dependenciesdie eine Kommentarzeichenfolge enthalten. Dies ist besser, aber Sie können trotzdem nur Kommentare auf höchster Ebene abgeben. Sie können einzelne Abhängigkeiten nicht kommentieren.

3. Fügen Sie echoIhrem Befehl Befehle hinzu scripts. Dies funktioniert, aber es ist scheiße, weil Sie es nur in verwenden können scripts.

Diese Lösungen sind auch alle nicht sehr gut lesbar. Sie fügen eine Menge visuelles Rauschen hinzu und IDEs werden sie durch die Syntax nicht als Kommentare hervorheben.

Ich denke, die einzig vernünftige Lösung besteht darin, die package.jsonaus einer anderen Datei zu generieren . Am einfachsten ist es, Ihren JSON als Javascript zu schreiben und ihn mit Node zu schreiben package.json. Speichern Sie diese Datei als package.json.mjs, chmod +xund dann können Sie sie einfach ausführen, um Ihre zu generieren 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));

Es verwendet den //Schlüssel, um Personen vor dem Bearbeiten zu warnen. \x40generatedist absichtlich. Es wird zu @generatedIn package.jsonund bedeutet, dass einige Codeüberprüfungssysteme diese Datei standardmäßig reduzieren.

Es ist ein zusätzlicher Schritt in Ihrem Build-System, aber es schlägt alle anderen Hacks hier.

Da doppelte Kommentarschlüssel mit den Tools package.json (npm, Garn usw.) entfernt werden, habe ich eine Hash-Version verwendet, die ein besseres Lesen als mehrere Zeilen und Schlüssel ermöglicht

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

Das ist laut meiner IDE als Root-Schlüssel 'gültig', dependenciesbeschwert sich aber darin, einen String-Wert zu erwarten.

Noch ein Hack. Ich habe ein Skript erstellt, das package.jsonals Kontext für eine Lenkervorlage gelesen werden kann .

Code unten, falls jemand diesen Ansatz nützlich findet:

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

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

}}}

Für npm package.json wurden zwei Möglichkeiten gefunden (nach dem Lesen dieser Konversation):

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

Aber mit dem Update oder der Neuinstallation des Pakets mit "--save" oder "--save-dev" kommentieren Sie wie "^ 4.1.0! Kommentar "an der entsprechenden Stelle wird gelöscht. Und all dies wird npm Audit gebrochen.

Ich nehme die Frustration über keine Kommentare in JSON auf. Ich erstelle neue Knoten, die nach den Knoten benannt sind, auf die sie verweisen, denen jedoch Unterstriche vorangestellt sind. Dies ist unvollkommen, aber funktional.

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