From c3df152fcb17b58bc8e0a73449393c54c1db7f83 Mon Sep 17 00:00:00 2001
From: Nikos Douvlis <nikosdouvlis@gmail.com>
Date: Fri, 16 Jan 2026 12:37:16 +0200
Subject: [PATCH] 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
---
 package.json              |  3 ++
 scripts/local-registry.sh | 73 +++++++++++++++++++++++++++++++++++++++
 verdaccio.install.yaml    |  2 +-
 3 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100755 scripts/local-registry.sh

diff --git a/package.json b/package.json
index 4c40fcae0f2..b6a60188ce6 100644
--- a/package.json
+++ b/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",
diff --git a/scripts/local-registry.sh b/scripts/local-registry.sh
new file mode 100755
index 00000000000..e07623012fd
--- /dev/null
+++ b/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
diff --git a/verdaccio.install.yaml b/verdaccio.install.yaml
index e82793e0afe..2b77595e6e5 100644
--- a/verdaccio.install.yaml
+++ b/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