Представьте ситуацию, что в вашем проекте есть 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 позволяет подключать модули отдельными компонентами. А семантическое версионирование пакетов помогает пользователям понимать совместимость релизов друг с другом.