Настройка приватного npm Registry: Verdaccio, GitLab, Nexus

Настройка приватного npm Registry

Отметим: когда в компании несколько проектов используют общие JavaScript/TypeScript пакеты — UI-компоненты, утилиты, конфиги eslint, shared типы — возникает необходимость в приватном реестре. Публикация на npmjs.com нарушает безопасность и контроль версий. Git submodules усложняют версионирование и управление зависимостями. Решение — собственный приватный npm registry, который обеспечивает версионирование, контроль доступа и кэширование публичных пакетов.

Мы настраиваем приватные реестры под ключ: от выбора решения до интеграции с CI/CD и документации. За 1–3 дня вы получаете рабочий реестр, доступный всей команде. За 7 лет мы развернули более 50 инсталляций — от стартапов до enterprise. Экономия времени разработчиков на управлении зависимостями достигает 40%. Получите консультацию — оценим ваш проект.

В этой статье разберём, как выбрать решение, настроить его и подключить к пайплайнам. Приведём конфиги для типовых сценариев.

Как выбрать приватный registry?

Три основных варианта:

По нашему опыту, Verdaccio выбирают 60% проектов — из-за простоты и малого потребления ресурсов. GitLab Package Registry — 30% (органичное решение для GitLab-экосистемы). Nexus — 10%, в основном миксовые стеки.

Как Verdaccio решает проблему с кэшированием?

Verdaccio — Node.js приложение, которое работает как прокси с кэшем для npmjs.com. При запросе пакета он сначала проверяет локальное хранилище; если пакета нет — загружает с npmjs.org и сохраняет в кэш (параметр maxage). Это ускоряет сборки на 30–50% и снижает нагрузку на внешние сети.

# docker-compose.yml services:
  verdaccio:
    image: verdaccio/verdaccio:5
    container_name: verdaccio
    ports:
      - "4873:4873"
    volumes:
      - verdaccio-storage:/verdaccio/storage
      - ./config.yaml:/verdaccio/conf/config.yaml
    restart: unless-stopped
volumes:
  verdaccio-storage:

# config.yaml
storage: /verdaccio/storage
auth:
  htpasswd:
    file: /verdaccio/storage/htpasswd
    max_users: 100
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    timeout: 30s
    maxage: 10m
packages:
  '@company/*':
    access: $authenticated
    publish: $authenticated
    storage: '@company'
  '**':
    access: $all
    proxy: npmjs
server:
  keepAliveTimeout: 60
logs:
  type: stdout
  format: pretty
  level: http

После запуска регистрируем пользователя и настраиваем npm:

# Создание пользователя
npm adduser --registry http://verdaccio.company.ru:4873

# Настройка .npmrc для проекта (в корне репозитория)
@company:registry=https://verdaccio.company.ru
//verdaccio.company.ru/:_authToken=${VERDACCIO_TOKEN}

GitLab Package Registry: аутентификация через токены

Если команда работает в GitLab, встроенный Package Registry — наиболее органичный вариант: не требует отдельной инфраструктуры, права доступа наследуются. Для установки пакетов в другом проекте нужен Personal Access Token с правом read_api или CI_JOB_TOKEN с правом read_package_registry.

# Публикация пакета из GitLab CI
# .gitlab-ci.yml
publish-npm:
  stage: publish
  script:
    - echo "@company:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm publish
  only:
    - tags

Для установки пакетов из GitLab Package Registry в другом проекте:

# .npmrc в проекте-потребителе
@company:registry=https://gitlab.company.ru/api/v4/packages/npm/
//gitlab.company.ru/api/v4/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

GITLAB_NPM_TOKEN — Personal Access Token с правом read_api. В CI используем CI_JOB_TOKEN или Deploy Token с правом read_package_registry.

Сравнение производительности: Verdaccio vs GitLab Package Registry (10 параллельных npm install):

Verdaccio быстрее на 40% без кэша благодаря proxy-кэшу. Если кэш прогрет — разница составляет 0.8 с.

Как настроить CI для публикации пакетов?

Стандартный pipeline для npm пакета: тест → сборка → публикация при новом теге. Пример для GitLab CI:

# .gitlab-ci.yml
stages: [test, build, publish]

test:
  image: node:20-alpine
  script:
    - npm ci
    - npm test

build:
  image: node:20-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths: [dist/]

publish:
  image: node:20-alpine
  stage: publish
  script:
    - npm ci
    - npm run build
    - npm version ${CI_COMMIT_TAG} --no-git-tag-version
    - npm publish
  only:
    - tags
  environment:
    name: npm-registry

Версионирование через git tags: при создании тега v1.2.3 pipeline публикует пакет с версией 1.2.3. В среднем pipeline занимает 2–5 минут.

Scoped packages и workspace монорепо

В monorepo с Turborepo или Nx все внутренние пакеты используют единый scope (@company). В package.json каждого пакета прописываем "publishConfig": {"registry": "https://verdaccio.company.ru"} — npm при публикации использует этот registry вместо дефолтного. Это гарантирует, что пакет не уйдёт на npmjs.com случайно. Мы также настраиваем rules в CI: публикация только с тегом, запрет на публикацию из мастер-ветки.

Что входит в настройку приватного npm registry под ключ

• Выбор решения (Verdaccio / GitLab / Nexus) с учётом вашего стека
• Установка и конфигурация: SSL через nginx reverse proxy, аутентификация, fino настройка config.yaml
• Интеграция с CI/CD: шаблоны .gitlab-ci.yml, .npmrc для проектов
• Документация для разработчиков (как устанавливать и публиковать пакеты)
• Обучение команды (1–2 часа воркшоп)
• Поддержка после запуска (1 месяц бесплатно)

Сроки: от 1 до 3 дней. Стоимость рассчитывается индивидуально — пишите, оценим.

Почему стоит обратиться к нам?

7+ лет опыта в DevOps, 50+ проектов по настройке реестров артефактов. Работаем с Kubernetes, Terraform, Ansible — любой стек. Гарантия: если registry не работает под нагрузкой — доработаем бесплатно. Используем best practices: GitOps, RBAC, Istio service mesh для микросервисов. Свяжитесь с нами — получите консультацию и оценку проекта за один день.