vercel-deployment

---

description: "Best practices for Vercel deployments including serverless functions, Edge Runtime, middleware, caching, environment variables, and CI/CD configuration" globs: ["vercel.json", ".vercelignore", "middleware.ts", "middleware.js", "api//*", "app/api//*"] alwaysApply: false

You are an expert in Vercel deployments, serverless architecture, and modern web application hosting.

Core Principles

• Always optimize for Vercel's edge network and serverless model
• Prefer Edge Runtime for globally distributed, low-latency responses
• Use Vercel's built-in environment variable management for secrets
• Structure projects to leverage Vercel's zero-config deployment detection
• Always use vercel.json for advanced routing, headers, and redirects configuration

vercel.json Configuration

• Use rewrites for proxying API calls or SPA fallback routing
• Use redirects for permanent (308) or temporary (307) URL changes
• Use headers to set security headers (CSP, HSTS, X-Frame-Options) globally
• Use regions to pin serverless functions to specific regions when data locality matters
• Always include security headers:

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-XSS-Protection", "value": "1; mode=block" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

Serverless Functions

• Keep dependencies minimal — bundle size directly impacts cold starts
• Use Edge Functions (export const runtime = 'edge') for auth checks, redirects, and A/B testing
• Use Node.js runtime for database connections, heavy computation, or Node-only packages
• Always handle errors and return proper HTTP status codes
• Use streaming responses for LLM or large data outputs

Edge Middleware

• Place middleware.ts at the project root
• Use middleware for: auth guards, geo-based redirects, bot protection, A/B flags
• Keep middleware lightweight — runs on every request before the cache
• Always use matcher config to scope middleware to needed routes only:

export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
}

Environment Variables

• Never hard-code secrets; always use process.env.VARIABLE_NAME
• Prefix client-side env vars with NEXT_PUBLIC_ (Next.js) or expose explicitly per framework
• Use Vercel CLI (vercel env add) or the Vercel dashboard to manage per-environment values
• Use .env.local for local development — never commit it

Performance & Caching

• Use Cache-Control headers to control CDN caching: s-maxage for CDN TTL, max-age for browser
• Use stale-while-revalidate for ISR-like behavior in non-Next.js apps
• Avoid over-fetching in serverless functions — reuse DB connections with connection pooling
• Use vercel/og for dynamic OG image generation at the edge

CI/CD & Preview Deployments

• Use Vercel's GitHub/GitLab/Bitbucket integration for automatic preview deployments per PR
• Use vercel pull + vercel build + vercel deploy --prebuilt in custom CI pipelines
• Use VERCEL_ENV to differentiate behavior across preview/production

Databases & Storage

• Prefer Vercel-native storage (Vercel KV, Vercel Postgres, Vercel Blob) for zero-config integration
• For external databases, always use connection pooling — serverless functions don't maintain persistent connections

Security Best Practices

• Enable Vercel's DDoS protection and Firewall rules for malicious IP/pattern blocking
• Rotate secrets regularly using Vercel's environment variable versioning
• Never log sensitive data (tokens, passwords, PII) in serverless function output
• Use VERCEL_OIDC_TOKEN for secure machine-to-machine auth between Vercel and cloud providers