Как опубликовать пакет на npm

Посылки на пороге дома, символизирующие публикацию пакетов

Введение

npm (Node Package Manager) — это онлайн-репозиторий и CLI-инструмент для публикации и установки пакетов JavaScript/Node.js. Публикация состоит из простых шагов: подготовить проект, создать аккаунт, протестировать пакет локально и выполнить публикацию. Эта статья объясняет каждый шаг подробно, включает полезные чеклисты, альтернативы и советы по отладке.

Важно: публикуемые поля package.json, такие как name, version и license, станут публичными. Проверьте конфиденциальные данные и не включайте секреты.

Основные шаги

Установить Node.js и npm
Создать аккаунт на npm и подтвердить email
Инициализировать репозиторий Git
Инициализировать npm в проекте (package.json)
Протестировать пакет локально
Выполнить npm login и npm publish

Шаг 1: Установка Node.js и npm

npm поставляется вместе с Node.js. Установите Node.js с официального сайта или через менеджер пакетов вашей ОС.

На Ubuntu: используйте официальные инструкции Node.js или nvm для управления версиями.
На Windows: скачайте установщик с nodejs.org.

Совет: используйте nvm (Node Version Manager), если вам нужно переключаться между версиями Node.js.

Шаг 2: Создание аккаунта npm

Зарегистрируйтесь на https://www.npmjs.com и подтвердите адрес электронной почты — без подтверждения публикация вызовет ошибку.

Процесс регистрации кратко:

Перейдите на страницу регистрации npm.
Заполните имя пользователя, email и пароль.
Примите лицензию и политику конфиденциальности.
Подтвердите email по ссылке из письма.

Примечание: при включённой двухфакторной аутентификации вам потребуется настройка TOTP в профиле и соответствующий код при входе через CLI.

Шаг 3: Инициализация Git-репозитория

Инициализируйте репозиторий, чтобы отслеживать изменения и хранить удалённую копию на GitHub/GitLab.

В корне проекта выполните:

git init

Создайте файл .gitignore и добавьте в него файлы и папки, которые не должны попадать в репозиторий (node_modules, .env и т. п.). Затем добавьте и закоммитьте файлы:

git add -A
git commit -m "initial-commit"

Рекомендуется добавить удалённый репозиторий и пушить изменения для резервного копирования и совместной работы.

Шаг 4: Инициализация npm в проекте

Инициализация создаёт файл package.json с метаданными пакета. Выполните в корне проекта:

npm init

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

npm init -y

Основные поля package.json и их смысл:

name — уникальное имя пакета в npm (или scoped-имя @scope/name). Не используйте конфиденциальные данные.
version — семантическая версия (semver). Увеличивайте её при изменениях: патч, минор, мажор.
description — короткое описание пакета.
main — входной файл (например, index.js).
scripts — команды, например, test, build.
repository — URL вашего Git-репозитория.
keywords — ключевые слова для поиска.
author — имя разработчика.
license — лицензия пакета.

Краткая методология выбора имени и версии:

Если пакет публичный и имя занято — выберите другое имя или используйте scoped-пакет @your-org/name.
Версионируйте по semver: patch для исправлений, minor для обратнозаменяемых улучшений, major для несовместимых изменений.

Шаг 5: Тестирование пакета локально

Перед публикацией убедитесь, что пакет работает как зависимость.

В проекте выполните:

npm link

Создайте отдельную папку для теста и перейдите в неё:

mkdir test
cd test

Подключите локальный пакет к тестовой папке:

npm link name-of-your-package

Создайте файл-заглушку и импортируйте пакет, проверьте его поведение.

После проверки удалите тестовую папку.

Альтернатива: вместо npm link используйте локальную установку через файл-ссылку:

npm install ../path-to-your-package

Шаг 6: Вход в npm через CLI

Авторизуйтесь в npm в терминале:

npm login

Команда запросит имя пользователя, пароль и код двухфакторной аутентификации, если он включён.

Шаг 7: Публикация пакета

Опубликуйте пакет командой:

npm publish

Если используется scoped-пакет и вы хотите опубликовать его публично, убедитесь, что в package.json указано “private”: false или отсутствует поле private, и при необходимости добавьте флаг –access public:

npm publish --access public

После успешной публикации пакет будет доступен на https://www.npmjs.com/package/name-of-your-package.

Чтобы установить опубликованный пакет в другом проекте используйте:

npm install name-of-your-package

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

Удаление возможно через настройки пакета на npmjs.com. Обратите внимание, что npm имеет ограничения на unpublish для публичных пакетов, особенно старых версий; при необходимости обратитесь к документации npm перед удалением.

Альтернативы и расширения рабочего процесса

Yarn и pnpm: альтернативные менеджеры пакетов с похожими возможностями публикации. Используйте их, если предпочитаете их workflow.
npx: позволяет запускать пакеты без глобальной установки — полезно для одноразовых CLI-инструментов.
Scoped-пакеты: @org/name — удобны для организации и управления правами доступа.
Частные пакеты: если пакет содержит приватные артефакты, используйте npm Organizations или другие реестры (например, Verdaccio) для приватных публикаций.

Роли и чек-листы

Разработчик

Убедиться, что в package.json нет секретов.
Тесты проходят локально и в CI.
Semver корректно обновлена.

Мейнтейнер (maintainer)

Проверить соответствие лицензии.
Проверить описание и ключевые слова.
Проверить CI и скрипты публикации.

Протестировать пакет через npm link и локальную установку.
Проверить поведение при разных версиях Node.js.

Критерии приёмки

Пакет устанавливается командой npm install без ошибок.
Экспортируемые API работают в тестовом проекте.
package.json корректно отражает точку входа и скрипты.
Документация (README) объясняет установку и примеры использования.

Распространённые ошибки и как их исправить

Ошибка: “npm ERR! You must verify your email” — решение: подтвердите email на npmjs.com.
Ошибка: “package name already in use” — решение: выберите уникальное имя или используйте scoped-имя @scope/name.
Ошибка: неверная версия — решение: обновите поле version в package.json согласно semver и повторите npm publish.
Ошибка при двухфакторной аутентификации — решение: используйте текущий TOTP-код или временные пароли, если настроены.

Если возникает ошибка публикации, прочитайте текст ошибки и выполните полную проверку полей package.json и состояния npm-аутентификации.

Безопасность и приватность

Не храните секреты (ключи, пароли) в package.json или исходниках.
Для приватных артефактов используйте приватные реестры или организации npm.
Включите двухфакторную аутентификацию для аккаунта, который имеет права публикации.

Короткий словарь

package.json — манифест Node-пакета.
semver — семантическое версионирование.
scoped-пакет — пакет с префиксом @scope/name.
npm link — команда для локальной симуляции установки пакета как зависимости.

Заключение

Публикация пакета на npm — повторяемый процесс: подготовка проекта, тестирование, аутентификация и публикация. Следуйте семантическому версионированию, проверяйте package.json и защищайте учётную запись с помощью двухфакторной аутентификации.

Короткие рекомендации:

Всегда тестируйте пакет локально через npm link.
Используйте scoped-имена для организации пакетов.
Документируйте API и пример установки в README.

Важно: перед удалением пакета проверьте политику npm относительно удаления и влияние на пользователей.

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

Node.js и npm установлены
Аккаунт npm создан и email подтверждён
Git-репозиторий и .gitignore настроены
package.json заполнен корректно
Локальные тесты пройдены (npm link или локальная установка)
Выполнен npm login
Выполнен npm publish