Перевод статьи «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 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!
Следите за сообщениями о проблемах, которые будут отсылать люди, использующие ваш пакет. Также не забывайте уделять внимание вопросам безопасности.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]