Публикация пакета в npm

Представьте ситуацию, что в вашем проекте есть JavaScript-модуль, и нужно скопировать его в другой проект. Есть вариант перенести код вручную, а можно подключить отдельным компонентом, и сделать это всего одной строчкой при помощи npm — менеджера пакетов для Node.js. В этой статье вы узнаете, как оформить ваш модуль в виде пакета, разместить его в общедоступной базе и поддерживать в дальнейшем.

Подготовительный этап

Для создания npm-пакета у вас должен быть установлен Node.js. После установки Node.js с официального сайта, npm в вашей системе появится автоматически.

Убедимся, что npm установлен — проверим его версию, набрав в консоли:

npm -v

Удобно хранить репозиторий на каком-нибудь хостинге совместной разработки IT-проектов, например, на GitHub. Тогда вы сможете:

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

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

npm init

Вам будут заданы вопросы об основных параметрах пакета. Можете заполнить их сразу в консоли или временно пропустить, нажимая Enter, и потом сделать это в текстовом редакторе. В текущей директории появится файл package.json.

Package.json

Параметры пакета можно отредактировать напрямую в файле package.json:

'name’— имя, по которому пакет будет доступен в npm
‘description’— описание пакета
‘author’— никнейм и ссылка на разработчика, например, на гитхабе, либо ‘contributors’— когда в разработке принимало участие несколько человек
‘license’ — лицензия

Поля ‘version’, ‘repository’, ‘bugs’, ‘homepage’ будут сгенерированы автоматически при создании package.json.


{
  "name": "mypackage",
  "version": "1.0.0",
  "description": "Your package description",
  "scripts": {
    "test": "command for testing package"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/myname/mypackage.git"
  },
  "author": "me",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/myname/mypackage/issues"
  },
  "homepage": "https://github.com/myname/mypackage#readme"
}

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

В секцию scripts можно поместить ваши команды, которые должны выполняться Node.js. Например, запуск системы сборки или тестов. Это словарь, заполняемый в формате ключ_команды : выполняемый скрипт.

Чтобы запустить скрипт, достаточно вызвать в консоли:

npm run ключ_команды

При запуске npm run build будет выполнено: webpack --progress --display-error-details --display-entrypoints --display-reasons

"scripts": {
    "build": "webpack --progress --display-error-details --display-entrypoints --display-reasons"
  }

Добавление скриптов позволит вам вызывать серию команд по одному ключевому слову.

Здесь перечислены основные поля package.json. Как работать с остальными, можно почитать в официальной документации.

README

Осталось оформить файл пользовательской документации или README.md, поясняющий, как установить и настроить ваш модуль. Если у вас не было опыта написания README, то об основных правилах можно почитать по ссылке. А если ищете готовый шаблон, то вот один из вариантов. Теперь можно приступать к самому интересному — публикации пакета в npm.

Публикация в npm

Если вы не зарегистрированы на npmjs.com — сделайте это с помощью команды:

npm adduser

Если же у вас есть учётная запись — вы можете авторизоваться:

npm login

Вас попросят ввести логин и пароль.

После ввода следующей команды ваш пакет окажется в npm, поэтому важно ещё раз всё проверить и убедиться в работоспособности модуля. Проверили? Отлично, публикуем :)

Наберите в консоли:

npm publish

Если публикация прошла успешно, можно перейти по ссылке и увидеть информацию о пакете:

https://npmjs.com/package/<your_package_name>

Также он появится у вас в профиле на сайте.

Публикация от имени команды

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

Обратите внимание: пакеты, публикуемые от имени команды, по умолчанию private. Чтобы сделать ваш пакет общедоступным, выполните публикацию с ключом --access public:

npm publish --access public

Установка пакета

Наконец, когда пакет опубликован, его можно установить и подключить в любом проекте с помощью команды:

npm install mypackage

В JavaScript-файле, где вы хотите использовать модуль, пропишите:

import mypackage from 'mypackage';

Готово, теперь вы можете обращаться к модулю по имени. Например, для вызова метода init:

mypackage.init();

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

Что нужно сделать, чтобы обновить модуль?

Внести изменения в код.
Обновить версию: npm version [ major | minor | patch ]
В терминале ввести npm publish

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

Если изменения незначительные (исправления мелких ошибок) — npm version patch. Это увеличит версию package.json, например, с 1.0.0 до 1.0.1

Если в пакете появились новые методы, не влияющие на уже существующие, то npm version minor и изменение второго знака: 1.0.0 —> 1.1.0

В случае модификации кода без обратной совместимости с предыдущей версией, npm version major — то, что вам нужно. И увеличение версии: 1.0.0 —> 2.0.0

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

Важно: если вы решили изменить версию в package.json вручную, то пропустите этот пункт, иначе версия будет изменена дважды.

Удаление пакетов из npm

Начнем с того, что удаление пакетов считается плохой практикой — от них могут зависеть проекты других пользователей. Однако, если вы опубликовали пакет командой npm publish, и поняли, что что-то пошло не так, отменить это действие в течение 24 часов можно командой npm unpublish. Npm запретил самостоятельно удалять пакеты, которые старше суток.

Если удалить такой пакет всё же необходимо, напишите в поддержку, указав причину. Пакет будет помечен как @deprecated и исчезнет из вашего профиля. Npm предупреждает о невозможности публикации нового пакета, если его название и версия будут совпадать с удаленным. Но есть и хорошие новости — пакет можно опубликовать повторно, изменив номер версии :)

Итого

Публикация в npm позволяет подключать модули отдельными компонентами. А семантическое версионирование пакетов помогает пользователям понимать совместимость релизов друг с другом.