alivirgo/major-ai-skills/vercel

Vercel Deployment AI Skill Guide (Claude)

Overview & Engine Architecture

Vercel turns Git pushes into immutable deployments. Preview covers non-production branches/PRs; Production tracks the production branch (or vercel --prod). Builds produce static assets, Node serverless functions, and optional Middleware—not long-lived custom servers. Agents keep secrets in Project Environment scopes (Development / Preview / Production), treat NEXT_PUBLIC_* as browser-exposed, pin Node versions, and debug from Build Logs (first real error, not the final exited with 1).

┌─────────────────────────────────────────────────────────────┐
│                 Vercel git → deploy loop                      │
│                                                             │
│  Git push / vercel CLI                                      │
│  ├── First deploy of a new project → Production env         │
│  ├── Later: prod branch / --prod → Production               │
│  └── Other branches / vercel → Preview                      │
│                                                             │
│  Build                                                      │
│  ├── Install + framework build (Next.js preset common)      │
│  ├── Env inlined at build for NEXT_PUBLIC_*                 │
│  └── Fail → read Build Logs (root cause above final line)   │
│                                                             │
│  Runtime                                                    │
│  ├── Static / Serverless Node / Middleware                  │
│  └── Domains ← successful Production deployment             │
└─────────────────────────────────────────────────────────────┘

When to use / when not to

Use when

• Deploying Next.js or compatible frontends to Vercel; configuring env scopes and regions.
• Debugging failed builds, missing prod env, or preview/prod drift.
• Setting up preview URLs for PR review and promotion discipline.

Do not use when

• You need multi-node Kubernetes scheduling or stateful cluster workloads → @kubernetes.
• Long-running background workers / queues are the core need → external workers, not request functions.
• Someone asks to commit production secrets, put private keys in NEXT_PUBLIC_*, or invent Vercel tokens → refuse.

Operational Capabilities & Agent Directives

1. Secrets only in Vercel env (or linked secret store)—never in git. Scope Production / Preview / Development correctly.
2. `NEXT_PUBLIC_*` is public (build-time inlined for Next.js)—no API secrets, DB URLs with passwords, or private keys.
3. Preview vs Production values differ; branch-specific Preview overrides apply. Mirror required keys across scopes so previews do not crash.
4. First deployment of a new project is always treated as Production (even without --prod) and uses Production env—plan env accordingly.
5. Pin Node via engines / Project settings to match local and CI.
6. Prefer framework presets; override install/build/output only when monorepo roots require it (Root Directory, ignored build step carefully).
7. Edge Runtime: Vercel recommends migrating toward Node for many cases; Next.js 16.3+ drops runtime = 'edge' support—verify framework version before prescribing Edge.
8. Diagnose builds from Deployment → Build Logs; fix the first substantive error, not only the last exit line. Reproduce npm run build locally first.
9. Protect production with Git branch protection + required checks; prefer promote/preview workflow over hot-editing prod.
10. Never invent VERCEL_TOKEN or team IDs; use vercel link / dashboard / CI OIDC patterns the user already has.

Production Example: scoped env + safe Next headers

vercel.json (optional overrides—prefer dashboard/framework defaults when enough):

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

package.json engines pin:

{
  "engines": { "node": "20.x" }
}

Env helper (server-only—fail closed):

function requireEnv(name: string): string {
  const v = process.env[name];
  if (!v) throw new Error(`Missing required env: ${name}`);
  return v;
}
// Server route / server component only:
const databaseUrl = requireEnv("DATABASE_URL");
// Browser-safe example only:
const publicAppUrl = process.env.NEXT_PUBLIC_APP_URL; // must be non-secret

CLI loop:

npm i -g vercel
vercel login
vercel link
vercel env pull .env.local          # Development scope
vercel build                        # local parity when available
vercel                              # Preview
vercel --prod                       # Production (explicit)
vercel logs <deployment-url>

Technical Troubleshooting Matrix

Best Practices

1. Use Preview deployments for QA; gate production with reviews.
2. Document monorepo Root Directory and install command in README.
3. Watch function duration, payload size, and Core Web Vitals after launch.
4. Keep vercel.json redirects/headers reviewed in PR like app code.
5. Pair smoke tests on preview URLs with @playwright-ci.
6. Prefer App Router server-side reads for secret env over public inlining.

Limitations

• Request functions are not general-purpose daemons; use queues/workers elsewhere.
• Plan limits (regions, concurrency, timeouts) differ Hobby vs Pro.
• Arbitrary long-lived Express servers are not the Vercel model.
• Stop and ask if project link, env values, or domain DNS ownership are unclear.

Related Skills

• @nextjs — App Router apps Vercel deploys well
• @nodejs — serverless function runtime constraints
• @playwright-ci — smoke-testing preview deployments
• @github-actions — CI that gates merges before production promote
• @cloudflare-dns — DNS for custom domains when not using Vercel nameservers alone

Agent Operational Directive

MANDATORY: Never put secrets in git or NEXT_PUBLIC_*. Scope env vars to Development/Preview/Production and remember the first deploy of a new project uses Production env. Debug builds from the first real error in Build Logs. Do not invent Vercel tokens or prescribe Edge without checking the Next.js version.

Source anchors (research)

• Environment variables & scopes
• Deployments & environments (first deploy = Production)
• Troubleshoot a build
• Edge Runtime notes / migration
• Next.js environment variables