1. Создание пакета

Пакет — это каталог с кодом и файлом 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):

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

Совет: Если вы хотите использовать значения по умолчанию для всего, вы также можете выполнить 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 — версия вашего пакета, совместимая со стандартом semver. Вы можете публиковать пакет сколько угодно раз, но они должны иметь новые версии.
description — необязательное, но рекомендуемое поле, которое используется другими пользователями Yarn для поиска и понимания вашего проекта.
main — используется для определения точки входа вашего кода, используемого программами, такими как Node.js. Если не указано, по умолчанию будет index.js.
repository — ещё одно необязательное, но рекомендуемое поле, которое помогает пользователям вашего пакета найти исходный код, чтобы внести свой вклад.
author — создатель или разработчик пакета. Следует формату "Your Name <you@example.com> (https://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> (https://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 — URL, который направляет пользователей на веб-сайт, где они могут найти информацию о пакете, документацию и ссылки на дополнительные ресурсы.
bugs — URL, который направляет пользователей вашего пакета в случае обнаружения проблемы.
contributors — список участников проекта. Если в вашем проекте участвуют другие люди, вы можете указать их здесь.
files — список файлов, которые должны быть включены в ваш пакет при публикации и установке. Если не указано, Yarn включит все файлы.
bin — отображение команд командной строки (бинарных файлов) для Yarn, которые будут созданы для пакета при его установке.

Полный список всех package.json полей и более подробную информацию о каждом из вышеперечисленных полей см. в package.json документации.

Лицензирование и открытый исходный код

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

Чтобы код стал открытым исходным кодом, ему нужна лицензия открытого исходного кода. Существует множество лицензий открытого исходного кода, вот несколько распространённых:

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

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

Примечание: Если вы не хотите, чтобы ваш проект был лицензирован как проект с открытым исходным кодом, вы должны чётко указать лицензию или то, что он не лицензирован.

Обмен кодом

Вероятно, вы захотите предоставить пользователям вашего пакета доступ к исходному коду и способ сообщать о проблемах. Есть несколько популярных веб-сайтов для размещения кода:

Эти сайты позволят вашим пользователям просматривать код, сообщать о проблемах и вносить свой вклад. После размещения кода где-либо, добавьте следующие поля в 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 способен очень эффективно устанавливать сотни или даже тысячи пакетов.

Многие небольшие пакеты — отличная модель управления пакетами. Часто это приводит к меньшим размерам загрузок, потому что вы не объединяете массивные зависимости, а используете только небольшой фрагмент.

Также следует учитывать содержимое вашего пакета. Убедитесь, что вы не случайно распространяете свои тесты или другие файлы, которые не нужны для использования вашего пакета (скрипты сборки, изображения и т. д.).

Будьте также внимательны к тем пакетам, от которых вы зависите, отдавайте предпочтение более компактным зависимостям, если у вас нет веских причин этого не делать. Убедитесь, что вы не зависите от чего-то огромного.