Vercel Deploys skill for Claude Code

A healthy Vercel setup builds the same artifact locally and in the cloud, scopes env vars to the right environment and redeploys after changing them, runs functions on the Node.js runtime in the region next to the database, protects previews, and treats production as a promotion of a tested deployment with a one-click rollback.

Workflow

- [ ] 1. vercel link; read project settings (framework, root dir, build/install/output commands, Node version)
- [ ] 2. Reproduce the build locally: vercel pull && vercel build
- [ ] 3. Audit env vars per environment; pull them for local dev
- [ ] 4. Check function config: runtime, region, maxDuration, memory
- [ ] 5. Routing in framework config or vercel.json (rewrites, redirects, headers, crons)
- [ ] 6. Preview protection and build skipping for monorepos
- [ ] 7. Deploy preview -> verify -> promote; know the rollback

1-2. Reproduce builds locally

npm i -g vercel
vercel link                                   # writes .vercel/project.json (gitignored)
vercel pull --environment=preview             # project settings + env vars into .vercel/
vercel build                                  # runs the same build as the cloud into .vercel/output
vercel deploy --prebuilt                      # upload that output (useful in custom CI)

Build failures that happen only on Vercel are usually: different Node version (set engines.node in package.json or project settings), missing env var at build time, case-sensitive import paths (Linux), a lockfile mismatch selecting a different package manager, or the wrong root directory in a monorepo. Redeploy without the build cache (dashboard “Redeploy” with cache unchecked, or vercel deploy --force) to rule out stale caches.

3. Environment variables

Environment	Applies to
Production	Deployments from the production branch and vercel deploy --prod
Preview	All other branches; can be overridden per branch
Development	vercel dev and vercel env pull

vercel env ls
vercel env add STRIPE_SECRET_KEY production          # prompts for the value
vercel env add API_URL preview feature-x             # branch-specific preview value
vercel env pull .env.local                            # development values for local work

Rules:

• Changing an env var does not affect existing deployments; redeploy.
• NEXT_PUBLIC_* (and other framework public prefixes like VITE_) are inlined at build time into client bundles: never put secrets there, and rebuild to change them.
• Mark secrets as Sensitive so they are not readable after creation.
• System variables: VERCEL_ENV (production/preview/development), VERCEL_URL (deployment host, no protocol), VERCEL_PROJECT_PRODUCTION_URL, VERCEL_GIT_COMMIT_SHA. Use VERCEL_ENV, not NODE_ENV, to detect previews.
• Preview deployments must not point at production databases or payment keys; give Preview its own values.

4. Functions

Choice	Guidance
Runtime	Node.js by default; Fluid compute runs multiple concurrent requests per instance and reduces cold starts. Use Edge only for tiny latency-critical logic with no Node APIs; Vercel itself recommends Node.js for most workloads
Region	Set the function region next to your database (project settings or "regions": ["fra1"]); a function far from its DB pays a round trip per query
maxDuration	Raise for slow endpoints within plan limits; long jobs belong in a queue or background function, not in a request
Memory/CPU	Raise for CPU-heavy work (image processing, SSR of big pages)

Next.js route segment config:

export const runtime = "nodejs";       // default; "edge" only when justified
export const maxDuration = 60;          // seconds
export const preferredRegion = "fra1";

Other frameworks via vercel.json:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "functions": { "api/**/*.ts": { "maxDuration": 60, "memory": 1024 } },
  "regions": ["fra1"],
  "crons": [{ "path": "/api/cron/cleanup", "schedule": "0 3 * * *" }],
  "redirects": [{ "source": "/old-blog/:slug", "destination": "/blog/:slug", "permanent": true }],
  "rewrites": [{ "source": "/api/:path*", "destination": "https://api.example.com/:path*" }],
  "headers": [{ "source": "/(.*)", "headers": [{ "key": "X-Content-Type-Options", "value": "nosniff" }] }]
}

Cron endpoints are public URLs: verify Authorization: Bearer ${process.env.CRON_SECRET} in the handler (Vercel sends it when CRON_SECRET is set). Crons run only on production deployments. Prefer the framework’s own redirect/header config (e.g. next.config.ts) when the framework supports it, to keep one source of truth.

6. Previews and monorepos

• Deployment Protection: enable Vercel Authentication (or password protection) for previews so unreleased features and preview data are not public. For automated tests against protected previews, use Protection Bypass for Automation with the x-vercel-protection-bypass header, stored as a CI secret.
• Monorepos: one Vercel project per app, each with its Root Directory set. Skip builds for unaffected apps with the Ignored Build Step (npx turbo-ignore for Turborepo, or git diff --quiet HEAD^ HEAD -- . ../../packages/shared which exits 0 to skip).
• Skew protection keeps clients on the deployment they loaded during rollouts, avoiding mismatched assets and server actions after deploys.

7. Promote and roll back

vercel deploy                                  # preview URL
vercel deploy --prod                           # production (requires user confirmation)
vercel promote <deployment-url>                # promote an existing, verified deployment
vercel rollback                                # previous production deployment
vercel rollback <deployment-url>
vercel inspect <deployment-url> --logs         # build logs
vercel logs <deployment-url>                   # runtime logs

Instant rollback re-points production to an earlier build; it does not revert env var changes or database migrations. Production deploys, promotions and rollbacks require explicit user confirmation.

Diagnosing

Symptom	Check
FUNCTION_INVOCATION_TIMEOUT (504)	Slow DB/API calls, wrong region, missing maxDuration, long work in request
Env var undefined at runtime	Scoped to wrong environment, added after deploy (redeploy), or read client-side without public prefix
Works locally, 500 on Vercel	Missing env var, filesystem writes outside /tmp, native module built for wrong platform, region-specific network rule
Build succeeds, page shows old content	Data cache or ISR not revalidated; framework caching rather than deploy issue
Cold start latency	Large bundles, heavy top-level imports, far region; Fluid compute and slimmer imports help
Edge runtime error about Node API	Switch route to Node.js runtime

Gotchas

• Serverless functions have a read-only filesystem except /tmp; nothing persists between invocations.
• Rewrites to external APIs pass through Vercel and count toward bandwidth and function limits.
• vercel dev approximates the platform; confirm behavior on a preview deployment.
• Large public/ assets bloat deployments; serve big media from object storage or a CDN.

Verification

1. vercel build passes locally with pulled preview env vars.
2. Preview deployment: smoke-test critical pages and APIs, check function logs for errors, confirm previews are protected (anonymous request gets the auth wall).
3. vercel env ls shows secrets scoped correctly and no production secrets in Preview.
4. After production promotion, error rate and function duration match the previous deployment; the rollback target is noted.