{"filename":"vercel-deployment.mdc","content":"---\ndescription: \"Best practices for Vercel deployments including serverless functions, Edge Runtime, middleware, caching, environment variables, and CI/CD configuration\"\nglobs: [\"vercel.json\", \".vercelignore\", \"middleware.ts\", \"middleware.js\", \"api/**/*\", \"app/api/**/*\"]\nalwaysApply: false\n---\nYou are an expert in Vercel deployments, serverless architecture, and modern web application hosting.\n\n## Core Principles\n- Always optimize for Vercel's edge network and serverless model\n- Prefer Edge Runtime for globally distributed, low-latency responses\n- Use Vercel's built-in environment variable management for secrets\n- Structure projects to leverage Vercel's zero-config deployment detection\n- Always use `vercel.json` for advanced routing, headers, and redirects configuration\n\n## vercel.json Configuration\n- Use `rewrites` for proxying API calls or SPA fallback routing\n- Use `redirects` for permanent (308) or temporary (307) URL changes\n- Use `headers` to set security headers (CSP, HSTS, X-Frame-Options) globally\n- Use `regions` to pin serverless functions to specific regions when data locality matters\n- Always include security headers:\n```json\n{\n  \"headers\": [\n    {\n      \"source\": \"/(.*)\",\n      \"headers\": [\n        { \"key\": \"X-Content-Type-Options\", \"value\": \"nosniff\" },\n        { \"key\": \"X-Frame-Options\", \"value\": \"DENY\" },\n        { \"key\": \"X-XSS-Protection\", \"value\": \"1; mode=block\" },\n        { \"key\": \"Referrer-Policy\", \"value\": \"strict-origin-when-cross-origin\" }\n      ]\n    }\n  ]\n}\n```\n\n## Serverless Functions\n- Keep dependencies minimal — bundle size directly impacts cold starts\n- Use Edge Functions (`export const runtime = 'edge'`) for auth checks, redirects, and A/B testing\n- Use Node.js runtime for database connections, heavy computation, or Node-only packages\n- Always handle errors and return proper HTTP status codes\n- Use streaming responses for LLM or large data outputs\n\n## Edge Middleware\n- Place `middleware.ts` at the project root\n- Use middleware for: auth guards, geo-based redirects, bot protection, A/B flags\n- Keep middleware lightweight — runs on every request before the cache\n- Always use `matcher` config to scope middleware to needed routes only:\n```ts\nexport const config = {\n  matcher: ['/dashboard/:path*', '/api/:path*'],\n}\n```\n\n## Environment Variables\n- Never hard-code secrets; always use `process.env.VARIABLE_NAME`\n- Prefix client-side env vars with `NEXT_PUBLIC_` (Next.js) or expose explicitly per framework\n- Use Vercel CLI (`vercel env add`) or the Vercel dashboard to manage per-environment values\n- Use `.env.local` for local development — never commit it\n\n## Performance & Caching\n- Use `Cache-Control` headers to control CDN caching: `s-maxage` for CDN TTL, `max-age` for browser\n- Use `stale-while-revalidate` for ISR-like behavior in non-Next.js apps\n- Avoid over-fetching in serverless functions — reuse DB connections with connection pooling\n- Use `vercel/og` for dynamic OG image generation at the edge\n\n## CI/CD & Preview Deployments\n- Use Vercel's GitHub/GitLab/Bitbucket integration for automatic preview deployments per PR\n- Use `vercel pull` + `vercel build` + `vercel deploy --prebuilt` in custom CI pipelines\n- Use `VERCEL_ENV` to differentiate behavior across preview/production\n\n## Databases & Storage\n- Prefer Vercel-native storage (Vercel KV, Vercel Postgres, Vercel Blob) for zero-config integration\n- For external databases, always use connection pooling — serverless functions don't maintain persistent connections\n\n## Security Best Practices\n- Enable Vercel's DDoS protection and Firewall rules for malicious IP/pattern blocking\n- Rotate secrets regularly using Vercel's environment variable versioning\n- Never log sensitive data (tokens, passwords, PII) in serverless function output\n- Use `VERCEL_OIDC_TOKEN` for secure machine-to-machine auth between Vercel and cloud providers\n"}