Как добавить комментарии к пакету.JSON для установки npm?
У меня есть простой пакет.файл 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. Я также пробовал / / комментарии к стилю.
12 ответов
это недавно обсуждалось в узел.список рассылки js.
согласно Исааку Шлютеру, который создал НПМ:
... ключ "/ / " никогда не будет использоваться 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.
надеюсь, это поможет кто-нибудь.
вы всегда можете злоупотреблять тем, что дублированные ключи перезаписываются. Вот что я только что написал:--7-->
"dependencies": {
"grunt": "...",
"grunt-cli": "...",
"api-easy": "# Here is the pull request: https://github.com/...",
"api-easy": "git://..."
"grunt-vows": "...",
"vows": "..."
}
однако неясно, разрешает ли JSON дублированные ключи (см. позволяет ли синтаксис JSON дублировать ключи в объекте?. Кажется, это работает с npm, поэтому я беру на себя риск.
рекомендуемый Хак должен использовать "//"
ключи (от список рассылки nodejs). Когда я тестировал его, он не работал с разделами "зависимости". Кроме того, пример в сообщении использует несколько "//"
keys, что означает, что npm не отклоняет файлы JSON с дублированными ключами. Другими словами, Хак выше всегда должен быть в порядке.
обновление: одним досадным недостатком дублированных ключ, что npm install --save
бесшумно устраняет все дубликаты. К сожалению, это очень легко упустить из виду, и ваши благие намерения комментарии исчезли.
на "//"
hack по-прежнему является самым безопасным, как кажется. Однако, многострочные комментарии будут удалены npm install --save
тоже.
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"
}
у меня есть забавная идея рубить.
создайте имя пакета npm соответствующим образом в качестве разделителя комментариев для dependencies
и devDependencies
блок в пакет.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": "*"
}
}
Примечание: необходимо добавить последнюю строку разделителя комментариев с допустимой версией, например *
в блоке.
вот мой взгляд на комментарии в package.json
/ bower.json
:
Я package.json.js
, который содержит скрипт, который экспортирует фактический package.json
. Запуск скрипта перезаписывает старый package.json
и говорит мне, какие изменения он сделал, идеально подходит, чтобы помочь вам отслеживать автоматические изменения npm
сделано. Таким образом, я даже могу программно определить, какие пакеты я хочу использовать.
последняя задача grunt здесь: https://gist.github.com/MarZab/72fa6b85bc9e71de5991
до сих пор большинство "хаков" здесь предлагают злоупотреблять 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"
}
}
это:
- не нарушать соответствие JSON (или, по крайней мере, его не взломать, и ваша IDE не даст вам предупреждения за странные, опасные вещи)
- работает кросс-платформенный (протестирован на macOS и windows, предполагая, что он будет работать просто отлично на Linux)
- не мешает работать
npm run myframework -- --help
- будет выводить значимую информацию при запуске
npm run
(которая является фактической командой для запуска, чтобы получить информация о доступных скриптах) - представляет более явную команду справки (в случае, если некоторые разработчики не знают, что npm run представляет такой вывод)
- покажет как команды, так и их описание При запуске самой команды
- несколько читается при открытии
package.json
(черезless
или ваша любимая IDE)
много интересных идей.
то, что я делал, это:
{
...
"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
мои 2cents для этого обсуждения:)
Я закончил с 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,... но ключи разные, и у меня нет никаких проблем вообще, как это.
мой взгляд на разочарование без комментариев в 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"
}
как дубликаты ключей комментариев удаляются запущенным пакетом.JSON tools (npm, yarn и т. д.) Я пришел к использованию хэшированной версии, которая позволяет лучше читать как несколько строк и ключей, таких как
"//": {
"alpaca": "we use the bootstrap version",
"eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
"moment-with-locales": "is part of moment"
},
что "правильных" по моему IDE как корневой ключ, но в пределах dependencies
Он жалуется, ожидая строковое значение.