Как опубликовать собственный NPM-пакет

0
177
views
javascript logo

Хочешь проверить свои знания по JS?

Подпишись на наш канал с тестами по JS в Telegram!

×

Перевод статьи «Publish your own NPM package».

Название статьи может показаться пугающим. Для меня самого так и было. Но я покажу вам, что бояться здесь нечего. Опубликовать свой первый NPM-проект — просто интересный опыт.

Если вас в принципе заинтересовала эта статья, значит, вы по крайней мере слыхали об NPM и, вероятно, пользовались им ранее.

Просто короткое напоминание: NPM — это самый крупный реестр программного обеспечения, а также менеджер пакетов и установщик.

Хотите узнать, как установить NPM? Собственно, он поставляется в комплекте с Node. Если хотите узнать, как установить Node, загляните на Homebrew.

Для чего вам может понадобиться публиковать NPM-пакет?

Допустим, вы создали что-то, чем сами постоянно пользуетесь в своих проектах. Тогда, вероятно, вы уже поняли, какая это головная боль — обновлять этот код повсюду. А вот если вы опубликуете этот код в виде NPM-пакета, вы сможете вносить изменения во все свои проекты, где он используется, при помощи команды npm-update.

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

Как создать собственный NPM-пакет

Начнем с самого начала.

Сперва создадим нашу локальную папку.

mkdir astro-static-tweet && cd astro-static-tweet

Затем инициализируем NPM.

npm init

По ходу дела отвечайте на вопросы, которые будут появляться на экране.

Что касается имени пакета, можно использовать публичное имя типа my-plugin, но велика вероятность, что кто-то его уже занял. Проверить, доступно ли выбранное вами имя, можно при помощи команды npm search.

Второй вариант — опубликовать пакет, перед именем которого будет идти ваше имя. То есть у вас получится что-то вроде @username/my-plugin. Скорее всего, такое имя будет уникальным.

Пишем код

Теперь давайте создадим какой-то код, чтобы наш плагин что-то делал.

Сделаем суперпростой пример: код в нашем пакете будет всего лишь выполнять базовые математические действия.

Создаем файл index.js и добавляем в него следующий код:

function add(one, two) {
  return one + two;
}

module.exports = add;

Поскольку мы хотим использовать этот пакет в дальнейшем, мы можем затребовать функцию add:

const add = require('plugin-name');
console.log(add(2, 5));

Добавление нескольких функций

Конечно, если наш плагин будет просто складывать числа, он будет практически бесполезен. Давайте добавим еще несколько функций и посмотрим, как их можно будет экспортировать и использовать.

function add(one, two) {
  return one + two;
}

function subtract(one, two) {
  return one - two;
}

function multiply(one, two) {
  return one * two;
}

module.exports = {add, subtract, multiply};

После загрузки нашего пакета мы сможем импортировать эти функции:

const {add, subtract, multiply} = require('plugin-name');

Добавление README

Добавлять README-файл в свои проекты — хорошая привычка. Этот текст может быть сколь угодно подробным, но как минимум он должен включать:

  • инструкции по установке
  • пример использования
  • указания, как сообщать о проблемах.

Опциональные части:

  • над чем вы еще работаете
  • лицензия
  • руководство для потенциальных контрибьюторов.

Тестируем наш пакет

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

Не буду вдаваться в детали относительно кода тестов, это отдельная тема. Но самый базовый тест, который мы можем сделать, — ручной.

Мы можем протестировать наш пакет даже до того, как он будет опубликован в NPM-реестре. Для этого нужно подключить его локально.

Перейдите в папку пакета и выполните следующую команду:

npm link

В проекте, в котором хотите попробовать использовать свой пакет, выполните команду:

npm link имя-вашего-пакета

Если все работает хорошо, переходим к следующему шагу.

Публикация NPM-пакета

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

Регистрация на NPM

Когда у вас будет аккаунт, вы сможете запустить в своем терминале команду:

npm login

Следуйте шагам, которые будет предлагать скрипт.

Когда все будет готово, в том числе и код, который вы хотите опубликовать, введите команду:

npm publish

Вы использовали в имени пакета свое имя (@username/my-package)? Тогда вы получите сообщение, что такие пакеты бесплатно не публикуются.

Таким образом, нам нужно опубликовать этот пакет как публичный:

npm publish --access=public

А теперь вы можете зайти на npmjs и посмотреть, что получилось.

Обновление вашего пакета

Что касается обновлений, при необходимости вы всегда можете обновить ваш код. Следующий шаг после этого — обновить версию пакета.

Наилучший подход — использовать семантическую нумерацию версий. Это предполагает обозначение версии тремя цифрами через точку.

Version: 1.2.3

Цифры в номере версии говорят следующее:

  • 1: «мажорное» изменение, в нем могут быть несовместимые изменения в функциях
  • 2: «минорное» изменение, чаще всего имеет обратную совместимость
  • 3: изменение-патч, чаще всего исправление багов.

Почитать больше на эту тему можно на сайте semver.

Обновив версию, вы можете ее опубликовать, как делали ранее:

npm publish
# Или, если имя вашего пакета содержит префикс в виде вашего имени:
npm publish --access=public

Заключение

Вот и все. Теперь у вас есть ваш собственный пакет в реестре NPM!

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

ОСТАВЬТЕ ОТВЕТ

Please enter your comment!
Please enter your name here