package.json

Основы

В package.json есть два наиболее важных поля: имя и версия, без которых пакет может не установится. Они используются совместно для создания уникального идентификатора.

имя

{
  "name": "my-awesome-package"
}

Это имя вашего пакета. Оно используется как ссылка в качестве аргумента командной строки и в качестве имени каталога внутри папки node_modules.

yarn add [name]
node_modules/[name]


https://registry.npmjs.org/[name]/-/[name]-[version].tgz

Правила

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

Советы

  • Не используйте имена модулей ядра Node.js
  • Не используйте js илиnode в имени.
  • Делайте имена краткими и содержательными. Старайтесь чтобы люди поняли, что это такое по имени, но оно также будет использоваться в вызовах require ().
  • Убедитесь что нет чего-то в реестре с тем же именем.

версия

{
  "version": "1.0.0"
}

Текущая версия пакета.

Информация

описание

{
  "description": "Моё короткое описание этого замечательного проекта"
}

Описание - это просто строка, которая помогает людям понять назначение пакета. Также его можно использовать при поиске пакетов в менеджере пакетов.

ключевые слова

{
  "keywords": ["короткие", "актуальные", "ключевые слова", "для", "поиска"]
}

Ключевые слова-это массив строк, которые помогают при поиске пакетов в диспетчере пакетов.

лицензия

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}

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

Рекомендуется использовать лицензию с открытым исходным кодом (Одобрено OSI (Институт Открытого Общества)), если только у вас нет причин этого не делать. Если пакет был создан как часть работы, то, вероятно, лучше проконсультироваться со своей компанией, прежде чем принимать решение о лицензировании.

Пожалуйста, используйте одно из следующего:

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

Ссылки

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

домашняя страница

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

Домашняя страница - это сетевой адрес целевой страницы, также может быть ссылкой на документацию к пакету.

ошибки

{
  "bugs": "https://github.com/user/repo/issues"
}

Ссылка на систему отслеживания проблем проекта. Также может быть чем-то вроде адреса электронной почты. Позволяет пользователям узнать, куда отправлять сообщения о проблемах с Вашим пакетом.

репозиторий

{
  "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": "Ваше Имя",
    "email": "you@example.com",
    "url": "http://your-website.com"
  },
  "author": "Ваше Имя <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"]
}

Если существуют связанные с проектом справочные страницы, добавьте их сюда.

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 &lt;script&gt;. Например, с помощью скрипта build-project можно вызывать yarn run build-project, также сработает и node build-project.js.

Некоторые имена сценариев являются особыми. Если определен сценарий с именем preinstall, то он выполнится перед установкой пакета в yarn. По причинам совместимости, скрипты называющиеся install, postinstall и prepublish вызовутся после завершения установки пакета.

Значение сценария 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"
  }
}

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

optionalDependencies

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

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

bundledDependencies

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

Связанные зависимости - это массив имён пакетов, которые будут объединены при публикации пакета.

flat

{
  "flat": true
}

Если ваш пакет допускает только одну версию данной зависимости, и вы хотите применить то же поведение, что и yarn install --flat в командной строке, задайте значение true.

Обратите внимание, что если ваш пакет .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] автоматически добавит блок Resolution в файл package.json.

Система

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

engines

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

Секция engines указывает, какие версии системных библиотек должны использоваться с вашим пакетом. Проверяется значение 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": {
    ...
  }
}

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