Как добавить комментарии к пакету.JSON для установки npm?

вот еще один хак для добавления комментариев в 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"
  }
}

это:

1. не нарушать соответствие JSON (или, по крайней мере, его не взломать, и ваша IDE не даст вам предупреждения за странные, опасные вещи)
2. работает кросс-платформенный (протестирован на macOS и windows, предполагая, что он будет работать просто отлично на Linux)
3. не мешает работать npm run myframework -- --help
4. будет выводить значимую информацию при запуске npm run (которая является фактической командой для запуска, чтобы получить информация о доступных скриптах)
5. представляет более явную команду справки (в случае, если некоторые разработчики не знают, что npm run представляет такой вывод)
6. покажет как команды, так и их описание При запуске самой команды
7. несколько читается при открытии 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 Он жалуется, ожидая строковое значение.