Initial commit: add .gitignore and README

PRIVATE_NPM_REGISTRY_SETUP.md

@@ -0,0 +1,329 @@
+# 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
+