Как добавить комментарии в package.json для npm install?

У меня есть простой файл 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, yarn и т. Д.) Будут удалены несколько ключей "//". Это выживает:

{ "//": [ 
  "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 diffs, либо в редакторе при работе с 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.json.x----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 run 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"
  },

Мое намерение здесь состоит не в том, чтобы уточнить одну строку, просто чтобы иметь какие-то разделители между моими сценариями для backend, frontend, all и т. Д.

Я не большой поклонник 1a, 1b, 1c, 2a, ... но ключи разные, и у меня вообще нет таких проблем.

Как объясняется в этом ответе , //ключ был зарезервирован, поэтому его можно использовать условно для комментариев. Проблема с //комментарием, что она не может быть использована в dependenciesи в devDependenciesкачестве регулярной зависимости со строкой в качестве версии ограничения:

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

вызывает ошибку,

нпм ERR! код EINVALIDPACKAGENAME

нпм 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 .

Примечание. В определенных контекстах, например, в объекте scripts, некоторые редакторы / 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, yarn и т. Д.), Я пришел к использованию хэшированной версии, которая позволяет лучше читать как несколько строк, так и ключи

"//": {
  "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 нашли 2 способа (после прочтения этого разговора):

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