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

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.

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

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": "*"
  }
}

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.

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

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

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.

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.

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

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)

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

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.

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

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.

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.

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.

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"

}}}

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.

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