Хорошо это или плохо, но содержимое package.json становится все сложнее и сложнее. В дни зарождения npm файл представлял собой просто некоторые метаданные о зависимостях, от которых зависел проект / пакет. Проекты становились сложнее, и теперь тестирование, фреймворки, другие библиотеки - все это зависимости, которые, казалось бы, сидят вместе. Было некоторое разделение с dependencies
и devDependencies
, но это грубая категоризация. У нас есть инструменты, которые теперь вносят вклад и размещаются в package.json с большей сложностью ... конфигурации monorepo, конфигурации lint, конфигурации фиксации, хуки git, nodemon, jest, список можно продолжить ...
Комментарии предлагают способ объяснить всю сложность.
Я по-прежнему считаю, что сопровождающие библиотеки должны по-прежнему использовать чистый JSON для обратной совместимости, но, по крайней мере, предложение этого продвижения вперед позволит создателям проектов (подавляющему большинству пользователей) возможность документировать свой package.json. Конечно, json позволяет дублировать ключи в качестве комментариев, но это слишком похоже на взлом.
Отредактированный и надуманный пример:
{
"name": "my-project",
"version": "0.0.1",
"license": "MIT",
"scripts": {
"build": "a bunch of scripts",
"ci": "a bunch of scripts",
"ci:local": "a bunch of scripts",
"docsite": "a bunch of scripts",
"docsite:combiner": "a bunch of scripts",
"docsite:sassdoc": "a bunch of scripts",
"docsite:tsdoc": "a bunch of scripts",
"e2e": "a bunch of scripts",
"html-sketchapp-install": "a bunch of scripts",
"html-sketchapp": "a bunch of scripts",
"lint": "a bunch of scripts",
"sassdoc": "a bunch of scripts",
"sassdoc:comp": "a bunch of scripts",
"sassdoc:core": "a bunch of scripts",
"start": "a bunch of scripts",
"start:hmr": "a bunch of scripts",
"start:qa": "a bunch of scripts",
"start:dev": "a bunch of scripts",
"generate-examples": "a bunch of scripts",
"rebuild-markdown": "a bunch of scripts",
"watch-examples": "a bunch of scripts",
"test:cov": "a bunch of scripts",
"test": "jest",
"test:watch": "jest --watch",
"test:cc": "jest --coverage"
},
"config": {
"commitizen": {
"path": "./node_modules/cz-conventional-changelog"
}
},
"dependencies": {
"@angular-devkit/build-angular": "~0.900.1",
"@angular-devkit/build-ng-packagr": "~0.900.1",
"@angular-devkit/core": "~9.0.0",
"@angular-devkit/schematics": "~9.0.0",
"@angular/animations": "~9.0.0",
"@angular/cdk": "~9.0.0",
"@angular/cli": "~9.0.1",
"@angular/common": "~9.0.0",
"@angular/compiler": "~9.0.0",
"@angular/compiler-cli": "~9.0.0",
"@angular/core": "~9.0.0",
"@angular/forms": "~9.0.0",
"@angular/language-service": "~9.0.0",
"@angular/platform-browser": "~9.0.0",
"@angular/platform-browser-dynamic": "~9.0.0",
"@angular/router": "~9.0.0",
"@angular/service-worker": "~9.0.0",
"@angularclass/hmr": "2.1.3",
"@ngrx/effects": "~8.6.0",
"@ngrx/entity": "~8.6.0",
"@ngrx/router-store": "~8.6.0",
"@ngrx/schematics": "~8.6.0",
"@ngrx/store": "~8.6.0",
"@ngrx/store-devtools": "~8.6.0",
"@types/jasmine": "~3.5.0",
"@types/jasminewd2": "~2.0.3",
"@types/lodash-es": "^4.17.3",
"@types/node": "^12.11.1",
"classlist.js": "1.1.20150312",
"codelyzer": "^5.1.2",
"console-polyfill": "0.3.0",
"core-js": "^2.5.4",
"cz-conventional-changelog": "1.2.0",
"date-fns": "1.30.1",
"highcharts": "^7.2.1",
"highcharts-angular": "^2.4.0",
"html2canvas": "^1.0.0-rc.5",
"jasmine-core": "~3.5.0",
"jasmine-spec-reporter": "~4.2.1",
"karma": "~4.3.0",
"karma-chrome-launcher": "~3.1.0",
"karma-coverage-istanbul-reporter": "~2.1.0",
"karma-jasmine": "~2.0.1",
"karma-jasmine-html-reporter": "^1.4.2",
"lodash-es": "^4.17.11",
"mime": "~2.4.2",
"ngrx-store-freeze": "0.2.4",
"ngx-monaco-editor": "~8.0.0",
"ngx-quill": "^7.3.12",
"pdfmake": "^0.1.64",
"prettier": "1.19.1",
"protractor": "~5.4.3",
"quill": "^1.3.7",
"rxjs": "~6.5.4",
"rxjs-compat": "^6.0.0",
"standard-changelog": "1.0.19",
"svgxuse": "1.2.6",
"ts-node": "~8.3.0",
"tsickle": "^0.35.0",
"tslib": "^1.10.0",
"tslint": "~5.18.0",
"typescript": "~3.7.5",
"web-animations-js": "~2.3.1",
"zone.js": "~0.10.2"
},
"devDependencies": {
"@types/jest": "^24.0.6",
"jest": "^24.1.0",
"jest-preset-angular": "^6.0.2",
"ts-node": "~7.0.1",
"typescript": "3.2.4"
},
"jest": {
"preset": "jest-preset-angular",
"setupTestFrameworkScriptFile": "<rootDir>/setupJest.ts"
},
"nodemonConfig": {
"ignore": [
"**/example-module.ts"
],
"watch": [
"./a/bunch/of/stuff"
],
"ext": "js ts md html"
},
"workspaces": {
"packages": [
"packages/*"
],
"nohoist": [
"**"
]
}
}
Пример package.json с комментариями.
{
"name": "my-project",
"version": "0.0.1",
"license": "MIT",
"scripts": {
"build": "a bunch of scripts",
"ci": "a bunch of scripts",
"ci:local": "a bunch of scripts",
// for building our documentation site
"docsite": "a bunch of scripts",
"docsite:combiner": "a bunch of scripts",
"docsite:sassdoc": "a bunch of scripts",
"docsite:tsdoc": "a bunch of scripts",
"e2e": "a bunch of scripts",
"lint": "a bunch of scripts",
"sassdoc": "a bunch of scripts",
"sassdoc:comp": "a bunch of scripts",
"sassdoc:core": "a bunch of scripts",
"start": "a bunch of scripts",
"start:hmr": "a bunch of scripts",
"start:qa": "a bunch of scripts",
"start:dev": "a bunch of scripts",
"generate-examples": "a bunch of scripts",
"rebuild-markdown": "a bunch of scripts",
"watch-examples": "a bunch of scripts",
"test:cov": "a bunch of scripts",
"test": "jest",
"test:watch": "jest --watch",
"test:cc": "jest --coverage"
},
"config": {
"commitizen": {
"path": "./node_modules/cz-conventional-changelog"
}
},
"dependencies": {
// ANGULAR
"@angular-devkit/build-angular": "~0.900.1",
"@angular-devkit/build-ng-packagr": "~0.900.1",
"@angular-devkit/core": "~9.0.0",
"@angular-devkit/schematics": "~9.0.0",
"@angular/animations": "~9.0.0",
"@angular/cdk": "~9.0.0",
"@angular/cli": "~9.0.1",
"@angular/common": "~9.0.0",
"@angular/compiler": "~9.0.0",
"@angular/compiler-cli": "~9.0.0",
"@angular/core": "~9.0.0",
"@angular/forms": "~9.0.0",
"@angular/language-service": "~9.0.0",
"@angular/platform-browser": "~9.0.0",
"@angular/platform-browser-dynamic": "~9.0.0",
"@angular/router": "~9.0.0",
"@angular/service-worker": "~9.0.0",
"@angularclass/hmr": "2.1.3",
"zone.js": "~0.10.2",
"rxjs": "~6.5.4",
"rxjs-compat": "^6.0.0",
// polyfills for angular
"console-polyfill": "0.3.0",
"core-js": "^2.5.4",
"classlist.js": "1.1.20150312",
"svgxuse": "1.2.6",
"web-animations-js": "~2.3.1",
// lint management
"codelyzer": "^5.1.2",
"prettier": "1.19.1",
"tslint": "~5.18.0",
// changelog creation
"cz-conventional-changelog": "1.2.0",
"standard-changelog": "1.0.19",
// ngrx state management
"@ngrx/effects": "~8.6.0",
"@ngrx/entity": "~8.6.0",
"@ngrx/router-store": "~8.6.0",
"@ngrx/schematics": "~8.6.0",
"@ngrx/store": "~8.6.0",
"@ngrx/store-devtools": "~8.6.0",
"ngrx-store-freeze": "0.2.4",
// library deps
// Graphs support
"highcharts": "^7.2.1",
"highcharts-angular": "^2.4.0",
// for creating pdfs
"html2canvas": "^1.0.0-rc.5",
"pdfmake": "^0.1.64",
// rich text support
"ngx-quill": "^7.3.12",
"quill": "^1.3.7",
// testing
"jasmine-core": "~3.5.0",
"jasmine-spec-reporter": "~4.2.1",
"karma": "~4.3.0",
"karma-chrome-launcher": "~3.1.0",
"karma-coverage-istanbul-reporter": "~2.1.0",
"karma-jasmine": "~2.0.1",
"karma-jasmine-html-reporter": "^1.4.2",
// e2e testing
"protractor": "~5.4.3",
// typscript and compilation
"ts-node": "~8.3.0",
"tsickle": "^0.35.0",
"tslib": "^1.10.0",
"typescript": "~3.7.5",
// misc deps
"date-fns": "1.30.1",
"lodash-es": "^4.17.11",
"mime": "~2.4.2"
},
"devDependencies": {
"@types/jasmine": "~3.5.0",
"@types/jasminewd2": "~2.0.3",
"@types/lodash-es": "^4.17.3",
"@types/node": "^12.11.1",
"@types/jest": "^24.0.6",
"jest": "^24.1.0",
"jest-preset-angular": "^6.0.2",
"ts-node": "~7.0.1",
"typescript": "3.2.4"
},
// complicated jest configuration here
"jest": {
"preset": "jest-preset-angular",
"setupTestFrameworkScriptFile": "<rootDir>/setupJest.ts"
},
// use nodemon to trigger stuff
"nodemonConfig": {
"ignore": [
"**/example-module.ts"
],
"watch": [
"./a/bunch/of/stuff"
],
"ext": "js ts md html"
},
// extra libraries we are creating internally
"workspaces": {
"packages": [
"packages/*"
],
"nohoist": [
"**"
]
}
}
https://github.com/microsoft/node-jsonc-parser
Typescript использует комментарии в своих файлах tsconfig.json.
@admosity, к сожалению, это будет обратно несовместимо: / Кроме того, для понимания нового синтаксиса потребуется все другое программное обеспечение, использующее package.json, а также многие пакеты npm ...
это было бы обратно несовместимо
У вас может быть два файла для обеспечения обратной совместимости:
package.json
package.json5
Пользователь просто отредактирует package.json5, чтобы добавить комментарии. Npm может создать (или переопределить) package.json и просто игнорировать комментарии из package.json5.
Любая новая функция по определению обратно несовместима - разве это не нормально и по своей природе прогрессирует в развитии любого программного обеспечения?
Помимо того, что их очень легко исправить в других проектах, которые загружают package.json
, просто добавив пакет и заменив JSON
на JSON5
- API-интерфейсы идентичны.
Некоторое время назад Babel добавил поддержку JSON5, и сообщество просто движется вперед и исправляет эти крошечные проблемы, что совсем не требует времени - и улучшения JSON5 просто как бы органично распространяются на другие пакеты, улучшения документации распространяются на проекты и так далее.
Кажется, это хорошо.
ИМО, не добавляйте больше сложности / путаницы, чтобы дать повод не двигаться вперед.
Самый полезный комментарий
Любая новая функция по определению обратно несовместима - разве это не нормально и по своей природе прогрессирует в развитии любого программного обеспечения?
Помимо того, что их очень легко исправить в других проектах, которые загружают
package.json
, просто добавив пакет и заменивJSON
наJSON5
- API-интерфейсы идентичны.Некоторое время назад Babel добавил поддержку JSON5, и сообщество просто движется вперед и исправляет эти крошечные проблемы, что совсем не требует времени - и улучшения JSON5 просто как бы органично распространяются на другие пакеты, улучшения документации распространяются на проекты и так далее.
Кажется, это хорошо.
ИМО, не добавляйте больше сложности / путаницы, чтобы дать повод не двигаться вперед.