RonanCodes/skills/vercel-verify

Vercel Verify

The local pre-push gate is necessary but not sufficient on Vercel. Turbo (and other build caches) can return a cache hit so pnpm build passes locally, while the actual Vercel build fails on something the cache masked — the classic being a server-only import leaking into the client bundle, or an env var present locally but missing in Vercel. A green push is not a green deploy. This skill closes that gap: after you push, confirm the deployment for that commit reached READY, and if it didn't, show you why.

This is the backstop. The real fix for a recurring class of failure is to make it un-pushable (see "Prevention" below). Use both.

When to use

• Automatically right after /ro:ship / /ro:cf-ship-style push when the repo deploys to Vercel.
• Any time the user asks "did it deploy", "is it live", "did the build pass", or pushed something build-affecting.

Do NOT use for Cloudflare/Fly deploys — those have their own verify paths.

Steps

1. Resolve the project + scope

cat .vercel/project.json 2>/dev/null   # → { "projectId": "...", "orgId": "..." }

• If present, use projectId and orgId (orgId is the teamId for API calls).
• Else read vercel.json / ask for the project name, or fall back to the Vercel CLI path (step 4).
• --project <name> overrides.

2. Get a token

Per the env convention, check the shared env first — do not ask the user to paste a token before looking:

grep -i 'VERCEL_TOKEN' ~/.claude/.env

If absent, offer two paths: (a) add VERCEL_TOKEN=... to ~/.claude/.env, or (b) use the Vercel CLI which carries its own auth (step 4).

3. Poll the deployment for the pushed commit (API path)

Target the deployment whose commit matches HEAD (or --sha), so you never read a stale older deploy:

SHA=$(git rev-parse HEAD)
TEAM="&teamId=$ORG_ID"   # omit if personal scope
curl -s "https://api.vercel.com/v6/deployments?projectId=$PROJECT_ID&limit=5$TEAM" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
| jq -r '.deployments[] | "\(.uid) \(.readyState) \(.meta.githubCommitSha // "")"'

Pick the row whose commit sha matches (prefix-match is fine). Poll its readyState every --wait seconds (default 15) until it's terminal:

• QUEUED / INITIALIZING / BUILDING → keep waiting.
• READY → success. Print the deployment URL and stop.
• ERROR / CANCELED → go to step 5.

Give up after --timeout (default 300s) and report "still building after Ns" rather than hanging.

4. CLI fallback (no token / no .vercel)

vercel ls --yes | head            # latest deployments + states
vercel inspect <deployment-url> --logs   # build logs for a specific one

vercel inspect ... --logs is also the quickest way to read a failed build's output by hand.

5. On ERROR — pull the build log and surface the cause

curl -s "https://api.vercel.com/v2/deployments/$UID/events?builds=1&limit=1000$TEAM" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
| jq -r '.[] | select(.type=="stderr" or .type=="stdout") | .payload.text' \
| tail -60

Surface the failing lines (the error, not the whole log). Common signatures to call out:

• server-only / client-only boundary violation → a server module reached the client bundle.
• Module not found → dependency not installed or path wrong in the real (uncached) build.
• Environment Variable "X" references Secret / is not defined → set it in Vercel (vercel env add).

Then propose the fix and, if it's a code bug, offer to open it as an issue or fix it directly.

6. Report

VERCEL-VERIFY — <project>
  commit:   <sha7>  (matched deployment <uid7>)
  state:    READY ✓ | ERROR ✗ | TIMEOUT
  url:      https://<deployment>.vercel.app
  cause:    <on failure: the one-line root cause from the log>
  next:     <on failure: the fix / issue filed>

Prevention (so the backstop fires less)

The verify loop catches the failure after the fact. To stop the class of failure from reaching main:

• Make the local gate match the real build. If pre-push relies on a Turbo cache, run the build uncached in the gate (turbo run build --force) so a cache hit can't hide a break.
• Catch boundary violations at lint. Add an ESLint rule that forbids client components importing server-only modules (e.g. eslint-plugin-boundaries, or Next's own boundary checks). That turns the most common Vercel-only break into a pre-commit lint error. This is repo-specific config; apply it in the app repo, not here.

Related

• [[ship]] / [[cf-ship]] — the push side; this is the post-push verify.
• [[diagnose]] — when the deploy is READY but the app misbehaves at runtime.