Як додати коментарі до package.json для встановлення npm?

У мене простий файл package.json, і я хочу додати коментар. Чи є спосіб це зробити чи є хаки, щоб зробити цю роботу?

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

Наведений вище коментар не працює, коли перерви в npm. Я також спробував // коментарі до стилю.

Про це нещодавно обговорювалося в Node.js списку розсилки .

За словами Ісаака Шлютера, який створив npm:

... ключ "//" ніколи не буде використовуватися npm для будь-яких цілей і зарезервований для коментарів ... Якщо ви хочете використовувати коментар з декількома рядками, ви можете використовувати масив, або кілька "//" ключі.

При використанні звичних інструментів (npm, пряжа тощо) кілька "//" клавіш буде видалено. Це виживає:

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

Це не витримає:

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

Ось ще один хак для додавання коментарів у JSON. З моменту:

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

Еквівалентно

{"a": 2}

Ви можете зробити щось на кшталт:

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

Затративши годину на складні та хиткі рішення, я знайшов і просте, і вірне рішення для коментування мого розділу об’ємних залежностей у package.json. Просто так:

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

Коли відсортовано так само, тепер мені дуже просто відстежувати ці пари залежностей / коментарів або в git commit diff, або в редакторі під час роботи з package.json .

І ніяких додаткових інструментів не задіяно, просто звичайний та дійсний JSON.

Сподіваюся, це допоможе комусь.

Багато цікавих ідей.

Що я робив, це:

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

Таким чином я можу прочитати "псевдо-коментарі" в самому сценарії, а також виконати щось на зразок наступного, щоб побачити якусь допомогу в терміналі:

npm run about
npm run about:watch

Мої 2 центи для цієї дискусії :)

NPS (Node Package Scripts) вирішив цю проблему для мене. Дозволяє помістити ваші сценарії NPM в окремий файл JS, де ви можете додавати коментарі в необачності та будь-яку іншу логіку JS, яка вам потрібна. https://www.npmjs.com/package/nps

Зразок package-scripts.jsодного з моїх проектів

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

Я щойно зробив локальну установку npm install nps -save-devі вклав це в свої package.jsonсценарії.

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

Ви завжди можете зловживати тим, що дублюються ключі перезаписуються. Ось що я написав:

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

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

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

Однак незрозуміло, чи дозволяє JSON дублювати ключі (див. Чи дозволяє синтаксис JSON дублювати ключі в об'єкті?) Здається, він працює з npm, тому я ризикую.

Рекомендований хак - використовувати "//"ключі (зі списку розсилки nodejs ). Коли я тестував це, він не працював із розділами "залежностей". Також у прикладі в публікації використовуються кілька "//"клавіш, з чого випливає, що npm не відхиляє файли JSON з дублюються ключами. Іншими словами, злом вище завжди повинен бути добре.

Оновлення. Одним з прикрою недоліком продубльованого злому ключа є те, щоnpm install --save мовчки усуває всі дублікати. На жаль, це дуже легко не помітити, і ваші цілеспрямовані коментарі зникли.

"//"Хак по- , як і раніше є самим безпечним , як це здається. Однак багаторядкові коментарі також буде видалено npm install --save.

У мене є кумедна ідея злому.

Наприклад, створіть ім'я пакета npm, як роздільник коментарів dependenciesта devDependenciesблокуйте, наприклад, у 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": "*"
    }
}

ПРИМІТКА . Потрібно додати останній рядок розділення коментарів із дійсною версією, наприклад, *у блоці.

Ось що ми використовуємо :

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

Поки що більшість "хакків" тут пропонують зловживати JSON. Але натомість, чому б не зловживати основними сценаріями мови?

Редагувати Початкова відповідь ставила опис праворуч, використовуючи його # add comments hereдля завершення; однак це не працює в Windows, тому що прапори (наприклад, npm запускають myframework - --myframework-flags) будуть ігноровані. Я змінив свою відповідь, щоб змусити її працювати на всіх платформах, і додав деякі відступи для цілей читання.

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

Це буде:

1. Не порушуйте відповідність JSON (або, принаймні, це не зламайте, і ваш IDE не дасть вам попередження за вчинення дивних, небезпечних речей)
2. Працює міжплатформою (тестується на macOS та Windows, припускаючи, що це буде добре працювати в Linux)
3. Не заважає бігу npm run myframework -- --help
4. Під час запуску буде виводитися змістовна інформація npm run (що є фактичною командою для запуску для отримання інформації про доступні сценарії)
5. Представляє більш чітку довідкову команду (якщо деякі розробники не знають, що npm run представляє такий вихід)
6. Показує обидві команди та її опис під час запуску самої команди
7. Дещо читається під час відкриття package.json(за допомогою lessабо улюбленого IDE)

Ось мій коментар у package.json/bower.json :

Я маю, package.json.jsщо містить сценарій, який експортує фактичний package.json. Запуск сценарію перезаписує старий package.jsonі повідомляє, які зміни він вніс, ідеально допомагаючи відстежувати автоматичні зміни npm. Таким чином я навіть можу програмно визначити, які пакунки я хочу використовувати.

Останнє завдання на грунт тут: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Я закінчив scriptsтак:

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

Моя мета тут не в тому, щоб уточнити один рядок, а просто мати якісь роздільники між моїми сценаріями для бекенда, фронтену, усіх тощо.

Я не є великим шанувальником 1a, 1b, 1c, 2a, ... але клавіші різні, і у мене взагалі немає такої проблеми.

Як пояснюється ця відповідь , //ключ був зарезервований, тому його можна використовувати умовно для коментарів. Проблема з //коментарем полягає в тому, що він не може бути використаний у dependenciesта devDependenciesяк звичайна залежність із рядком як обмеження версії:

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

запускає помилку,

npm ERR! код EINVALIDPACKAGENAME

npm ERR! Неправильне ім'я пакету "//": ім'я може містити лише символи, сприятливі для URL-адреси

Хоча ключі з рядковими значеннями вважаються недійсними залежностями та ефективно ігноруються:

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

Саму залежність можна коментувати так само:

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

Оскільки залежності сортуються, коли package.json модифікується NPM, розміщувати коментар вище залежності, на яку він посилається, недоцільно.

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

Ключ коментаря повинен бути названий відповідно, якщо він стосується конкретного рядка, тому його не буде переміщено:

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

Коментар, застосовний до конкретної залежності, може бути доданий як частина semver:

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

Зауважте, що якщо перша частина раніше ORне відповідає, коментар може бути проаналізований, наприклад 1.x.

Ці способи вирішення сумісні з усіма поточними версіями NPM (6 і новіші).

Оскільки більшість розробників знайомі з документацією на основі тегів / анотацій, умова, яку я почав використовувати, схожа. Ось смак:

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

Примітка: Для dependencies, devDependenciesі т.д секцій, коментар анотації не можуть бути додані безпосередньо над окремими залежностях пакетів всередині об'єкта конфігурації , так як npmочікує , що ключ бути ім'я пакета НМП. Звідси і причина@comment dependencies .

Примітка. У певних контекстах, таких як об'єкт скриптів, деякі редактори / IDE можуть скаржитися на масив. У контексті сценаріїв VS Code очікує рядок для значення, а не масив.

Мені подобається спосіб додавання коментарів до JSON у стилі анотації / тегів, оскільки @символ виділяється із звичайних декларацій.

Підсумовуючи всі ці відповіді:

1. Додати одне назване поле верхнього рівня,// яке містить рядок коментарів. Це працює, але це відстійно, оскільки ви не можете ставити коментарі поруч із тим, що вони коментують.

2. Додайте кілька полів верхнього рівня, починаючи з // , наприклад, //dependenciesщо містить рядок коментарів. Це краще, але це все ще дозволяє лише робити коментарі вищого рівня. Ви не можете коментувати індивідуальні залежності.

3. Додайте echoкоманди до свого scripts. Це працює, але це смокче, тому що ви можете використовувати його лише в scripts.

Ці рішення також всі не дуже читабельні. Вони додають тонну зорового шуму, і IDE не будуть виділяти їх синтаксисом як коментарями.

Я думаю, що єдине розумне рішення - це генерувати package.jsonфайл з іншого файлу. Найпростіший спосіб - написати свій JSON як Javascript і використовувати Node для його запису package.json. Збережіть цей файл як package.json.mjs, chmod +xвін, і тоді ви можете просто запустити його для створення вашого 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));

Він використовує //ключ, щоб застерегти людей від редагування. \x40generatedє навмисним. Це перетворюється на @generatedвpackage.json і означає , що деякі системи код огляд будуть згортатися файлом за умовчанням.

Це додатковий крок у вашій системі збирання, але він перемагає всі інші хаки тут.

Оскільки дублюючі ключі коментарів видаляються за допомогою інструментів package.json (npm, пряжа тощо), я прийшов до використання хешованої версії, яка дозволяє краще читати як кілька рядків, так і ключів, як

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

який є "дійсним", згідно з моїм IDE як кореневий ключ, але всередині dependenciesнього скаржиться на очікування рядкового значення.

Ще один хак. Я створив сценарій для читанняpackage.json як контекст шаблону рулі.

Код нижче, якщо хтось вважає такий підхід корисним:

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

файл шаблону рульових панелей 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"

}}}

Для npm package.json знайшли два способи (прочитавши цю розмову):

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

Але з оновленням або перевстановленням пакета з "--save" або "--save-dev, коментуйте на зразок" ^ 4.1.0! коментар "у відповідному місці буде видалено. І все це порушить npm аудит.

Моє враження від розчарування в коментарі JSON. Я створюю нові вузли, названі для вузлів, на які вони посилаються, але з префіксом підкресленнями. Це недосконало, але функціонально.

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