Створення пакету

package - це тека з певним вихідним кодом і файлом package.json, який надає інформацію Yarn щодо вашого пакету.

Більшість пакетів використовує певну систему контролю версій. Найбільш поширена - git, але Yarn буде працювати незалежно від вашого вибору системи. В цьому посібнику ми будемо використовувати git.

Примітка: якщо ви будете проходити цей посібнік, то спершу встановіть git і Yarn.

Створення вашого першого пакету

Для того, щоб створити ваш перший пакет, відкрийте вашу консоль або термінал і виконайте наступні команди:

git init my-new-project
cd my-new-project
yarn init

Це створить новий репозиторій git, змінить поточну теку і запустить інтерактивний помічник для створення нового проекту yarn з наступними питаннями:

name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

Ви можете вводити відповіді на кожне з питань, або можете просто натискати Ввід, щоб погодитися зі значення по замовченню, або ви можете залишити поле порожнім.

Порада: Якщо ви хочете використовувати параметри по замовчуванням, Ви можете також виконати yarn init --yes і пропустити всі запитання.

package.json

Тепер Ви повинні мати package.json який виглядає приблизно так:

{
  "name": "my-new-project",
  "version": "1.0.0",
  "description": "My New Project description.",
  "main": "index.js",
  "repository": {
    "url": "https://example.com/your-username/my-new-project",
    "type": "git"
  },
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

Поля, які Ви бачите в package.json, мають наступні значення:

  • name - це ідентифікатор вашого пакету, він має бути унікальним, якщо ви хочете опублікувати ваш пакет до глобального реєстру.
  • version - це семантично сумісна версія вашого пакету, ви можете опублікувувати пакети скількі завгодно, але у них мають бути різні версії.
  • description не обов’язкове, але рекомендоване поле, яке використовується користувачами Yarn, щоб знайти ваш пакет, або зрозуміти, що він робить.
  • main використовується, щоб визначити вхідну точку Вашого коду, яка використовується програмами як Node.js. Якщо не визначено - то по замовченню буде використаний файл index.js.
  • repository - це ще одне не обов’язкове, але рекомендоване поле, яке допомогає користувачам Вашого проекту знайди вихідних код і внести свій внесок назад.
  • author - це автор або супроводжувач пакету. Поле слідує формату Ваше ім'я <you@example.com> (http://your-website.com)"
  • license - це опубліковані юридичні документи Вашого пакету, також визначає, як можна користуватися кодом із Вашого проекту з юридичної точки зору.

Коли Ви запустите yarn init, все, що воно зробить - це створить цей файл, нічого більше не буде зроблено. Ви можете змінювати цей файл скільки завгодно разів.

Додаткові поля

Давайте переглянемо ще поля із package.json, які можуть стати в нагоді.

{
  "name": "my-new-project",
  "...": "...",
  "keywords": ["cool", "useful", "stuff"],
  "homepage": "https://my-new-project-website.com",
  "bugs": "https://github.com/you/my-new-project/issues",
  "contributors": [
    "Your Friend <their-email@example.com> (http://their-website.com)",
    "Another Friend <another-email@example.com> (https://another-website.org)"
  ],
  "files": ["index.js", "lib/*.js", "bin/*.js"],
  "bin": {
    "my-new-project-cli": "bin/my-new-project-cli.js"
  }
}
  • keywords - це список всіх ключових слів, по яким інші розробники можуть знайти ваш пакет.
  • homepage - це мережева адреса, на якій міститься інформація що введення до проекту, документація, а також посилання до додаткових ресурсів.
  • bugs - це мережева адреса, по якій користувачі вашого проекту зможуть задати запитання до вашого пакету.
  • contributors - це список вкладників Вашого проекту. Якщо є ще хтось, крім Вас, хто працює над проектом - то Ви можете додати їх тут.
  • files - це список файлів, які мають бути включені в Ваш проект коли він публікується або встановлюється. Якщо це поле відсутнє - Yarn включить всі файли.
  • bin це список консольних команд (виконуваних файлів), які Yarn створить під час установки пакету.

Для повного списку полів із package.json і більше деталей щодо них, звертайтесь до документації по package.json.

Ліцензії і відкритий вихідний код

Ми заохочуємо Вас робити пакети Yarn з відкритим вихідним кодом, але це не означає, що це буде зроблене під час опублікування пакету.

Для того, щоб вихідний код став відкритим, він має бути з ліцензією для відкритого вихідного коду. Існує великий перелік ліцензій для вибору, ось декілька із них:

Якщо Вам треба більший вибір, то перейдіть до більш повного списку.

Якщо ви вибрали ліцензію з відкритим вихідним кодом, то не забудьте додати LICENSE файл з текстом ліцензії до кореня вашого пакету, а також оновити поле license в package.json.

Примітка: якщо Ви не хочете, щоб Ваш проект був з відкритим вихідним кодом, то вкажіть це в ліцензії, або вкажіть, що ліцензія відсутня.

Розповсюдження вихідного коду

Скоріш за все, Вам захочеться, щоб Ваші користувачі мали доступ до вихідного коду і звітували Вам про помилки. Існує декілька популярних сайтів для публікування вашого коду:

Ці сайти дозволяють Вашим користувачам бачити Ваш код, звітувати про помилки і робити внески. Якщо Ви десь розмістили ваш код, Вам необхідно додати наступні поля в package.json:

{
  "homepage": "https://github.com/username/my-new-project",
  "bugs": "https://github.com/username/my-new-project/issues",
  "repository": {
    "url": "https://github.com/username/my-new-project",
    "type": "git"
  }
}

Документація

Найкраще буде, якщо ви напишете документацію до опублікування вашого пакету. Що найменше, Вам необхідно в корені вашого проекту написати README.md файл, який описує Ваш проект і документує публічний API.

Гарна документація - це коли ваші користувачі отримують всі знання про те, як користуватися вашим пакетом. Подумайте про питання, які може задати користувач, який нічого не знає про ваш проект. Документація має бути детальною, але в той же час короткою і легкою для засвоєння. Проекти з гарною документацією зазвичай більш вдалі.

Тримайте ваші пакети невеликими

Коли Ви створюєте Yarn пакети, ми заохочуємо Вас зробити їх невеликими і простими. Розділяйте Ваші велики пакети на маленькі, якщо це має сенс. Це дуже заохочується, оскільки Yarn може встановлювати сотні або і тисячі пакетів дуже ефективно.

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

Вам також треба приймати до уваги вміст Вашого пакету. Переконайтесь, що Ви випадково не розповсюджуєте Ваші тести або інші файли, які не потрібні для Ваших користувачів (сценарії збірок, картинки, тощо).

Також, будьте уважні щодо залежностей які використовує Ваш пакет, віддавайте перевагу невеликим за розміром залежностям, якщо у Вас є вибір. Переконайтесь, що Ви випадково не залежите від якогось величезного пакету.