Как создать и использовать приватный npm-пакет?

Приватный npm-пакет — это обычный пакет, но опубликованный в реестр с ограниченным доступом. Это нужно, когда код содержит бизнес-логику, которую нельзя выкладывать в публичный npm, но хочется переиспользовать между проектами так же удобно, как обычные зависимости.

Ключевые понятия

• Scope — префикс вида @company/, который привязывает пакет к организации.
• Registry — сервер, где хранятся пакеты: npm Private, GitHub Packages, GitLab Registry, Verdaccio.
• Токен — секрет для аутентификации при публикации и установке.

Публикация пакета

Сначала задаём имя со scope и указываем реестр в package.json:

{
  "name": "@company/utils",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

Затем логинимся и публикуем:

npm login --registry=https://npm.pkg.github.com
npm publish --access restricted

Установка в другом проекте

В корне проекта создаём .npmrc с токеном (токен лучше хранить в переменной окружения):

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

После этого пакет ставится как обычно:

npm install @company/utils

В CI токен передаётся через секреты, чтобы не хранить его в репозитории.

Итог: приватные пакеты стоит применять для общей внутренней библиотеки — утилит, UI-компонентов, типов — когда нужно централизованно версионировать и распространять код внутри команды или компании.