Jak dodać komentarze do package.json do instalacji npm?

380

Mam prosty plik package.json i chcę dodać komentarz. Czy istnieje sposób, aby to zrobić, czy są jakieś hacki, aby to zadziałało?

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

Powyższy przykładowy komentarz nie działa, gdy psuje się npm. Próbowałem też // stylowych komentarzy.

Will Shaver
źródło
możliwy duplikat Czy mogę skomentować plik JSON?
Yehuda Katz
17
@YehudaKatz - Nie sądzę, że jest to duplikat, ponieważ to pytanie jest specyficzne dla package.jsonplików i istnieje package.jsonkonkretna odpowiedź na liście mailingowej NodeJS.
Mark Evans
2
Jeden z głównych programistów npm odmówił rozważenia obsługi komentarzy package.json. Skomentuj ten problem - być może możemy pokazać, jak przydatne mogą być komentarze.
Dan Dascalescu,
5
Jeden pojedynczy tag <sarkazm />. JSON5 obsługuje komentarze json5.org
Cristian E.

Odpowiedzi:

450

Ten niedawno został omówiony w node.js listy .

Według Isaaca Schluetera, który stworzył npm:

... klucz „//” nigdy nie zostanie użyty przez npm do żadnego celu i jest zarezerwowany dla komentarzy ... Jeśli chcesz użyć komentarza wieloliniowego, możesz użyć tablicy lub wielu „//” Klucze.

Podczas korzystania ze zwykłych narzędzi (npm, przędzy itp.) Wiele kluczy „//” zostanie usuniętych. To przetrwa:

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

To nie przetrwa:

{ "//": "this is the first line of a comment", 
  "//": "this is the second line of the comment" } 
Igor Soarez
źródło
58
czy istnieje sposób na udokumentowanie, czym jest każdy wpis w sekcji „zależności”? sztuczka „//” nie działa, gdy jest atrybutem „zależności”.
rynop
8
Zauważ, że użycie wielu komentarzy, tak jak w pierwszym przykładzie, { "//": "first", "//": "second"}uniemożliwia korzystanie z npm versioninnych narzędzi wiersza poleceń, które zwykle ponownie analizują cały JSON i odrzucają powielone klucze.
jakub.g
60
Trzeba mieć świadomość, że „//” można stosować tylko u podstaw tego package.jsonprzedmiotu. Na przykład { "dependencies": { "//": "comment?" }}jest nieprawidłowy, ale { "//": "comment!", "dependencies":{}}ważny.
david_p
52
Nawet Douglas Crockford nie ma problemu z umieszczaniem komentarzy w plikach konfiguracyjnych JSON. Sytuacja z NPM jest co najmniej głupia.
Muhammad Rehan Saeed,
5
z mojego doświadczenia wynika, że "//"klucz i jego wartość zostaną ostatecznie usunięte. czy istnieje sposób, aby mieć stałe komentarze?
pruett,
116

Oto kolejny hack dodawania komentarzy w JSON. Od:

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

Jest równa

{"a": 2}

Możesz zrobić coś takiego:

{
  "devDependencies": "'mocha' not needed as should be globally installed",
  "devDependencies" :  {
    "should": "*"
  }
}
Jonathan Warden
źródło
12
Działa to również na określonym poziomie pakietu. Na przykład. "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x". Tak, „fuj”, jak mówi ColinE, a także „dzięki”, jak mówi ColinE.
juanpaco
22
Zauważ jednak, że ten hack uniemożliwia kiedykolwiek package.jsonprogramową zmianę , powiedzmy, npm version 1.2.3by poderwać wersję - zbędne wpisy zostaną usunięte z wynikowego JSON.
jakub.g
16
To zła rada, ponieważ nie jest gwarantowana kolejność interpretacji obiektu. Na przykład, w niektórych sytuacjach, twój przykład może skończyć się bytem 1 zamiast 2.
Jo Sprague
6
@mpen Ryzyko polega na tym, że nie ma gwarancji, że kod analizujący JSON zrobi to sekwencyjnie.
Jo Sprague,
7
Dla przypomnienia RFC wyraźnie stwierdza: „Gdy nazwy w obiekcie nie są unikalne, zachowanie oprogramowania, które odbiera taki obiekt, jest nieprzewidywalne. Wiele implementacji zgłasza tylko parę ostatnich nazw / wartości. Inne implementacje zgłaszają błąd lub błąd parsować obiekt, a niektóre implementacje zgłaszają wszystkie pary nazwa / wartość, w tym duplikaty. ”
Alan Tam
106

Po marnowaniu godziny na skomplikowane i zhackowane rozwiązania znalazłem zarówno proste, jak i prawidłowe rozwiązanie do komentowania mojej obszernej sekcji zależności package.json. Takie jak to:

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

Po posortowaniu w ten sam sposób, bardzo łatwo jest mi teraz wyśledzić te pary zależności / komentarzy w git commit diffs lub w edytorze podczas pracy z nimi package.json.

I bez dodatkowych narzędzi, tylko prosty i prawidłowy JSON.

Mam nadzieję, że to pomoże każdemu.

gkond
źródło
1
W ten sposób zyskaj więcej sensu i utrzymuj porządek.
Hitesh Sahu
4
Dzięki za niehackujące rozwiązanie, które jest technicznie ważne i semantycznie pomocne.
Roy Tinker,
5
Aby komentować skrypty, zapewnij skrypty „pomocy”, np. "scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
szczyt
1
@ szczyt dzięki! Jedynym minusem jest to, że rzeczywiste skrypty będą mieszane z komentarzami.
gkond
1
@gkond dzięki za to. Ma dla mnie jak najbardziej sens.
Robin Winslow
20

Wiele interesujących pomysłów.

To, co robiłem, to:

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

W ten sposób mogę zarówno przeczytać „pseudo-komentarze” w samym skrypcie, ORAZ także uruchomić coś takiego, jak poniżej, aby zobaczyć jakąś pomoc w terminalu:

npm run about
npm run about:watch

Moje 2 centy za tę dyskusję :)

Felipe N Moura
źródło
sprytne, podoba mi się to
KorreyD
14

NPS (skrypty pakietów węzłów) rozwiązał dla mnie ten problem. Umożliwia umieszczenie skryptów NPM w osobnym pliku JS, w którym można dodawać mnóstwo komentarzy i dowolną inną logikę JS, której potrzebujesz. https://www.npmjs.com/package/nps

Próbka package-scripts.jsjednego z moich projektów

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

Właśnie zrobiłem instalację lokalną npm install nps -save-devi umieściłem to w moich package.jsonskryptach.

"scripts": {
    "start": "nps",
    "test": "nps test"
}
Jim Doyle
źródło
13

Zawsze możesz nadużyć faktu, że zduplikowane klucze są zastępowane. Oto co właśnie napisałem:

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

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

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

Nie jest jednak jasne, czy JSON zezwala na duplikaty kluczy (zobacz Czy składnia JSON zezwala na duplikaty kluczy w obiekcie?. Wygląda na to, że działa z npm, więc podejmuję ryzyko.

Zalecanym włamaniem jest użycie "//"kluczy (z listy mailingowej nodejs ). Kiedy go przetestowałem, nie działało to jednak z sekcjami „zależności”. Również przykład w poście używa wielu "//"kluczy, co oznacza, że ​​npm nie odrzuca plików JSON ze zduplikowanymi kluczami. Innymi słowy, powyższy hack powinien zawsze być w porządku.

Aktualizacja: Jedną z denerwujących wad hackowania powielonego klucza jest tonpm install --save dyskretnie eliminuje wszystkie duplikaty. Niestety bardzo łatwo to przeoczyć, a twoje dobre intencje zniknęły.

"//"Hack jest nadal najbezpieczniejszym jak się wydaje. Jednak komentarze wielowierszowe również zostaną usunięte npm install --save.

Philipp Claßen
źródło
1
"//"Hack nie działa wewnątrz devDependencies. NPM próbuje rozwiązać ścieżkę UNC.
Dmitry S.
Dzięki za aktualizację zdania, ale znowu nie może komentować mochaatrybutu. Wystarczy dodać więcej niż jeden z nich i na końcu zostanie użyty przez npm.
vusan
Nienawidzę tego przyznać - ale podoba mi się to bardziej niż „//”
roocell
9

Mam zabawny pomysł na hack.

Utwórz na przykład nazwę pakietu npm jako dzielnik komentarzy dependenciesi devDependencieszablokuj na przykład w pliku 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": "*"
    }
}

UWAGA : Należy dodać linię podziału ostatniego komentarza z prawidłową wersją jak *w bloku.

Liao San Kai
źródło
6
tak, to jest faktycznie dostępne: npmjs.com/package/x----x----x
odwołano
9
Byłem zachwycony tą odpowiedzią, ale po uruchomieniu npm install(używając npm 5) moje zduplikowane klucze zostały automatycznie usunięte :(
Eric Majerus
@EricMajerus oops ~, npm5 złamać mi serce też :(
Liao San Kai
8

Zainspirowany tym wątkiem, oto czego używamy :

{
  "//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"
  }
}
to mój projekt
źródło
7

Jak dotąd większość „hacków” sugeruje nadużywanie JSON. Ale zamiast tego dlaczego nie nadużywać podstawowego języka skryptowego?

Edytuj Pierwszą odpowiedzią było umieszczenie opisu po prawej stronie za pomocą # add comments hereowijania go; nie działa to jednak w systemie Windows, ponieważ flagi (np. npm uruchom myframework - --myframework-flags) zostaną zignorowane. Zmieniłem odpowiedź, aby działała na wszystkich platformach, i dodałem kilka wcięć w celu zapewnienia czytelności.

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

Spowoduje to:

  1. Nie psuj zgodności z JSON (a przynajmniej nie jest to hack, a twoje IDE nie ostrzeże Cię przed robieniem dziwnych, niebezpiecznych rzeczy)
  2. Działa na wielu platformach (testowany na macOS i Windows, przy założeniu, że będzie działał dobrze w systemie Linux)
  3. Nie przeszkadza w bieganiu npm run myframework -- --help
  4. Podczas działania wyświetli znaczące informacje npm run (które jest właściwym poleceniem do uruchomienia w celu uzyskania informacji o dostępnych skryptach)
  5. Przedstawia bardziej wyraźne polecenie pomocy (w przypadku, gdy niektórzy deweloperzy nie są świadomi, że npm run prezentuje takie dane wyjściowe)
  6. Wyświetli zarówno polecenia ORAZ jego opis podczas uruchamiania samego polecenia
  7. Jest nieco czytelny podczas otwierania package.json(przy użyciu lesslub ulubionego IDE)
Marc Trudel
źródło
Argh, właściwie w systemie Windows po prostu zignorowałby flagi, więc 3. to nie prawda: /
Marc Trudel
Uczyń system Windows cmd kompatybilnym z: &&zamiast ;tak pierwsze polecenie staje się:"help": "echo 'Display help information (this screen)' && npm run",
phil_lgr
1
Tak, właśnie to skończyłem. Dobry chwyt!
Marc Trudel,
3
Działa tylko w scriptssekcji. package.jsonjest wiele innych rzeczy.
Rolf
Poprawny. Z drugiej strony, co jeszcze czułbyś w dokumentach?
Marc Trudel,
6

Oto moje zdanie na temat komentarzy w package.json/bower.json :

Mam, package.json.jsże zawiera skrypt, który eksportuje rzeczywiste package.json. Uruchomienie skryptu zastępuje stare package.jsoni mówi mi, jakie zmiany zostały wprowadzone, idealne, aby pomóc Ci śledzić automatyczne zmianynpm . W ten sposób mogę nawet programowo zdefiniować, których pakietów chcę używać.

Najnowsze zadanie gruntu jest tutaj: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

MarZab
źródło
Myślę, że jest to „poprawna” odpowiedź na wiele sposobów (zadanie usuwania komentarzy z łataniem diff w celu uwzględnienia zmian po paskowaniu) - mam jednak wrażenie, że dodatkowa waga pomruku nie jest tym, czym są niektórzy ludzie po, w przypadku małych projektów, najlepiej najlepiej przechowywać zewnętrzny plik do komentowania i używać skryptu NPM (całkowicie eliminuje zadania kompilacji). W przypadku dużych projektów prawdopodobnie używasz jakiejś formy programu uruchamiającego zadania, więc takie podejście wydaje się solidne. Pomiędzy tymi dwoma myślę, że może dostosowanie sugestii „//” do smaku (unikanie konkretnych punktów bólu) jest najlepszym rozwiązaniem, jakie można zrobić.
Enull
1
Podoba mi się ten pomysł, ale jak ktoś zapytał w skrócie, co z przypadkiem, w którym modyfikujesz oryginalny pakiet.json przez npm install --savelub --save-dev?
Izochroniczny
tak, ciągle tęsknię za tymi komentarzami; nie ma dobrego rozwiązania,
patrzyłem
1

Skończyło się scriptstak:

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

Moim zamiarem nie jest tutaj wyjaśnienie jednej linii, a jedynie posiadanie pewnego rodzaju separatorów między moimi skryptami dla backendu, frontendu itp.

Nie jestem wielkim fanem 1a, 1b, 1c, 2a, ... ale klawisze są inne i nie mam z tym żadnego problemu.

maxime1992
źródło
1

Jak wyjaśnia ta odpowiedź , //klucz został zarezerwowany, więc można go używać konwencjonalnie do komentowania. Problem z //komentarzem jest to, że nie może być stosowany w dependenciesi devDependenciesjak regularne uzależnienia sznurkiem w wersji przymusu:

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

wywołuje błąd,

npm ERR! kod EINVALIDPACKAGENAME

npm ERR! Nieprawidłowa nazwa pakietu „//”: nazwa może zawierać tylko znaki przyjazne adresowi URL

Chociaż klucze z wartościami nieciągowymi są uważane za nieprawidłowe zależności i są skutecznie ignorowane:

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

Zależność można skomentować w ten sam sposób:

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

Ponieważ zależności są sortowane, gdy pakiet.json jest modyfikowany przez NPM, niepraktyczne jest umieszczanie komentarza powyżej zależności, do której się odnosi:

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

Klucz komentarza powinien zostać odpowiednio nazwany, jeśli odnosi się do określonej linii, więc nie zostanie przeniesiony:

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

Komentarz mający zastosowanie do konkretnej zależności można dodać jako część semver:

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

Zauważ, że jeśli pierwsza część ORnie pasuje, komentarz może zostać przeanalizowany, np 1.x.

Te obejścia są kompatybilne ze wszystkimi aktualnymi wersjami NPM (6 i niższymi).

Estus Flask
źródło
1

Ponieważ większość programistów zna dokumentację opartą na znacznikach / adnotacjach, konwencja, z której zacząłem korzystać, jest podobna. Oto smak:

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

Uwaga: W przypadku dependencies, devDependenciesitp sekcjach, adnotacje komentarz nie może być dodany bezpośrednio nad poszczególnymi zależnościami pakietów wewnątrz obiektu konfiguracji ponieważ npmspodziewa się klucz do być nazwa pakietu npm. Stąd przyczyna @comment dependencies.

Uwaga: W niektórych kontekstach, na przykład w obiekcie skryptów, niektórzy redaktorzy / IDE mogą narzekać na tablicę. W kontekście skryptów VS Code oczekuje ciągu wartości - nie tablicy.

Podoba mi się sposób dodawania komentarzy do JSON w stylu adnotacji / tagu, ponieważ @symbol wyróżnia się od zwykłych deklaracji.

Danny Hurlburt
źródło
1

Podsumowując wszystkie te odpowiedzi:

  1. Dodaj jedno pole najwyższego poziomu o nazwie, //które zawiera ciąg komentarza. To działa, ale jest do bani, ponieważ nie można umieszczać komentarzy w pobliżu tego, co komentują.

  2. Dodaj wiele pól najwyższego poziomu, zaczynając od // , np. //dependenciesZawierających ciąg komentarza. Jest to lepsze, ale nadal pozwala tylko na komentarze na najwyższym poziomie. Nie możesz komentować poszczególnych zależności.

  3. Dodaj echopolecenia do swojego scripts. To działa, ale jest do bani, ponieważ można go używać tylko w scripts.

Te rozwiązania również nie są zbyt czytelne. Dodają mnóstwo wizualnego szumu, a IDE nie podświetlą ich jako komentarzy.

Myślę, że jedynym rozsądnym rozwiązaniem jest wygenerowanie package.jsonz innego pliku. Najprostszym sposobem jest napisanie JSON jako Javascript i użycie Node do napisania package.json. Zapisz ten plik jako package.json.mjs, chmod +xa następnie możesz go uruchomić, aby go wygenerować 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));

Używa //klucza, aby ostrzec ludzi przed edycją. \x40generatedjest celowe. Zmienia się @generatedw package.jsoni oznacza, że ​​niektóre systemy przeglądania kodu domyślnie zwiną ten plik.

To dodatkowy krok w twoim systemie kompilacji, ale pokonuje wszystkie inne hacki tutaj.

Timmmm
źródło
0

Gdy zduplikowane klucze komentarza są usuwane przy użyciu narzędzi package.json (npm, przędza itp.), Zacząłem używać wersji z haszowaniem, która pozwala na lepszy odczyt, ponieważ wiele wierszy i kluczy, takich jak

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

który jest „prawidłowy” według mojego IDE jako klucza głównego, ale w dependenciesnim narzeka, oczekując wartości ciągu.

Clemens Tolboom
źródło
tak, b / c tak naprawdę nie można, ale //klucz jest wszędzie, nie jest to naprawdę dobry zamiennik dla komentarzy, szczególnie gdy komentarze mogą mieć ładne podświetlanie składni za pomocą edytora itp.
Alexander Mills
0

Kolejny hack. Stworzyłem skrypt do czytania package.jsonjako kontekst dla szablonu kierownicy.

Kod poniżej na wypadek, gdyby ktoś uznał to podejście za przydatne:

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

plik szablonu kierownicy 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
źródło
0

Dla npm package.json znalazłem 2 sposoby (po przeczytaniu tej rozmowy):

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

Ale wraz z aktualizacją lub ponowną instalacją pakietu za pomocą „--save” lub „--save-dev, skomentuj jak„ ^ 4.1.0! komentarz "w odpowiednim miejscu zostanie usunięty. A wszystko to złamie npm audyt.

Alex Gurin
źródło
czy nie spróbuje to zainstalować pakietów o nazwach del-commenti envify-comment?
Beni Cherniavsky-Paskin
-1

Moje zdanie na temat braku komentarzy w JSON. Tworzę nowe węzły, nazwane od węzłów, do których się odnoszą, ale z prefiksem. Jest to niedoskonałe, ale funkcjonalne.

{
  "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
źródło
użycie start_commentbyłoby lepsze, ponieważ wtedy uporządkuje alfabetycznie
Alexander Mills,