/infra-platform-vercel

name: infra-platform-vercel
description: Vercel deployment platform — project configuration, serverless/edge functions, Routing Middleware, cron jobs, environment variables, monorepo setup

Vercel Platform Patterns

> **Quick Guide:** Configure deployments with `vercel.json` (static) or `vercel.ts` (programmatic, build-time). Functions default to Node.js runtime in `iad1` region. Use `export const runtime = 'edge'` for edge functions (V8 isolates, global deployment). Routing Middleware runs before the cache globally. Secure cron jobs with `CRON_SECRET`. Enable Fluid compute for better concurrency and cost. Always place functions near your data source.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST always include `"$schema": "https://openapi.vercel.sh/vercel.json"` in vercel.json for IDE validation)**

**(You MUST place functions in a region close to your data source -- the default `iad1` may add latency if your database is elsewhere)**

**(You MUST verify `CRON_SECRET` in cron job handlers -- Vercel cron endpoints are publicly accessible URLs)**

**(You MUST design cron jobs to be idempotent -- Vercel may deliver the same cron event more than once)**

**(You MUST NOT store secrets in vercel.json or source code -- use Environment Variables in the Vercel dashboard)**

</critical_requirements>

---

Examples

• [Core Configuration & Functions](examples/core.md) -- vercel.json schema, functions config, runtime selection, regions, environment variables, Fluid compute
• [Routing & Middleware](examples/routing.md) -- Routing Middleware, headers, redirects, rewrites, conditional routing, geo-routing
• [Cron Jobs & Scheduling](examples/cron-jobs.md) -- cron configuration, CRON_SECRET verification, idempotent handlers
• [Monorepo & Advanced](examples/monorepo.md) -- monorepo setup, vercel.ts programmatic config, ignoreCommand, image optimization
• [Quick Reference](reference.md) -- vercel.json property reference, plan limits, region IDs, CLI commands

---

**Auto-detection:** Vercel, vercel.json, vercel.ts, @vercel/config, Vercel Functions, Vercel deploy, VERCEL_URL, VERCEL_ENV, VERCEL_REGION, Routing Middleware, middleware.ts, Edge Runtime, export const runtime, Fluid compute, vercel cron, cron jobs vercel, vercel.json crons, vercel dev, vercel build, vercel deploy, vercel env, vercel link, vercel pull, .vercelignore, vercel monorepo, vercel regions, vercel headers, vercel redirects, vercel rewrites

**When to use:**

• Configuring Vercel project settings via `vercel.json` or `vercel.ts`
• Deploying serverless functions (Node.js or Edge runtime)
• Setting up Routing Middleware for auth, geo-routing, or A/B testing
• Configuring cron jobs for scheduled tasks
• Managing environment variables across preview/production
• Setting up monorepo deployments with per-app configuration
• Configuring headers, redirects, rewrites, and URL routing
• Choosing function regions and memory/duration limits

**When NOT to use:**

• Long-running background jobs exceeding plan limits (use a dedicated job runner)
• Workloads requiring persistent WebSocket connections (Vercel functions are request/response)
• Applications needing custom server runtimes beyond Node.js/Edge/Bun/Python/Go/Ruby

**Key patterns covered:**

• `vercel.json` / `vercel.ts` project configuration with IDE schema validation
• Serverless function configuration (runtime, memory, maxDuration, regions)
• Edge Runtime vs Node.js runtime tradeoffs
• Routing Middleware (runs before cache, global edge execution)
• Cron jobs with `CRON_SECRET` authentication
• Headers, redirects, rewrites with conditional matching (`has`/`missing`)
• Monorepo setup with root directory and ignored build steps
• Fluid compute for improved concurrency and cost efficiency
• Environment variables (`VERCEL_ENV`, `VERCEL_URL`, `VERCEL_REGION`)

---

<philosophy>

Philosophy

Vercel is a deployment platform that auto-detects your framework and optimizes builds, routing, and function deployment. The key architectural principle: **configure only what you need to override**. Vercel's defaults are sensible for most projects -- `vercel.json` exists for when those defaults don't fit.

1. **Convention over configuration** -- Vercel auto-detects frameworks, build commands, and output directories. Only override when the defaults don't work. 2. **Functions near data** -- Serverless functions default to `iad1` (Washington, D.C.). If your database is in Europe, set `regions` to a European region. 3. **Edge for global, Node.js for power** -- Edge runtime runs globally with low latency but has limited APIs. Node.js runtime has full API access but runs in a single region by default. 4. **Routing Middleware runs before cache** -- Use it for personalization, auth, geo-routing. Keep it fast (50ms CPU average on Edge). 5. **Fluid compute** -- Enabled by default for new projects (since April 2025). Reuses function instances for concurrent requests, reducing cold starts and cost.

**When to use Vercel:**

• Deploying web applications with automatic framework detection
• Serverless API endpoints that scale to zero
• Edge-first applications needing global low-latency
• Projects needing preview deployments per PR

**When NOT to use Vercel:**

• Long-running compute exceeding plan maxDuration limits
• Applications requiring persistent connections (WebSockets beyond Vercel's support)
• Workloads with heavy sustained compute (cost-prohibitive at scale)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: vercel.json Configuration

Every Vercel project can have a `vercel.json` at the root for static configuration, or `vercel.ts` for programmatic build-time configuration. Always include the `$schema` for IDE autocompletion.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "regions": ["iad1"],