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

Несколько упакованных посылок у входной двери

Обзор и цели

npm (Node Package Manager) — это репозиторий и командный интерфейс для публикации и распространения пакетов Node.js. Цель статьи — подробно провести вас через процесс публикации пакета: от подготовки проекта до удаления пакета, с акцентом на тестирование, безопасность и возвращаемость действий.

Важно: при публикации информация из package.json станет видимой публично (имя, описание, лицензия, репозиторий и т.д.).

Основные термины

npm — менеджер пакетов для Node.js.
package.json — метаданные пакета и список зависимостей.
npm publish — команда для публикации пакета в реестр npm.
npm link — команда для локального тестирования пакета.

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

Чтобы пользоваться npm, установите Node.js, который включает npm. Наиболее распространённые варианты:

На Ubuntu: используйте официальный репозиторий NodeSource или apt после добавления PPA.
На Windows: скачайте установщик с сайта nodejs.org.
На macOS: используйте Homebrew (brew install node) или официальный установщик.

После установки проверьте версии:

node --version
npm --version

Если версии отображаются, вы готовы к следующему шагу.

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

Перейдите на страницу регистрации npm (https://www.npmjs.com/signup).
Заполните поля, согласитесь с условиями и подтвердите создание аккаунта.
Подтвердите адрес электронной почты по ссылке, полученной от npm.

Важно: без подтверждения почты попытка публикации вызовет ошибку.

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

Отслеживание изменений в проекте рекомендуется с самого начала.

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

git init

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

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

Рекомендуется разместить репозиторий на GitHub, GitLab или другом хостинге для удобства совместной работы и автоматизации CI/CD.

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

В корне проекта запустите:

npm init

Вас попросят заполнить поля в package.json. Основные параметры:

name — уникальное имя пакета в реестре npm. Если имя занято, публикация не пройдет.
version — текущая версия пакета, по семантике версионирования (SemVer). Повышайте её при каждом релизе.
description — краткое описание пакета, видимое в npm.
main — файл входа (точка входа) вашего пакета.
scripts — команды для тестирования и сборки (например, “test”: “jest”).
repository — URL удалённого репозитория.
keywords — теги для поиска.
author — автор пакета.
license — лицензия проекта (например, MIT, ISC и т.д.).

Совет: используйте npm init –yes для автоматического заполнения значений по умолчанию, затем отредактируйте package.json вручную.

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

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

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

npm link

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

mkdir test
cd test
npm link name-of-your-package

Создайте простой файл, импортируйте ваш пакет и проверьте базовую функциональность.
По завершении тестирования удалите тестовую папку.

Это гарантирует, что пакет корректно экспортирует API и что основные сценарии использования работают.

Шаг 6: Вход в npm на локальной машине

Выполните:

npm login

Команда запросит имя пользователя, пароль и код двухфакторной аутентификации (если включён). После успешного входа npm CLI будет иметь права публикации от вашего аккаунта.

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

Когда всё готово, выполните:

npm publish

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

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

npm install name-of-your-package

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

Вы можете удалить пакет через интерфейс npmjs.com: перейдите в настройки пакета и выберите «Delete package». Удаление — необратимо (в большинстве случаев), поэтому убедитесь, что вы понимаете последствия.

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

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

Перед публикацией проверьте, что:

package.json содержит корректное имя, версию и точку входа.
Лицензия указана и соответствует требованиям вашей организации.
Все зависимости перечислены и версии зафиксированы там, где нужно.
Тесты проходят локально и в CI (если настроено).
Чувствительная информация не попала в пакет (ключи, пароли, приватные сертификаты).

Чек‑лист перед публикацией

node и npm установлены и обновлены.
Email аккаунта npm подтверждён.
Git коммит с актуальным состоянием.
package.json проверен и валиден.
README.md с примерами использования и лицензией.
Unit-тесты и базовая интеграция проходят.
Локальное тестирование через npm link выполнено.

Мини‑методология релизного процесса

Разработка в отдельной ветке feature.
Обязательные тесты и код‑ревью.
Мёрдж в main/master и тег релиза (git tag vX.Y.Z).
Обновление version в package.json согласно SemVer.
CI выполняет сборку и тесты.
Публикация npm publish из защищённого CI либо вручную.

Когда публикация на npm не подходит (примеры)

Когда пакет содержит приватные или лицензионно чувствительные данные.
Когда библиотека предназначена только для внутреннего использования и не должна быть публичной (лучше использовать приватный реестр или scoped пакеты с приватным доступом).
Когда вы не готовы поддерживать API и исправлять критические баги — публикация обязывает к поддержке.

Альтернативные подходы

Использовать scoped пакеты (например, @org/name) с приватным доступом для внутренних библиотек.
Развернуть приватный реестр (Verdaccio) для организации.
Публиковать артефакты в корпоративный реестр (GitLab Package Registry, JFrog Artifactory).

Безопасность и рекомендации

Включите двухфакторную аутентификацию (2FA) для аккаунта npm.
Никогда не храните секреты в package.json, исходниках или в git.
Проверяйте зависимости с помощью npm audit и инструментов SCA (Software Composition Analysis).

Примечание: npm audit показывает известные уязвимости в зависимостях; исправляйте их перед публикацией.

Риск‑матрица и смягчения

Неправильная лицензия — риск легальных последствий. Смягчение: проверка лицензии перед публикацией.
Утечка секретов — риск компрометации. Смягчение: .gitignore + секреты в переменных окружения, использование инструментов сканирования.
Поломка API после обновления — риск у пользователей. Смягчение: семантическое версионирование, документация и CHANGELOG.

Критические тесты и критерии приёмки

Unit-тест: ключевые методы возвращают ожидаемые значения.
Integration: пакет корректно импортируется и выполняет базовую задачу при установке.
Smoke test: пример из README выполняется без ошибок.

Если все тесты проходят — пакет готов к публикации.

Как откатить публикацию или удалить пакет

Для приватных пакетов/скоупов: используйте интерфейс npmjs.com для удаления.
Для публичных пакетов удаление может быть ограничено; в таких случаях выпускaйте новую версию, в которой пометите пакет как deprecated (npm deprecate) и подробно опишите альтернативы.

Примеры команд (шпаргалка)

# Инициализация git
git init
git add -A
git commit -m "initial-commit"

# Инициализация npm
npm init

# Локальное тестирование
npm link
mkdir test
cd test
npm link name-of-your-package

# Вход и публикация
npm login
npm publish

# Установка опубликованного пакета
npm install name-of-your-package

Глоссарий (одной строкой)

SemVer: система версионирования, где версия X.Y.Z означает major.minor.patch.
Scoped package: пакет, у которого имя содержит область (scope), например @org/name.
Registry: реестр пакетов (npmjs.com или приватный сервер).

Роль‑ориентированные действия

Разработчик: обеспечьте тесты, README и package.json.
Техлид/ревьювер: проверьте API-совместимость и лицензию.
DevOps/CI: настроить автоматическую публикацию либо защищённый pipeline для релизов.

Короткая инструкция для объявления релиза (SOP)

Убедитесь, что main ветка в актуальном состоянии.
Повысите версию в package.json согласно SemVer.
Запустите тесты и сборку в CI.
Выполните npm publish из защищённой среды.
Обновите CHANGELOG и пометьте релиз в системе трекинга.

Заключение

Публикация пакета на npm — это стандартный рабочий процесс, который состоит из подготовки проекта, тестирования, входа в аккаунт и выполнения npm publish. Правильная подготовка (тесты, лицензии, безопасность) снижает риски и упрощает поддержку пакета.

Важно: всегда задокументируйте изменения и поддерживайте backward compatibility, когда это возможно.