package.json

Необхідні речі

Два найбільш важливих поля в вашому package.json - це name і version, без цього ваш пакет не зможе бути встановленим. Поля name та version використовуються разом, щоб створити унікальний ідентифікатор.

name

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

Це ім’я вашого пакету. Воно використовується в мережевих посиланнях, як аргумент до консольних команд, і як ім’я теки, де міститься node_modules.

yarn add [name]
node_modules/[name]


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

Правила

  • Має бути не більшим ніж 214 characters (включаючи @scope/ для пакетів з контекстом).
  • Не може починатися з точки (.) або підкреслення (_).
  • Не може мати велику літеру в назві.
  • Має використовувати знаки, які дозволені в ідентифікаторах мережевих ресурів.

Поради

  • Не використовуйте таке ж ім’я як і основні 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 вираз, якщо ви використовуєте декілька стандартних ліцензій.
  • ДИВІТЬСЯ В <ім'я файлу> рядок, який вказує файл <ім'я файлу>, в кореневому рівні вашого пакету, якщо ви використовуєте не стандартну ліцензію.
  • UNLICENSED рядок, якщо ви не хочете надавати іншим право на користування приватним або неопублікованним пакетов під будь-якими умовами.

Посилання

Різні посилання на документацію, місця, де можна звітувати про помилки, і де знаходиться ваш код.

homepage

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

Домашня сторінка - це мережева адреса до сторінки або документації вашого пакету.

bugs

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

Посилання на ваш менеджер звітів про помилки. Це також може бути електронною адресою. Це дозволить користувачам надсилати вам звіти про помилки в вашому пакеті.

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

Значення сценарію start по замовченню буде node server.js.

config

{
  "config": {
    "port": "8080"
  }
}

Варіанти налаштувань або параметрів ваших сценаріїв.

Залежності

Скоріш за все, ваш пакет буде залежати від інших пакетів. Ви можете вказати ці залежності в файлі package.json.

dependencies

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

Ці залежності необхідні як для розробки вашого пакету, так і для його виконання.

Ви можете вказати конкретну версію, найменшу (e.g., >=) або діапазон (наприклад: >= ... <).

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.

Прийміть до уваги, що якщо ваш 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.

This check follows normal semver rules with one exception. It allows prerelease versions to match semvers that do not explicitly specify a prerelease. For example, 1.4.0-rc.0 matches >=1.3.0, while it would not match a typical semver check.

os

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

Це вказує сумісніть з операційними системами вашого пакету. Воно перевіряється з process.platform.

cpu

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

Користуйтеся цим, щоб вказати, що ваш пакет може запуститися на певних архітектур процесорів. Воно перевіряється з process.arch.

Публікація

private

{
  "private": true
}

Якщо ви не хочете, щоб ваш пакет був опублікований менеджером пакетів, то встановіть це поле в true.

publishConfig

{
  "publishConfig": {
    ...
  }
}

Ці налаштування будуть використані під час публікації вашого пакету. Як приклад, ви можете задати мітку пакету.