осторожно, не используйте package.json в качестве имени папки, если вы хотите клонировать этот проект на свой компьютер — это приведет к поломке yarn ( An unexpected error occurred: "EISDIR: illegal operation on a directory, read". ).
Исходная версия этого документа скопирована из Yarnpkg.
См. также документацию npm, std-pkg, clean-publish, package-json-validator, cosmiconfig, rc (как альтернативный подход к cosmiconfig).
nameversiondescriptionkeywordslicensehomepagebugsrepositoryauthorcontributorsfilesmainbinmandirectoriesscriptsscripts npmconfigdependenciesdevDependenciespeerDependenciesoptionalDependenciesbundledDependenciesenginesoscpulibcprivatepublishConfigflatresolutionsworkspacesboltunpkgtypesflow:mainbrowserslistmodulebrowseresnextes2015esmmodule-browsermodules.rootjsnext:mainreact-nativesideEffectssource , umd:mainsource@std/esmjspmignoreformatregistryshimmapbrowserify.transformproxyhomepagebabeleslintConfigjeststylelintsize-limitpwmetricsavanycpreferGlobalstylelessstandard Два наиболее важных поля в вашем package.json — это name и version , без них ваш пакет не сможет быть установлен. Поля name и version используются вместе для создания уникального идентификатора.
name{
"name" : " my-awesome-package "
} Это имя вашего пакета. Он используется в URL-адресах, как аргумент в командной строке и как имя каталога внутри node_modules .
yarn add [name] node_modules/[name]
https://registry.npmjs.org/[name]/-/[name]-[version].tgz
Правила
@scope/ для пакетов с ограниченной областью действия).. ) или подчеркивания ( _ ).Советы
js или node .require() .version{
"version" : " 1.0.0 "
}Текущая версия вашего пакета.
description{
"description" : " My short description of my awesome package "
}Описание — это просто строка, которая помогает людям понять назначение пакета. Его также можно использовать при поиске пакетов в менеджере пакетов.
keywords{
"keywords" : [ " short " , " relevant " , " keywords " , " for " , " searching " ]
}Ключевые слова — это массив строк, которые полезны при поиске пакетов в менеджере пакетов.
license{
"license" : " MIT " ,
"license" : " (MIT or GPL-3.0) " ,
"license" : " SEE LICENSE IN LICENSE_FILENAME.txt " ,
"license" : " UNLICENSED "
}Во всех пакетах должна быть указана лицензия, чтобы пользователи знали, как им разрешено ее использовать и какие ограничения вы накладываете на нее.
Вам рекомендуется использовать лицензию с открытым исходным кодом (одобренную OSI), если у вас нет особых причин не делать этого. Если вы создали свой пакет в рамках своей работы, вероятно, лучше проконсультироваться с вашей компанией, прежде чем принимать решение о лицензии.
Должно быть одно из следующих:
SEE LICENSE IN <filename> , указывающая на <filename> на верхнем уровне вашего пакета, если вы используете нестандартную лицензию.UNLICENSED , если вы не хотите предоставлять другим право использовать частный или неопубликованный пакет на любых условиях. Различные ссылки на документацию, места для проблем с файлами и местонахождение кода вашего пакета.
homepage{
"homepage" : " https://your-package.org "
}Домашняя страница — это URL-адрес целевой страницы или документации для вашего пакета.
Также используется приложением Create React.
bugs{
"bugs" : " https://github.com/user/repo/issues "
}URL-адрес системы отслеживания проблем вашего проекта. Это также может быть что-то вроде адреса электронной почты. Он дает пользователям возможность узнать, куда отправлять проблемы с вашим пакетом.
repository{
"repository" : { "type" : " git " , "url" : " https://github.com/user/repo.git " },
"repository" : " github:user/repo " ,
"repository" : " gitlab:user/repo " ,
"repository" : " bitbucket:user/repo " ,
"repository" : " gist:a1b2c3d4e5f "
}Репозиторий — это место, где находится реальный код вашего пакета.
Сопровождающие вашего проекта.
author{
"author" : { "name" : " Your Name " , "email" : " [email protected] " , "url" : " http://your-website.com " },
"author" : " Your Name <[email protected]> (http://your-website.com) "
}Информация об авторе пакета. Автор – один человек.
contributors{
"contributors" : [
{ "name" : " Your Friend " , "email" : " [email protected] " , "url" : " http://friends-website.com " }
{ "name" : " Other Friend " , "email" : " [email protected] " , "url" : " http://other-website.com " }
],
"contributors" : [
" Your Friend <[email protected]> (http://friends-website.com) " ,
" Other Friend <[email protected]> (http://other-website.com) "
]
}Те, кто внес свой вклад в ваш пакет. Участники — это множество людей.
Вы можете указать файлы, которые будут включены в ваш проект, а также основную точку входа для вашего проекта.
files{
"files" : [
" filename.js " ,
" directory/ " ,
" glob/*.{js,json} "
]
}Это файлы, которые включены в ваш проект. Вы можете указать отдельные файлы, целые каталоги или использовать подстановочные знаки для включения файлов, соответствующих определенным критериям.
main{
"main" : " filename.js "
}Это основная точка входа для функциональности вашего проекта.
bin{
"bin" : " bin.js " ,
"bin" : {
"command-name" : " bin/command-name.js " ,
"other-command" : " bin/other-command "
}
}Исполняемые файлы, включенные в ваш проект, которые будут установлены.
man{
"man" : " ./man/doc.1 " ,
"man" : [ " ./man/doc.1 " , " ./man/doc.2 " ]
}Если у вас есть справочные страницы, связанные с вашим проектом, добавьте их сюда.
directories{
"directories" : {
"lib" : " path/to/lib/ " ,
"bin" : " path/to/bin/ " ,
"man" : " path/to/man/ " ,
"doc" : " path/to/doc/ " ,
"example" : " path/to/example/ "
}
}При установке пакета вы можете указать точные места для размещения двоичных файлов, страниц руководства, документации, примеров и т. д.
Ваш пакет может включать в себя запускаемые сценарии или другую конфигурацию.
scripts{
"scripts" : {
"build-project" : " node build-project.js "
}
} Скрипты — отличный способ автоматизации задач, связанных с вашим пакетом, таких как простые процессы сборки или инструменты разработки. Используя поле "scripts" , вы можете определить различные сценарии, которые будут запускаться как yarn run <script> . Например, приведенный выше сценарий build-project можно вызвать с помощью yarn run build-project и запустить node build-project.js .
Некоторые имена сценариев являются особенными. Если задано, сценарий preinstall вызывается Yarn перед установкой вашего пакета. По соображениям совместимости сценарии install , postinstall и prepublish будут вызываться после завершения установки вашего пакета.
Значение start сценария по умолчанию равно node server.js .
"scripts": {"start": "node server.js"}. Если в корне вашего пакета есть файл server.js, то npm по умолчанию будет использовать команду запуска узла server.js.
"scripts":{"preinstall": "node-gyp rebuild"}. Если в корне вашего пакета есть файлbinding.gyp, npm по умолчанию выполнит команду предварительной установки для компиляции с использованием node-gyp.-- документация npm
scripts npm npm поддерживает свойство scripts файла package.json для следующих сценариев:
prepublish : запускать ДО того, как пакет будет упакован и опубликован, а также при локальной установке npm без каких-либо аргументов. (См. ниже)prepare : запустить как ДО того, как пакет будет упакован и опубликован, так и при локальной установке npm без каких-либо аргументов (см. ниже). Это запускается ПОСЛЕ предварительной публикации, но только ДО предварительной публикации.prepublishOnly : Запускается ДО того, как пакет будет подготовлен и упакован, ТОЛЬКО при публикации npm. (См. ниже.)prepack : запускать ДО того, как архив будет упакован (в пакете npm, публикации npm и при установке зависимостей git)postpack : Запускать ПОСЛЕ того, как tar-архив был создан и перемещен в конечный пункт назначения.publish , postpublish : Запускается ПОСЛЕ публикации пакета.preinstall : запустить ДО установки пакета.install , postinstall : запускать ПОСЛЕ установки пакета.preuninstall , uninstall : запустить ПЕРЕД удалением пакета.postuninstall : Запускается ПОСЛЕ удаления пакета.preversion : запускать ПЕРЕД обновлением версии пакета.version : запускать ПОСЛЕ обновления версии пакета, но ДО фиксации.postversion : запускать ПОСЛЕ обновления версии пакета и ПОСЛЕ фиксации.pretest , test , posttest : запускается командой npm test.prestop , stop , poststop : запускается командой npm stop.prestart , start , poststart : запускается командой npm start.prerestart , restart , postrestart : запускается командой перезапуска npm. Примечание. npm restart запустит сценарии остановки и запуска, если сценарий перезапуска не указан.preshrinkwrap , shrinkwrap , postshrinkwrap : Запускается командой npm Shrinkwrap.Источник: документация npm.
config{
"config" : {
"port" : " 8080 "
}
}Параметры конфигурации или параметры, используемые в ваших сценариях.
Ваш пакет, скорее всего, будет зависеть от других пакетов. Вы можете указать эти зависимости в файле package.json .
dependencies{
"dependencies" : {
"package-1" : " ^3.1.4 "
}
}Это зависимости, которые необходимы как при разработке, так и при производстве вашего пакета.
Вы можете указать точную версию, минимальную версию (например,
>=) или диапазон версий (например>= ... <).
devDependencies{
"devDependencies" : {
"package-2" : " ^0.4.2 "
}
}Это пакеты, которые необходимы только при разработке вашего пакета, но не будут установлены в рабочей среде.
peerDependencies{
"peerDependencies" : {
"package-3" : " ^2.7.18 "
}
}Одноранговые зависимости позволяют вам указать совместимость вашего пакета с версиями других пакетов.
optionalDependencies{
"optionalDependencies" : {
"package-5" : " ^1.6.1 "
}
}С вашим пакетом можно использовать дополнительные зависимости, но это не обязательно. Если дополнительный пакет не найден, установка продолжится.
bundledDependencies{
"bundledDependencies" : [
" package-4 "
]
}Связанные зависимости — это массив имен пакетов, которые будут объединены при публикации вашего пакета.
Вы можете предоставить информацию системного уровня, связанную с вашим пакетом, например совместимость операционной системы и т. д.
engines{
"engines" : {
"node" : " >=4.4.7 <7.0.0 " ,
"zlib" : " ^1.2.8 " ,
"yarn" : " ^0.14.0 "
}
} В механизмах указаны версии клиентов, которые необходимо использовать с вашим пакетом. Это проверяет как process.versions так и текущую версию пряжи.
os{
"os" : [ " darwin " , " linux " ],
"os" : [ " !win32 " ]
} Это определяет совместимость операционной системы для вашего пакета. Он проверяет process.platform .
cpu{
"cpu" : [ " x64 " , " ia32 " ],
"cpu" : [ " !arm " , " !mips " ]
} Используйте это, чтобы указать, что ваш пакет будет работать только на определенных архитектурах ЦП. Это проверяется на process.arch .
libc{
"libc" : [ " glibc " ],
"libc" : [ " musl " ]
} Используйте это, чтобы указать, что ваш пакет работает только на определенной версии libc. Это проверяет результат detect-libc .
private{
"private" : true
} Если вы не хотите, чтобы ваш пакет публиковался в менеджере пакетов, установите для этого параметра значение true .
publishConfig{
"publishConfig" : {
...
}
}Эти значения конфигурации будут использоваться при публикации вашего пакета. Например, вы можете пометить свою посылку.
flat{
"flat" : true
} Если ваш пакет допускает только одну версию данной зависимости, и вы хотите обеспечить то же поведение, что и yarn install --flat в командной строке, установите для этого параметра значение true .
Обратите внимание, что если ваш package.json содержит "flat": true и другие пакеты зависят от вашего (например, вы создаете библиотеку, а не приложение), этим другим пакетам также потребуется "flat": true в их package.json или быть устанавливается с помощью yarn install --flat в командной строке.
resolutions{
"resolutions" : {
"transitive-package-1" : " 0.0.29 " ,
"transitive-package-2" : " file:./local-forks/transitive-package-2 " ,
"dependencies-package-1/transitive-package-3" : " ^2.1.1 "
}
}Позволяет переопределить версию определенной вложенной зависимости. Полную спецификацию см. в RFC «Разрешения для выборочных версий».
Обратите внимание, что установка зависимостей с помощью [ yarn install --flat ] автоматически добавит блок resolutions в ваш файл package.json .
workspaces Если --use-workspaces имеет значение true, packages будут переопределены значением из package.json/workspaces .
Источник: --use-workspaces.
boltСм. Конфигурацию
{
"bolt" : {
"workspaces" : [
" utils/* " ,
" apps/* "
]
}
}unpkg Если вы опустите путь к файлу (т. е. используете «голый» URL-адрес), unpkg будет обслуживать файл, указанный в поле unpkg в package.json , или вернется к main (источнику).
types Если в вашем пакете есть основной файл .js , вам также необходимо указать основной файл объявления в файле package.json . Установите свойство types , чтобы оно указывало на ваш связанный файл декларации. Например:
{
"main" : " ./lib/main.js " ,
"types" : " ./lib/main.d.ts "
} Обратите внимание, что поле typings является синонимом types и также может использоваться.
Также обратите внимание: если ваш основной файл объявлений называется index.d.ts и находится в корне пакета (рядом с index.js ), вам не нужно отмечать свойство types , хотя это желательно сделать.
Источник: документация TypeScript.
Примечание: во Flow используется другой подход.
flow:mainОфициально не поддерживается. Предложение здесь.
browserslist? Библиотека для совместного использования целевых браузеров различными интерфейсными инструментами. Он используется в:
package.json или файлах browserslist поддерживаемых в версии 2.0) Все инструменты, использующие Browserslist, автоматически найдут его конфигурацию, если вы добавите в package.json следующее:
{
"browserslist" : [
" > 1% " ,
" last 2 versions "
]
}Источник: список браузеров.
См. также: Создание поддержки приложений React.
Введение см. в разделе «Настройка многоплатформенных пакетов npm».
module pkg.module будет указывать на модуль, который имеет синтаксис модуля ES2015, но в остальном только функции синтаксиса, которые поддерживаются целевыми средами. Полное описание здесь.
Поддерживается: накопительный пакет, веб-пакет
browser Поле browser предоставляется автором модуля как подсказка для сборщиков javascript или инструментов компонентов при упаковке модулей для использования на стороне клиента. Предложение здесь.
Поддерживается: накопительный пакет, веб-пакет, браузерификация
Запрошена поддержка: Babel-plugin-module-resolver
esnextПолное предложение здесь. Краткое объяснение:
esnext : исходный код, использующий функции этапа 4 (или старше), не транспилированный в модули ES.main : указывает на модуль CommonJS (или модуль UMD) с настолько современным JavaScript, насколько Node.js в настоящее время может обрабатывать.module можно обрабатывать через esnext .browser можно управлять через расширенную версию esnext {
"main" : " main.js " ,
"esnext" : {
"main" : " main-esnext.js " ,
"browser" : " browser-specific-main-esnext.js "
}
}См. также: Доставка нетранспилированного исходного кода через npm.
es2015Нетранспилированный код ES6. Источник: Формат пакета Angular (APF) v5.0.
esmПредложение здесь: скорректированное предложение: модуль ES "esm": истинный флаг package.json
См. также:
module-browserПосмотреть этот выпуск
Также называется moduleBrowser , jsnext:browser .
modules.rootУпоминается в статье «В защиту .js».
Существует также modules.resolver .
jsnext:mainУСТАРЕЛО
jsnext:main был заменен на pkg.module , который указывает расположение файла с объявлениями импорта/экспорта. Оригинальное предложение здесь.
При поддержке: Rollup.
react-native Работает аналогично browser , но для конкретных модулей, реагирующих на реакцию. Источник.
sideEffectsУказывает, что модули пакета не имеют побочных эффектов (при оценке) и предоставляют только экспорт. Это позволяет таким инструментам, как Webpack, оптимизировать реэкспорт.
См. также: пример sideEffects , предложение по маркировке функций как чистых, eslint-plugin-tree-shaking.
source , umd:mainСм. раздел Указание сборок в package.json.
sourceСм. package-bundler/parcel#1652.
@std/esm У разработчиков есть твердое мнение практически обо всем. В соответствии с этим @std/esm позволяет разблокировать дополнительные функции с помощью поля "@std/esm" или "@std":{"esm":{}} в вашем package.json .
Источник: @std/esm
jspm Вы можете написать все свойства пакета в основе package.json или, если вы не хотите изменять существующие свойства, которые вы хотели бы использовать специально для npm , вы можете написать свою конфигурацию, специфичную для jspm, внутри свойства jspm package.json и jspm будут использовать эти параметры вместо параметров конфигурации корневого уровня.
Например:
{
"name" : " my-package " ,
"jspm" : {
"main" : " jspm-main "
}
}См. полную спецификацию.
ignoreЕсли есть определенные файлы или папки, которые следует игнорировать, их можно перечислить в массиве.
format Варианты: esm , amd , cjs и global .
При загрузке модулей из
npmформат модуля по умолчанию рассматривается какcjs, и автоматическое определение не выполняется. Для загрузки модулей другого формата вам придется переопределить это свойство вручную.
Формат модуля
esm(модуль ECMAScript) в настоящее время не используется в package.json.
registryjspm понимает зависимости в контексте реестра.
При загрузке пакетов из npm jspm установит реестр по умолчанию на npm и соответствующим образом обработает зависимости.
При загрузке пакетов из GitHub свойство зависимостей игнорируется без присутствия свойства реестра, поскольку jspm не имеет возможности узнать, что означают зависимости для существующих репозиториев GitHub.
Установка свойства реестра также определяет, как jspm интерпретирует пакет. Например, пакет GitHub с registry: "npm" , наряду с получением его зависимостей от npm, будет интерпретироваться как CommonJS и поддерживать такие функции, как каталог и требуемые JSON, точно так же, как если бы он был установлен с конечной точки npm с самого начала.
Зависимости пакета на GitHub, для которого установлено значение registry: "jspm" будут рассматриваться как зависимости в стиле jspm.
shim Пакетам, написанным как глобальные переменные, необходима конфигурация прокладки для правильной работы в модульной среде. Чтобы разместить файл some/global.js внутри пакета, мы можем написать:
{
"shim" : {
"some/global" : {
"deps" : [ " jquery " ],
"exports" : " globalExportName "
}
}
} И deps , и exports не являются обязательными.
exports автоматически обнаруживается загрузчиком SystemJS, как и любые глобальные переменные, написанные сценарием. В большинстве случаев это обнаружение будет работать правильно.
Сокращённая форма "some/global": ["jquery"] также поддерживается, если exports нет.
mapКонфигурация карты перепишет внутренние требования, чтобы указать на разные локальные или внешние модули.
Рассмотрим пакет, который включает собственную зависимость dep , расположенную по адресу third_party/dep . Внутри него может быть оператор require что-то вроде:
require ( 'dep' ) ;Чтобы использовать локальную версию, мы можем написать:
{
"map" : {
"dep" : " ./third_party/dep "
}
}Также может быть полезно ссылаться на пакет по его собственному имени внутри подмодулей:
{
"map" : {
"thispackage" : " . "
}
} Тогда у нас могут быть внутренние требования для правильного import 'thispackage/module' .
Конфигурация карты также может ссылаться на подмодули зависимостей.
Мы также можем полностью исключить модули, сопоставив их с пустым модулем:
{
"map" : {
"jquery" : " @empty "
}
}Возвращаемое значение тогда будет объектом модуля без экспорта.
browserify.transformДокументация здесь
proxyЛюди часто обслуживают интерфейсное приложение React с того же хоста и порта, что и их серверная реализация.
Источник: Проксирование запросов API в разработке.
homepageИсточник: Создание относительных путей.
babelПосмотрите этот выпуск.
eslintConfigjest{
"jest" : {
"verbose" : true
}
}
Источник: шуточная документация
stylelintСм.: Новый загрузчик конфигурации.
size-limit Если вы используете эту библиотеку, вы можете определить ее конфигурацию в package.json :
{
"size-limit" : [
{
"limit" : " 9 KB " ,
"path" : " index.js "
}
]
}Источник: ограничение размера
pwmetrics Вы можете указать параметры в package.json :
{
"pwmetrics" : {
"url" : " http://example.com/ " ,
"expectations" : {
"ttfcp" : {
"warn" : " >=1500 " ,
"error" : " >=2000 "
}
}
}
}Все доступные варианты здесь
Источник: pwmetrics
avaПример:
"ava" : {
"require" : [ " @std/esm " ]
}Источник: ава
nycПример:
"nyc" : {
"extension" : [ " .js " , " .mjs " ],
"require" : [ " @std/esm " ]
}Источник: Нью-Йорк
preferGlobalУСТАРЕЛО
Раньше эта опция вызывала предупреждение npm, но больше не выдает предупреждение. Это чисто для информационных целей. Теперь рекомендуется по возможности устанавливать любые двоичные файлы как локальные зависимости devDependency.
style Атрибут style в package.json полезен для импорта пакетов CSS. Предложение здесь.
Поддерживается: packageify, npm-less, rework-npm, npm-css.
См. также: istf-спец.
less То же, что style , но за меньшую цену.
Поддерживается: npm-less.
Следующие поля зарезервированы для будущего расширения: build , default , email , external , files , imports , maintainer , paths , platform , require , summary , test , using , downloads , uid .
Следующие поля зарезервированы для реестров пакетов, которые они могут использовать по своему усмотрению: id , type .
Все свойства, начинающиеся с _ или $ также зарезервированы для реестров пакетов, которые могут использовать их по своему усмотрению.
Источник: вики CommonJS.
standard Стандартный JS — это руководство по стилю JavaScript, линтер и форматтер. Вы можете добавить некоторые свойства в package.json, например parser , ignore , globals , plugins .
Пример:
"standard" : {
"parser" : " babel-eslint " ,
"ignore" : [
" **/out/ " ,
" /lib/select2/ " ,
" /lib/ckeditor/ " ,
" tmp.js "
]
}См. также: Стандартный JS.
