docs/PRIVATE_NPM_REGISTRY_SETUP.md

Private npm Registry Setup Guide

Date: 2025-01-27 Purpose: Guide for setting up private npm registry for shared packages Status: Implementation Guide

---

Overview

This guide provides instructions for setting up a private npm registry to publish and distribute shared workspace packages.

---

Options

Option 1: Verdaccio (Recommended - Self-Hosted)

Pros:

• Free and open-source
• Lightweight and easy to deploy
• Good for small to medium teams
• Can run on Kubernetes

Cons:

• Self-hosted (requires infrastructure)
• Limited enterprise features

Option 2: GitHub Packages

Pros:

• Integrated with GitHub
• Free for public repos, paid for private
• No infrastructure to manage
• Good security features

Cons:

• Tied to GitHub
• Limited customization

Option 3: npm Enterprise

Pros:

• Enterprise features
• Support and SLA
• Advanced security

Cons:

• Commercial (paid)
• More complex setup

Recommendation: Start with Verdaccio for self-hosted, or GitHub Packages for cloud-based.

---

Setup: Verdaccio (Self-Hosted)

1. Deploy Verdaccio

Using Docker

docker run -d \
  --name verdaccio \
  -p 4873:4873 \
  -v verdaccio-storage:/verdaccio/storage \
  -v verdaccio-config:/verdaccio/conf \
  verdaccio/verdaccio

Using Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: verdaccio
spec:
  replicas: 1
  selector:
    matchLabels:
      app: verdaccio
  template:
    metadata:
      labels:
        app: verdaccio
    spec:
      containers:
      - name: verdaccio
        image: verdaccio/verdaccio:latest
        ports:
        - containerPort: 4873
        volumeMounts:
        - name: storage
          mountPath: /verdaccio/storage
        - name: config
          mountPath: /verdaccio/conf
      volumes:
      - name: storage
        persistentVolumeClaim:
          claimName: verdaccio-storage
      - name: config
        configMap:
          name: verdaccio-config

2. Configure Verdaccio

Create config.yaml:

storage: /verdaccio/storage
plugins: /verdaccio/plugins

web:
  title: Workspace Private Registry
  enable: true

auth:
  htpasswd:
    file: /verdaccio/storage/htpasswd
    max_users: 1000

packages:
  '@workspace/*':
    access: $authenticated
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs

  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

logs:
  - { type: stdout, format: pretty, level: http }

3. Configure Projects

.npmrc in workspace-shared/

@workspace:registry=http://verdaccio:4873/
//verdaccio:4873/:_authToken=${NPM_TOKEN}

.npmrc in projects

@workspace:registry=http://verdaccio:4873/
//verdaccio:4873/:_authToken=${NPM_TOKEN}

4. Authentication

# Login to registry
npm login --registry=http://verdaccio:4873/

# Or set token
export NPM_TOKEN="your-token"

---

Setup: GitHub Packages

1. Configure .npmrc

Create .npmrc in workspace-shared/:

@workspace:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Configure package.json

{
  "name": "@workspace/shared-types",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com",
    "@workspace:registry": "https://npm.pkg.github.com"
  }
}

3. Publish

# Set GitHub token
export GITHUB_TOKEN="your-github-token"

# Publish
npm publish

---

Publishing Workflow

1. Build Package

cd workspace-shared/packages/shared-types
pnpm build

2. Version Package

# Patch version
pnpm version patch

# Minor version
pnpm version minor

# Major version
pnpm version major

3. Publish

npm publish --registry=<registry-url>

4. Update Projects

cd project-directory
pnpm add @workspace/shared-types@latest

---

CI/CD Integration

GitHub Actions Example

name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://npm.pkg.github.com'
          scope: '@workspace'

      - name: Install pnpm
        uses: pnpm/action-setup@v2

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - name: Publish
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

---

Best Practices

Versioning

• Use semantic versioning
• Tag releases in git
• Document breaking changes

Access Control

• Use authentication for private packages
• Limit publish access
• Audit package access

Monitoring

• Monitor registry health
• Track package usage
• Monitor storage usage

---

Troubleshooting

Authentication Issues

• Verify token is set correctly
• Check registry URL
• Verify package scope matches

Publishing Issues

• Check package name matches scope
• Verify version is incremented
• Check for duplicate versions

---

Next Steps

1. Choose Registry: Verdaccio or GitHub Packages
2. Deploy Registry: Set up infrastructure
3. Configure Projects: Update .npmrc files
4. Publish First Package: Test publishing workflow
5. Update Projects: Start using shared packages

---

Last Updated: 2025-01-27