Представьте ситуацию, что в вашем проекте есть 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"
}

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

Публикация в 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();

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

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

  1. Внести изменения в код
  2. Обновить версию: npm version [ major | minor | patch ]
  3. В терминале ввести 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 предупреждает о невозможности публикации нового пакета, если его название и версия будут совпадать с удаленным. Но есть и хорошие новости - пакет можно опубликовать повторно, изменив номер версии.