2. package.json

Основные сведения

Две наиболее важные области в вашем 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

Правила

• Должно быть не более 214 символов (включая @scope/ для пакетов с областью видимости).
• Не должно начинаться с точки (.) или символа подчёркивания (_).
• Имя не должно содержать заглавных букв.
• Должны использоваться только URL-безопасные символы.

Рекомендации

• Не используйте то же имя, что и у модуля ядра Node.js
• Не включайте 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), если у вас нет особой причины этого не делать. Если вы создали пакет в рамках своей работы, лучше проконсультироваться со своей компанией, прежде чем принять решение о лицензии.

Должно быть одним из следующих:

• Действительный идентификатор лицензии SPDX, если вы используете стандартную лицензию.
• Действительное выражение лицензии SPDX 2.0, если вы используете несколько стандартных лицензий.
• Строка SEE LICENSE IN <filename>, указывающая на файл <filename> в корневой директории пакета, если вы используете нестандартную лицензию.
• Строка UNLICENSED если вы не хотите предоставлять другим право использовать частный или не опубликованный пакет на каких-либо условиях.

Ссылки

Различные ссылки на документацию, места для отправки проблем и местоположение кода вашего пакета.

homepage

{
  "homepage": "https://your-package.org"
}

Главная страница — URL-адрес стартовой страницы или документации вашего пакета.

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": "you@example.com",
    "url": "http://your-website.com"
  },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}

Информация об авторе пакета. Автор — это один человек.

contributors

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (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"]
}

Если у вашего проекта есть страницы man, добавьте их сюда.

directories

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}

При установке вашего пакета вы можете указать точные места размещения двоичных файлов, страниц man, документации, примеров и т. д.

Задачи

Ваш пакет может включать исполняемые скрипты или другую конфигурацию.

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, и prepare будут вызваны после завершения установки вашего пакета.

Значение скрипта start по умолчанию node server.js.

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

Взаимозависимости позволяют вам указать совместимость вашего пакета с версиями других пакетов.

peerDependenciesMeta

{
  "peerDependenciesMeta": {
    "package-3": {
      "optional": true
    }
  }
}

Позволяет добавлять метаданные к взаимозависимостям.

В настоящее время доступна только метка optional. Установка её в значение true подавит предупреждение о недостающей взаимозависимости.

optionalDependencies

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

Дополнительные зависимости могут использоваться с вашим пакетом, но не являются обязательными. Если дополнительный пакет не найден, установка всё равно продолжается.

bundledDependencies

{
  "bundledDependencies": ["package-4"]
}

Взаимозависимости — массив имён пакетов, которые будут объединены при публикации вашего пакета.

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.

Система

Вы можете предоставить информацию о системе, связанную с вашим пакетом, например, совместимость с операционной системой.

engines

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}

Движки указывают версии клиентов, которые должны использоваться с вашим пакетом. Это проверяется по отношению к process.versions, а также к текущей версии yarn.

Эта проверка следует обычным правилам semver с одним исключением. Она позволяет предызданиям соответствовать semvers, которые не явно указывают на предыздание. Например, 1.4.0-rc.0 соответствует >=1.3.0, но не будет соответствовать стандартной проверке semver.

os

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

Это указывает совместимость вашего пакета с операционной системой. Это проверяется по отношению к process.platform.

cpu

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

Используйте это, чтобы указать, что ваш пакет будет работать только на определённых архитектурах процессоров. Это проверяется по отношению к process.arch.

Публикация

private

{
  "private": true
}

Если вы не хотите публиковать свой пакет в менеджере пакетов, установите это значение в true.

publishConfig

{
  "publishConfig": {
    ...
  }
}

Эти значения конфигурации будут использоваться при публикации вашего пакета. Например, вы можете назначить метку вашему пакету.