feat(repo): add local Verdaccio workflow for testing packages

Why:
Testing package changes locally has been painful:
- npm/pnpm linking doesn't always work and doesn't mimic real published
  package behavior (symlinks behave differently than installed packages)
- YALC is an older solution with the same limitation - it doesn't map 1:1
  with how packages behave when published to npm
- The common workaround was pushing to a branch and waiting for snapshot
  releases, which takes 5+ minutes per iteration from push to install

Verdaccio solves this by running a local npm registry. Packages are built
and published exactly as they would be to npm, then installed normally in
test apps. This makes iteration cycles much shorter while testing real
package behavior.

What changed:
- Added `local:registry:up` to start Verdaccio with npm proxy support
- Added `local:registry:down` to stop the registry
- Added `local:registry:pub` to build, publish with snapshot versions, and
  auto-reset git changes after publishing

Usage:
  pnpm local:registry:up     # Start registry (Terminal 1)
  pnpm local:registry:pub    # Build & publish (Terminal 2)
  bun install --registry http://localhost:4873  # In test app

Author: nikosdouvlis

package.json

@@ -24,6 +24,9 @@
     "lint:inspect": "pnpx @eslint/config-inspector@latest",
     "lint:packages": "FORCE_COLOR=1 turbo lint",
     "lint:publint": "FORCE_COLOR=1 turbo lint:publint",
+    "local:registry:down": "./scripts/local-registry.sh down",
+    "local:registry:pub": "./scripts/local-registry.sh pub",
+    "local:registry:up": "./scripts/local-registry.sh up",
     "nuke": "node ./scripts/nuke.mjs",
     "prepare": "husky install",
     "release": "changeset publish && git push --follow-tags",

scripts/local-registry.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+
+# Local Verdaccio Registry Script
+# Usage: ./scripts/local-registry.sh [up|down|pub]
+
+set -e
+
+REGISTRY_URL="http://localhost:4873"
+
+case "$1" in
+  up)
+    echo ""
+    echo "📦 Local Verdaccio Registry"
+    echo "==========================="
+    echo "Registry running at: $REGISTRY_URL"
+    echo ""
+    echo "To install packages in your test app:"
+    echo "  1. Update package.json catalog: \"@clerk/backend\": \"local\""
+    echo "  2. Run: bun install --registry $REGISTRY_URL"
+    echo ""
+    echo "To stop: pnpm local:registry:down"
+    echo ""
+    verdaccio --config verdaccio.install.yaml --listen 4873
+    ;;
+
+  down)
+    pkill -f 'verdaccio.*4873' && echo "Verdaccio stopped" || echo "Verdaccio not running"
+    ;;
+
+  pub)
+    # Ensure git changes are restored on exit (success or failure)
+    cleanup() {
+      git checkout -- 'packages/*/package.json' '.changeset/' 2>/dev/null || true
+    }
+    trap cleanup EXIT
+
+    # Restore any dirty package.json files first (from previous failed runs)
+    # so turbo cache can be used
+    cleanup
+
+    # Build all packages FIRST (uses turbo cache)
+    # This must happen before versioning, otherwise the package.json
+    # changes invalidate the turbo cache (package.json is in globalDependencies)
+    pnpm build
+
+    # Clear existing @clerk packages from Verdaccio storage to force republish
+    rm -rf .verdaccio/storage/@clerk
+
+    # Version packages with snapshot (uses snapshot.mjs which pins workspace deps
+    # to exact versions, preventing semver issues with prereleases)
+    pnpm version-packages:snapshot local
+
+    # Publish to Verdaccio using environment variable
+    npm_config_registry=$REGISTRY_URL pnpm changeset publish --no-git-tag --tag local
+
+    echo ""
+    echo "✅ Published to local Verdaccio"
+    echo "   Install with: bun install --registry $REGISTRY_URL"
+    ;;
+
+  *)
+    echo "Usage: $0 [up|down|pub]"
+    echo ""
+    echo "  up   - Start Verdaccio registry"
+    echo "  down - Stop Verdaccio registry"
+    echo "  pub  - Build and publish all packages"
+    echo ""
+    echo "Examples:"
+    echo "  $0 up"
+    echo "  $0 pub"
+    exit 1
+    ;;
+esac

verdaccio.install.yaml

@@ -15,4 +15,4 @@ packages:
     publish: $all
     proxy: npmjs
 log: { type: stdout, format: pretty, level: http }
-max_body_size: 20mb
+max_body_size: 200mb