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

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

#### Using Kubernetes

```yaml
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`:

```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

```bash
# 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

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

### 3. Publish

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

# Publish
npm publish
```

---

## Publishing Workflow

### 1. Build Package

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

### 2. Version Package

```bash
# Patch version
pnpm version patch

# Minor version
pnpm version minor

# Major version
pnpm version major
```

### 3. Publish

```bash
npm publish --registry=<registry-url>
```

### 4. Update Projects

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

---

## CI/CD Integration

### GitHub Actions Example

```yaml
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