npm пакет — как опубликовать свой проект?

Создание и публикация своего проекта в npm может обуславливаться разными причинами. Например, опубликовать свою собственную библиотеку, которая обязательно «спасет мир» 🙂 , или просто загрузить участок кода, чтобы вызывать его импортом (Reset CSS или min JS), скачать в другой проект (gulp-picture-html) или создать проект объединив другие… Давайте узнаем, как загрузить свой проект в npm.

Создание проекта

Для создания 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": "stolphe",
"license": "MIT",
"bugs": {
"url": "https://github.com/myname/mypackage/issues"
},
"homepage": "https://github.com/myname/mypackage#readme"
}

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

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

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

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

Например:

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

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

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

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

README

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

Публикация

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

npm login

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

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

npm publish

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

https://npmjs.com/package/

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

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

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

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 предупреждает о невозможности публикации нового пакета, если его название и версия будут совпадать с удаленным. Но есть и хорошие новости — пакет можно опубликовать повторно, изменив номер версии 🙂

Итого

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