CLAUDE.md for Vercel Deployments

Why Vercel Deployments Need Platform-Aware Rules

Vercel is a serverless platform — there are no long-running servers, no Docker containers, no PM2 process managers. AI assistants generate deployment patterns from traditional server training data: Dockerfiles, nginx configs, systemd services, and PM2 ecosystem files. None of these exist on Vercel. Your code runs as serverless functions with cold starts, execution time limits, and no persistent filesystem.

The second challenge: Vercel offers two runtimes — Node.js (full Node API, up to 60s execution, larger memory) and Edge Runtime (V8 isolates, sub-millisecond cold starts, limited API, 25ms-30s execution). AI doesn't distinguish between them and generates code that uses Node-only APIs (fs, child_process) in Edge functions that don't support them.

These rules target Vercel with Next.js (the primary use case) but apply to any framework deployed on Vercel. They cover serverless constraints, runtime selection, environment variables, and Vercel-specific optimizations.

Rule 1: Serverless Function Constraints

The rule: 'API routes and server components run as serverless functions with: 10-second default timeout (configurable to 60s on Pro, 300s on Enterprise), 50MB max function size (including node_modules), no persistent filesystem (use external storage), cold starts on first request after idle. Design for these constraints: fast execution, minimal dependencies, external state.'

For function size: 'Minimize node_modules in serverless functions. Use tree-shakeable packages. Avoid heavy dependencies (puppeteer, sharp without @next/image) in API routes. If a function exceeds 50MB, split it or move heavy processing to a separate service. Use bundle analyzer to identify bloated dependencies.'

For statelessness: 'Functions don't share memory between requests — no in-memory caches, no global state that persists, no connection pools that survive between invocations. Use external services: Redis for caching (Vercel KV), PostgreSQL for state (Vercel Postgres / Neon), Blob Store for files (Vercel Blob). Design every function as if it's the first and last time it runs.'

• Timeouts: 10s default, 60s Pro, 300s Enterprise — design for fast execution
• 50MB max function size — tree-shake, minimize dependencies
• No persistent filesystem — Vercel Blob, S3, or external storage
• No shared memory between requests — external Redis/DB for state
• Cold starts: first request after idle is slower — minimize init code

Rule 2: Edge Runtime vs Node.js Runtime

The rule: 'Use Edge Runtime for: middleware, simple API routes, redirects, A/B testing, geolocation-based responses, and anything that needs sub-millisecond cold starts. Use Node.js runtime for: database queries, heavy computation, file processing, and anything that needs full Node.js APIs. Set runtime per route: export const runtime = "edge" or export const runtime = "nodejs".'

For Edge limitations: 'Edge Runtime runs V8 isolates, not Node.js. No: fs, child_process, net, crypto (use Web Crypto), path (use URL), Buffer (use Uint8Array). Maximum execution: 25ms-30s depending on plan. Use for lightweight, fast operations. If your function needs Node APIs, use Node.js runtime.'

For middleware: 'Next.js middleware always runs on Edge. Keep middleware lightweight: auth token verification, redirects, geolocation, header modification. Don't: query databases (use Node runtime), process large payloads, or run complex logic. Middleware runs on every request to matched paths — it must be fast.'

Rule 3: Environment Variable Management

The rule: 'Configure environment variables in the Vercel dashboard — not in .env files deployed to the platform. Vercel supports three scopes: Production (main branch), Preview (PR branches), and Development (local with vercel env pull). Use NEXT_PUBLIC_ prefix for client-side variables. Never commit secrets to the repo — Vercel dashboard is the source of truth for env vars.'

For local development: 'Pull env vars from Vercel: vercel env pull .env.local. This creates a .env.local with your development-scope variables. .env.local is in .gitignore — never committed. Use this instead of manually creating .env files — it stays in sync with the Vercel dashboard.'

For secrets: 'Use Vercel's encrypted environment variables for secrets (API keys, database URLs, auth secrets). Vercel encrypts at rest and injects at runtime. Never use process.env for secrets in client-side code — even with server components, build logs may expose them. Use server actions or API routes to access secrets.'

• Vercel dashboard for env vars — not .env files on the platform
• Three scopes: Production, Preview, Development — different values per scope
• NEXT_PUBLIC_ prefix for client-accessible — unprefixed for server-only
• vercel env pull for local .env.local — stays in sync with dashboard
• Encrypted secrets — never in client code or build logs

Rule 4: Preview Deployments and Git Integration

The rule: 'Every PR gets an automatic preview deployment — a unique URL with the PR's code. Use preview deployments for: visual review, QA testing, stakeholder demos, and integration testing. Set Preview environment variables with test API keys and staging database URLs — never production credentials on preview deployments.'

For comments and checks: 'Vercel posts deployment URLs as PR comments — link directly to the changed page. Use Vercel's deployment checks integration: run Playwright tests against the preview URL. Use deployment protection for sensitive preview content: require authentication to view preview deployments.'

For branching strategy: 'main → production deployment (automatic). Feature branches → preview deployments (automatic). Use Preview environment for staging-equivalent testing. Never deploy directly to production without a preview — the preview is your pre-production verification step.'

Rule 5: Vercel-Specific Optimizations

The rule: 'Use Vercel's caching: set Cache-Control headers on API routes for CDN caching (s-maxage=60, stale-while-revalidate). Use ISR (Incremental Static Regeneration) for pages that update periodically. Use Vercel Image Optimization (next/image) — it resizes, compresses, and serves WebP automatically from Vercel's CDN. Use Vercel Analytics for real-user web vitals monitoring.'

For Vercel services: 'Use Vercel KV (Redis) for caching and rate limiting. Use Vercel Postgres (Neon) for database. Use Vercel Blob for file storage. Use Vercel Cron for scheduled tasks. These integrate natively with Vercel's infrastructure — no configuration, no connection management, optimal latency.'

For build optimization: 'Use next.config output: "standalone" for minimal builds. Enable experimental.optimizePackageImports for tree-shaking large packages. Use @vercel/speed-insights for real-user performance data. Monitor build times — Vercel has build time limits (45 minutes Pro). Use turbopack for faster development builds.'

Complete Vercel Rules Template

Consolidated rules for Vercel deployment.

• Serverless constraints: timeouts, 50MB size, no filesystem, no shared memory
• Edge Runtime for middleware/fast routes — Node.js for DB/compute — set per route
• Env vars in Vercel dashboard — three scopes — NEXT_PUBLIC_ for client — secrets encrypted
• Preview deployments: auto per PR, separate env vars, test against preview URL
• ISR for periodic pages — Cache-Control for API caching — next/image for optimization
• Vercel KV, Postgres, Blob, Cron — native services, optimal latency
• output: standalone — optimizePackageImports — turbopack for dev
• vercel env pull for local dev — Vercel Analytics for real-user web vitals