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

380

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.

Will Shaver
quelle
Mögliches Duplikat von Kann ich eine JSON-Datei kommentieren?
Yehuda Katz
17
@YehudaKatz - Ich denke nicht, dass es sich um ein Duplikat handelt, da diese Frage spezifisch für package.jsonDateien ist und es eine package.jsonspezifische Antwort auf der NodeJS-Mailingliste gibt.
Mark Evans
2
Einer der wichtigsten npm-Entwickler hat sich geweigert , die Unterstützung von Kommentaren in Betracht zu ziehen package.json. Bitte kommentieren Sie dieses Problem - vielleicht können wir zeigen, wie nützlich Kommentare sein können.
Dan Dascalescu
5
Ein einzelnes Tag <Sarkasmus />. JSON5 unterstützt Kommentare json5.org
Cristian E.

Antworten:

450

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" } 
Igor Soarez
quelle
58
Gibt es eine Möglichkeit zu dokumentieren, was jeder Eintrag im Abschnitt "Abhängigkeiten" ist? Der Trick "//" funktioniert nicht, wenn es sich um ein Attribut von 'Abhängigkeiten' handelt.
Rynop
8
Beachten Sie, dass die Verwendung mehrerer Kommentare wie im ersten Beispiel { "//": "first", "//": "second"}die Verwendung npm versionanderer Befehlszeilen-Utils verhindert, die normalerweise den gesamten JSON-Code reparieren und die in Bearbeitung befindlichen doppelten Schlüssel verwerfen.
jakub.g
60
Man muss sich bewusst sein, dass "//" nur an der Wurzel des package.jsonObjekts verwendet werden kann. Zum Beispiel { "dependencies": { "//": "comment?" }}ist ungültig, aber { "//": "comment!", "dependencies":{}}gültig.
David_p
52
Selbst Douglas Crockford hat kein Problem damit, Kommentare in JSON-Konfigurationsdateien einzufügen. Die Situation mit NPM ist gelinde gesagt albern.
Muhammad Rehan Saeed
5
Nach meiner Erfahrung werden der "//"Schlüssel und sein Wert irgendwann gelöscht. Gibt es eine Möglichkeit, dauerhafte Kommentare zu haben?
Pruett
116

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": "*"
  }
}
Jonathan Warden
quelle
12
Dies funktioniert auch auf der spezifischen Paketebene. Zum Beispiel. "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x". Also ja, "yuck" wie ColinE sagt, und auch "danke" wie ColinE sagt.
Juanpaco
22
Beachten Sie jedoch, dass dieser Hack verhindert, dass Sie das package.jsonProgramm jemals programmatisch ändern , z. B. um npm version 1.2.3die Version zu verbessern. Die redundanten Einträge werden aus dem resultierenden JSON entfernt.
jakub.g
16
Dies ist ein schlechter Rat, da die Reihenfolge, in der ein Objekt interpretiert wird, nicht garantiert ist. In einigen Situationen kann Ihr Beispiel beispielsweise 1 statt 2 sein.
Jo Sprague
6
@mpen Das Risiko besteht darin, dass nicht garantiert werden kann, dass der Code, der den JSON analysiert, dies nacheinander ausführt.
Jo Sprague
7
Für den Datensatz sagt der RFC ausdrücklich: "Wenn die Namen innerhalb eines Objekts nicht eindeutig sind, ist das Verhalten von Software, die ein solches Objekt empfängt, nicht vorhersehbar. Viele Implementierungen melden nur das Nachname / Wert-Paar. Andere Implementierungen melden einen Fehler oder Fehler um das Objekt zu analysieren, und einige Implementierungen melden alle Name / Wert-Paare, einschließlich Duplikate. "
Alan Tam
106

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.

gkond
quelle
1
Auf diese Weise macht es mehr Sinn und hält die Dinge sauber.
Hitesh Sahu
4
Vielen Dank für eine nicht hackige Lösung, die technisch gültig und semantisch hilfreich ist.
Roy Tinker
5
Wenn Sie Kommentare zu Skripten wünschen, geben Sie "Hilfe" -Skripte an, z. B. "scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
Peak
1
@peak danke! Der einzige Nachteil, den ich sehe, ist, dass tatsächliche Skripte mit Kommentaren gemischt werden.
Gkond
1
@gkond danke dafür. Macht für mich am meisten Sinn.
Robin Winslow
20

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

Felipe N Moura
quelle
klug, ich mag es
KorreyD
14

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

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.

Philipp Claßen
quelle
1
Der "//"Hack funktioniert nicht innerhalb von devDependencies. NPM versucht, einen UNC-Pfad aufzulösen.
Dmitry S.
Vielen Dank für den Aktualisierungssatz, aber auch hier kann das mochaAttribut nicht kommentiert werden. Nur kann es mehr als eine davon hinzufügen und wird am Ende von npm verwendet.
Vusan
Ich hasse es, es zuzugeben - aber ich mag das besser als das "//"
Roocell
9

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 .

Liao San Kai
quelle
6
Ja, es ist tatsächlich verfügbar: npmjs.com/package/x----x----x
revelt
9
War begeistert von dieser Antwort, aber nachdem ich npm install(mit npm 5) ausgeführt hatte, wurden meine doppelten Schlüssel automatisch entfernt :(
Eric Majerus
@ EricMajerus oops ~, npm5 brechen auch mein Herz :(
Liao San Kai
8

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"
  }
}
Das ist mein Design
quelle
7

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)
Marc Trudel
quelle
Argh, eigentlich unter Windows würde es nur Flags ignorieren, also 3. ist nicht wahr: /
Marc Trudel
Machen Sie es Windows cmd kompatibel mit: &&Stattdessen wird ;der erste Befehl:"help": "echo 'Display help information (this screen)' && npm run",
phil_lgr
1
Ja, das habe ich letztendlich getan. Guter Fang!
Marc Trudel
3
Es funktioniert nur in der scriptsSektion. package.jsonist viele andere Dinge.
Rolf
Richtig. Was würden Sie sonst noch brauchen, um dort zu dokumentieren?
Marc Trudel
6

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

MarZab
quelle
Ich denke, dies ist in vielerlei Hinsicht die "richtige" Antwort (Aufgabe, Kommentare mit Diff-Patches zu entfernen, um Änderungen nach dem Entfernen zu berücksichtigen) - ich habe jedoch das Gefühl, dass das zusätzliche Gewicht einer Grunzaufgabe nicht das ist, was manche Leute sind Danach ist es für kleine Projekte wahrscheinlich am besten, eine externe Datei für Kommentare aufzubewahren und NPM-Skripte zu verwenden (vermeidet Build-Aufgaben insgesamt). Bei großen Projekten verwenden Sie wahrscheinlich eine Art Task-Runner, sodass dieser Ansatz solide erscheint. Ich denke, zwischen den beiden ist es vielleicht das Beste, den "//" -Vorschlag an den Geschmack anzupassen (die eigenen Schmerzpunkte zu vermeiden).
Enull
1
Ich mag diese Idee, aber als jemand im Kern fragte, was ist mit dem Fall, in dem Sie die ursprüngliche package.json durch npm install --saveoder ändern --save-dev?
Isochronous
Ja, ich vermisse diese Kommentare immer wieder. Es gibt keine gute Lösung, ich habe mir Git-Diffs angesehen und meine .js-Datei nach dem Update aktualisiert
MarZab
1

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.

maxime1992
quelle
1

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.

Estus Flask
quelle
1

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.

Danny Hurlburt
quelle
1

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.

Timmmm
quelle
0

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.

Clemens Tolboom
quelle
Ja, b / c kann man nicht wirklich, aber der //Schlüssel überall, es ist nicht wirklich ein guter Ersatz für Kommentare, besonders wenn Kommentare eine nette Syntaxhervorhebung mit einem Editor usw. haben können
Alexander Mills
0

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"

}}}
forforf
quelle
0

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.

Alex Gurin
quelle
würde dies nicht versuchen, Pakete mit dem Namen del-commentund zu installieren envify-comment?
Beni Cherniavsky-Paskin
-1

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"
}
rmirabelle
quelle
Verwenden start_commentwäre besser, denn dann wird es alphabetisch sortiert
Alexander Mills