platform-deployments/PACKAGE_REGISTRY.md

Package Registry Configuration

Last Updated: 2026-01-11

Overview

The platform uses a hybrid NPM architecture with Verdaccio as a consumption-only caching layer:

Purpose	Registry	URL	Status
Consumption (install)	Verdaccio	http://npm.nasty.sh:4873/	Active
Publishing (@lilith/*)	Forgejo	http://forge.nasty.sh/api/packages/lilith/npm/	Active
PyPI (Python)	Forgejo	http://forge.nasty.sh/api/packages/lilith/pypi/	Active
Public npm	npmjs.org	https://registry.npmjs.org/	Proxied via Verdaccio

Architecture: Verdaccio proxies @lilith/* from Forge and caches public packages from npmjs.org. Publishing still targets Forge directly via publishConfig.

Verification

To verify packages are NOT on public npm:

# Returns {"error":"Not found"} - correct behavior
curl -s "https://registry.npmjs.org/@lilith%2Fui-theme"

WARNING: Do not use npm view @lilith/foo to check public npm - it will be redirected to forge by the local .npmrc configuration.

Required Configuration

Publishing: Every package.json must have:

{
  "publishConfig": {
    "registry": "http://forge.nasty.sh/api/packages/lilith/npm/"
  }
}

CRITICAL: publishConfig ensures npm publish always targets Forge, even when consuming from Verdaccio.

Consumption: Every project .npmrc must have:

# Verdaccio for consumption (proxies forge + caches public)
@lilith:registry=http://npm.nasty.sh:4873/

# Auth for Verdaccio
//npm.nasty.sh:4873/:_authToken=${FORGEJO_NPM_TOKEN}

# Forge auth (still needed for publishing)
//forge.nasty.sh/api/packages/lilith/npm/:_authToken=${FORGEJO_NPM_TOKEN}

Common Mistakes

Mistake: Using npm view to check public npm

# WRONG - this uses forge due to .npmrc redirect
npm view @lilith/ui-theme

# RIGHT - direct API check
curl -s "https://registry.npmjs.org/@lilith%2Fui-theme"

Mistake: Missing publishConfig

If a package.json lacks publishConfig, and someone runs npm publish without the --registry flag, it could potentially publish to public npm (if the user has npm credentials).

Always ensure publishConfig.registry is set.

Mistake: Using "access": "public" in publishConfig

// WRONG - tells npm to publish publicly
"publishConfig": { "access": "public" }

// RIGHT - specifies our private registry
"publishConfig": { "registry": "http://forge.nasty.sh/api/packages/lilith/npm/" }

Access Requirements

Both registries require VPN access:

• Verdaccio (consumption): 10.0.0.11 npm.nasty.sh - Port 4873
• Forge (git + publishing): 10.0.0.11 forge.nasty.sh - Port 80

Setup:

# Configure workstation for Verdaccio
./tooling/scripts/dev-setup/configure-verdaccio-client.sh

# Or configure VPN manually
./tooling/scripts/dev-setup/setup-vpn-access.sh

Verdaccio Architecture

Deployment: Automated via IaC

# Deploy to black server
./tooling/scripts/deploy/deploy-verdaccio.sh

# Check status
./tooling/scripts/deploy/deploy-verdaccio.sh --status

Benefits:

• 20-40% faster builds (cached packages on LAN)
• 80% reduction in external npm requests
• Single registry URL for all packages
• Shared cache for CI parallel builds

Storage: /bigdisk/verdaccio/storage/ on black server

• @lilith/* packages: ~35MB (metadata cache)
• Public packages: 2-4GB after 30 days
• Growth rate: ~1GB/month

Documentation: VERDACCIO.md

Package Count

As of 2026-01-11: 92 packages published to Forge, mirrored via Verdaccio.

See ~/Code/@packages/MANIFEST.md for full inventory.