Vercel Deployment skill for Codex

A healthy Vercel project builds the same way locally, in CI and on Vercel; every environment variable is scoped to the right environment; functions run in the region next to their database; and production can be rolled back in under a minute without a rebuild.

Inspect first

1. Read AGENTS.md, package.json, the lockfile and vercel.json (or vercel.ts).
2. Check .vercel/project.json exists. If not, the directory is not linked: vercel link needs network and a logged-in CLI, so ask the user to run it or provide VERCEL_TOKEN.
3. Identify the framework. Next.js, SvelteKit, Nuxt, Astro and Remix configure functions through the framework; plain api/ directories use Vercel Functions directly.
4. Note the monorepo root: the Vercel project’s Root Directory setting must point at the app package, and the install command must run from the workspace root.

Core CLI loop

vercel pull --yes --environment=preview     # project settings + env into .vercel/
vercel env pull .env.local                  # development env vars for local runs
vercel build                                # reproduce the cloud build locally
vercel deploy                               # preview deployment, prints a unique URL
vercel deploy --prod                        # production: ask the user first
vercel inspect <deployment-url> --logs      # build logs of one deployment
vercel logs <deployment-url>                # runtime logs
vercel promote <deployment-url>             # make an existing deployment production
vercel rollback                             # instant rollback to the previous production

Every command that talks to Vercel needs network. In CI, pass --token "$VERCEL_TOKEN" and set VERCEL_ORG_ID and VERCEL_PROJECT_ID.

Environment variables

Scope	Used by
Production	vercel deploy --prod and the production branch
Preview	Every other branch; can be narrowed to one branch
Development	vercel env pull and vercel dev only

vercel env ls
vercel env add DATABASE_URL production        # prompts for the value; mark it sensitive
vercel env add DATABASE_URL preview feature-x # branch-scoped preview value
vercel env rm OLD_KEY production

Rules:

• Changing a variable does not affect existing deployments. Redeploy after every change.
• Anything prefixed for the client (NEXT_PUBLIC_, VITE_, PUBLIC_) is inlined into the bundle at build time and is public. Never put secrets there.
• Preview deployments must not point at the production database. Give Preview its own DATABASE_URL or a branch database from a Marketplace integration.
• System variables worth using: VERCEL_ENV (production, preview, development), VERCEL_URL (deployment host, no protocol), VERCEL_GIT_COMMIT_SHA.

vercel.json essentials

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "regions": ["iad1"],
  "functions": {
    "api/reports/*.ts": { "maxDuration": 120, "memory": 1769 }
  },
  "crons": [{ "path": "/api/cron/cleanup", "schedule": "0 3 * * *" }],
  "redirects": [{ "source": "/docs/:path*", "destination": "https://docs.example.com/:path*", "permanent": true }],
  "rewrites": [{ "source": "/app/(.*)", "destination": "/app/index.html" }],
  "headers": [{
    "source": "/assets/(.*)",
    "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
  }],
  "cleanUrls": true
}

• regions: put functions next to the database. A function in iad1 querying a database in Frankfurt adds roughly 90 ms per round trip; an ORM doing five queries pays it five times.
• maxDuration and memory limits depend on the plan and on whether Fluid compute is on (it is the default for new projects). Check the current plan limits instead of guessing; move anything longer than a few minutes to a queue or background worker.
• Frameworks with their own routing (Next.js) should keep redirects in the framework config so they work in next dev too.

Cron jobs

Vercel calls the cron path with GET on the production deployment only. Protect it:

export async function GET(req: Request) {
  if (req.headers.get("authorization") !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response("unauthorized", { status: 401 });
  }
  await cleanup();
  return Response.json({ ok: true });
}

Set CRON_SECRET in Production; Vercel sends it as a bearer token automatically. Make the job idempotent: a cron can run twice or be skipped.

Edge Config

Use Edge Config for small, read-mostly values needed on every request (feature flags, redirect maps, IP blocklists). Reads are fast; writes go through the REST API or dashboard and propagate in seconds.

import { get } from "@vercel/edge-config";   // reads the EDGE_CONFIG connection string

export async function middleware() {
  const maintenance = await get<boolean>("maintenance");
  if (maintenance) return new Response("Down for maintenance", { status: 503 });
}

Do not use it as a database: it has a small total size and is not designed for frequent writes. For per-user data use a real store from the Marketplace (Postgres, Redis).

CI deploys with prebuilt output

Build once in CI, deploy the exact artifact:

- run: npm i -g vercel@latest
- run: vercel pull --yes --environment=production --token "$VERCEL_TOKEN"
- run: vercel build --prod --token "$VERCEL_TOKEN"
- run: vercel deploy --prebuilt --prod --token "$VERCEL_TOKEN"
  env:
    VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

When CI deploys, disable Git-triggered builds for the same branch ("git": {"deploymentEnabled": false} or per branch) so each commit is not built twice.

Decision table

Symptom	First check
Works locally, fails on Vercel build	Node version setting, lockfile committed, Root Directory, vercel build locally
undefined env var at runtime	Scope (Preview vs Production), redeploy after change, client prefix
Function 504 / timeout	maxDuration, region vs database, slow cold path, long work in request
Preview visible to strangers	Deployment Protection settings; use the bypass secret for automated tests
Users get 404 for old JS chunks after deploy	Enable Skew Protection or keep old assets
Production broke after deploy	vercel rollback first, investigate second

Verification

• vercel build succeeds locally with pulled settings.
• A preview deploy URL serves the change; curl -I shows expected headers and redirects.
• Runtime logs show no missing-env errors; cron route returns 401 without the secret.
• Production deploys, promotes and rollbacks happen only after explicit user approval.

Gotchas

• vercel dev does not perfectly emulate every framework; trust vercel build plus a preview deploy over vercel dev for routing questions.
• Edge runtime functions cannot use most Node APIs or native modules; Vercel now recommends the Node.js runtime unless you need the edge specifically.
• Environment variables have a total size cap per deployment; large certificates or JSON blobs belong in a secret store or file, not in env.
• vercel rollback points the production domain at an older deployment, but env vars and databases do not roll back with it. Data migrations need their own reverse plan.

Output

## Vercel change: <summary>
- Project / root dir / framework:
- Env vars added or changed (name, scopes; never values):
- vercel.json changes:
- Preview URL tested:
- Production action taken (with user approval) or pending:
- Rollback path: vercel rollback / promote <url>