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

Пакет - это директория с кодом и с файлом package.json, который предоставляет информацию для Yarn о вашем пакете.

Большинство пакетов используют какую-либо систему контроля версий. Наиболее распространенной является git, но Yarn не запрещает использование другой системы. В этом руководстве, все наши примеры используют git.

Внимание: Если вы хотите следовать этому руководству, убедитесь что git и Yarn установлены в вашей системе.

Создание первого пакета

Чтобы создать ваш первый пакет, откройте системный терминал/консоль и запустите следующие команды:

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

Эти команды создадут вам новый репозиторий и переместят вас внутрь вновь созданной папки, а затем откроется интерактивная форма для создания нового пакета Yarn со следующими вопросами:

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

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

Подсказка: Если вы хотите использовать значения по умолчанию для всех вопросов, вы можете запустить команду 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 - автор пакета. Поле соответствует формату "Ваше имя <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 &lt;their-email@example.com&gt; (http://their-website.com)",
    "Another Friend &lt;another-email@example.com&gt; (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 - ссылка, по которой пользователи могу пройти и отправить отчет о найденных ошибках.
  • 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 способен устанавливать сотни и даже тысячи пакетов очень эффективно.

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

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

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