Представьте, что вы шеф-повар. Чтобы все рестораны вашей сети готовили одинаково вкусные блюда, вы разработали серию «секретных соусов». Вы хотите, чтобы эти соусы доставлялись в каждый филиал, но вы не можете позволить обычным прохожим забирать их.

В мире разработки программного обеспечения эти секретные соусы — это внутренние «частные пакеты» компании.

По мере роста проектов вы, вероятно, сталкивались с этим разочарованием: дублирование одного и того же UI-компонента или вспомогательной функции в каждом проекте или борьба с Git Submodules до тех пор, пока вы не начнете сомневаться в своем жизненном выборе. На самом деле всё, что вам нужно, — это «Частная кладовая (Private NPM Registry)». Сегодня мы обсудим, как использовать pnpm для публикации пакетов в GitLab, чтобы члены команды могли устанавливать их так же просто, как пакеты с открытым исходным кодом, с помощью одной команды.

Зачем вам нужны частные пакеты и Scope?

Во вселенной Node.js у частных пакетов должна быть «фамилия» — это Scope (область действия).

Например, если ваша компания называется @my-company, название вашего пакета может выглядеть так: @my-company/ui-kit. Имея эту фамилию, когда pnpm увидит её, он не будет бесцельно искать на npmjs.org. Вместо этого он направится прямиком к указанным вами координатам компании.

Ключевое решение: Group Level против Project Level

В GitLab это всё равно что решать, где хранить приправы:

Настройка «паспорта»: Токены доступа и переменные окружения

Чтобы войти в подземное зернохранилище, вам сначала нужно получить «карту доступа».

1. Перейдите в Settings > Access Tokens в GitLab.
2. Подайте заявку на токен, отметив разрешения read_api (для загрузки) и write_package_registry (для публикации).
3. Важно: Как только вы получите токен, никогда не прописывайте его жестко прямо в коде или файле .npmrc! Это всё равно что оставить ключ от сейфа в двери.

Самый профессиональный подход — спрятать его в «переменных окружения». Добавьте эту строку в терминал Mac или Linux (например, ~/.zshrc):

export GITLAB_TOKEN="ваш_токен_GitLab"

Таким образом, система будет автоматически прикреплять учетные данные за вас, что делает процесс одновременно безопасным и удобным.

Настройки навигации: Суть .npmrc

Затем мы создадим карту навигации .npmrc в корне проекта, чтобы подсказать pnpm, куда идти:

# Для всего, что начинается с @my-company, иди в GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Настройка аутентификации по карте доступа (чтение переменной окружения, которую мы только что установили)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

Просто подставьте Group ID вашей компании, и путь будет проложен!

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

Многие люди спешат опубликовать пакет сразу после настройки соединения, но в итоге случайно загружают тестовые файлы или даже секретные конфигурации. Здесь на помощь приходит поле files в package.json.

Это концепция «белого списка» (allowlist):

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

Перед публикацией рекомендуется использовать команду pnpm pack, чтобы распаковать и проверить содержимое локально. Когда всё будет выглядеть хорошо, уверенно запускайте pnpm publish!

Заключение

Создать частную кладовую несложно. Ключевые моменты:

1. Запросите токен и защитите его переменными окружения.
2. Настройте правильную навигационную карту .npmrc.
3. Используйте поле files в package.json для точной отгрузки.

Освоив этот рабочий процесс, вы сможете сделать повторное использование кода вашей компании профессиональным, безопасным и элегантным. А теперь идите и создайте свою собственную центральную кухню!

Reference

• package.json | npm Docs
• Package registry | GitLab Docs