Ежедневно мы используем тысячи готовых решений. Большая часть из них — маленькие и универсальные NPM пакеты под конкретные задачи.
Во время разработки, каждый из нас генерирует сотни таких решений. Что делать если они переносятся из проекта в проект? Правильно!
Отделить их от проекта и опубликовать в виде NPM пакета 🙂
Вступление
В качестве примера мы с вами создадим классический react-accordion 😉
Идея есть, но с чего начать создание пакета? Как эффективно упаковать в него компонент? И как правильно оформить документацию перед публикацией пакета в NPM?
Ответы на эти вопросы мы постараемся найти в этой и следующих статьях 😎
Вся работа с проектом будет проходить через GitHub. Давайте создадим репозиторий, а затем склонируем его на локальную машину. Вся дальнейшая работа будет происходить в нём.
Точка входа
Основной точкой входа для управления пакетом является package.json. Его можно создать с помощью встроенного в NPM конфигуратора.
Давайте вызовем его:
Сразу запускается конфигуратор:
Затем поэтапно заполняем поля в конфигураторе. Это именно тот случай, когда все нужно заполнить с пристрастием 🤓
Заполнение
Name
С этим именем ваш пакет будет доступен в NPM. Важно чтобы имя в NPM и имя репозитория Github совпадало, в будущем это избавит нас от проблем и лишней работы.
Если такое имя уже существует в NPM, тогда пакет добавится в ваш личный скоуп. В моем случае он был бы доступен для скачивания из NPM по имени @toastyboost/react-collapser
Version
При публикации пакета каждая версия должна быть уникальной. В NPM традиционно используется семантическое версионирование. Основные принципы этого подхода заключаются в разделении версии на 3 части: мажорная, минорная и патч (2.3.1).
Мажорная версия (2) увеличивается когда в обновлении API вашего компонента присутствуют изменения способные поломать предыдущие версии API.
Минорная версия (3) увеличивается когда обновление добавляет новый функционал не ломая текущую мажорную версию.
Версия патча (1) увеличивается в случае устранения багов или внесения второстепенных изменений в компонент.
Согласно семантическому версионированию, в качестве номера мажорной версии мы должны указать — 0. Это означает что API компонента может измениться в любой момент без учета обратной совместимости.
Description
Этот текст будет отображаться в поисковой выдаче NPM и коротких описаниях, которые подтягиваются при парсинге ссылки в социальных сетях (Open Graph).
Вместо длинного описания советую вставить короткий список ключевых особенностей вашего пакета, пользователям будет проще понять чем ваш пакет отличается от остальных.
Подберите для вашего пакета релевантное emoji 🏄♂️и поместите его в описание, это немного выделит описание вашего пакета на фоне остальных.
Author
Почту для связи или ссылка на профайл, где с нами можно связаться. Именно туда вы напишите с просьбой освободить хорошие имя для вашего пакета, ведь автор заливал последнюю версию 5 лет назад 😭
Tags
Ключевые слова по которым ваш пакет можно будет найти package registry (поиск в NPM). Изучите теги похожих компонентов и используйте их у себя, это поможет нам оказаться на одной странице с ними.
Результат
В результате мы должны получить package.json примерно со следующим содержанием:
На основе этих значений NPM автоматически заполнит профайл вашего будущего пакета в своем package registry сразу после публикации.
От качества заполнения package.json зависит насколько высоко в выдаче поиска окажется ваш пакет. Так же пользователи будут иметь удобный доступ к полезным ссылкам для вашего проекта.
Регистрация
Мы выполнили все базовые условия для публикации пакета. Теперь нам нужно зарегистрироваться в NPM. Продвинутые разработчики могут сделать это через консоль:
Затем нужно авторизоваться в NPM через терминал:
Введите свои логин и пароль. После успешного входа у нас появится возможность публиковать свои пакеты в NPM 😎
Процесс публикации
Теперь у нас нет никаких препятствий для публикации! Давайте введём заветную команду и посмотрим на результат:
Ву-а-ля! Через несколько секунд ваш пакет становится доступен по адресу https://npmjs.com/package/<package_name>
Achievement unlocked
Теперь он доступен для скачивания напрямую из NPM, поздравляю 🎉
Давайте сразу это проверим:
Дальше вся работа с публикацией новых версий компонента будет сводиться к использованию одной команды, с разными свойствами:
Поехали:
Заключение
В NPM можно публиковать всё. Не важно насколько полезен или хорош ваш пакет. Не стесняйтесь пользоваться этим инструментом, оптимизируйте свою работу!
Надеюсь мои рекомендации помогли вам разобраться как опубликовать NPM пакет, далее мы рассмотрим:
- Как подготовить пакет к open-source разработке
- Как эффективно упаковать ваш модуль
- Как оформить storybook и документацию
- Как подготовить тестирование
Спасибо что прочитали до конца 🙂
Ссылки
Полное описание ключей package.json
https://docs.npmjs.com/files/package.json
Официальная инструкция:
https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry