Expert knowledge for deploying to Vercel with Next.js
\nProperly configure environment variables for all environments
\nWhen to use: Setting up a new project on Vercel
\n// Three environments in Vercel:\n// - Development (local)\n// - Preview (PR deployments)\n// - Production (main branch)
\n// In Vercel Dashboard:\n// Settings → Environment Variables
\n// PUBLIC variables (exposed to browser)\nNEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co\nNEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
\n// PRIVATE variables (server only)\nSUPABASE_SERVICE_ROLE_KEY=eyJ... // Never NEXT_PUBLIC_!\nDATABASE_URL=postgresql://...
\n// Per-environment values:\n// Production: Real database, production API keys\n// Preview: Staging database, test API keys\n// Development: Local/dev values (also in .env.local)
\n// In code, check environment:\nconst isProduction = process.env.VERCEL_ENV === 'production'\nconst isPreview = process.env.VERCEL_ENV === 'preview'
\nChoose the right runtime for your API routes
\nWhen to use: Creating API routes or middleware
\n// EDGE RUNTIME - Fast cold starts, limited APIs\n// Good for: Auth checks, redirects, simple transforms
\n// app/api/hello/route.ts\nexport const runtime = 'edge'
\nexport async function GET() {\nreturn Response.json({ message: 'Hello from Edge!' })\n}
\n// middleware.ts (always edge)\nexport function middleware(request: NextRequest) {\n// Fast auth checks here\n}
\n// SERVERLESS (Node.js) - Full Node APIs, slower cold start\n// Good for: Database queries, file operations, heavy computation
\n// app/api/users/route.ts\nexport const runtime = 'nodejs' // Default, can omit
\nexport async function GET() {\nconst users = await db.query('SELECT * FROM users')\nreturn Response.json(users)\n}
\nOptimize build for faster deployments and smaller bundles
\nWhen to use: Preparing for production deployment
\n// next.config.js\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n// Minimize output\noutput: 'standalone', // For Docker/self-hosting
\n// Image optimization\nimages: {\nremotePatterns: [\n{ hostname: 'your-cdn.com' },\n],\n},
\n// Bundle analyzer (dev only)\n// npm install @next/bundle-analyzer\n...(process.env.ANALYZE === 'true' && {\nwebpack: (config) => {\nconst = require('webpack-bundle-analyzer')\nconfig.plugins.push(new BundleAnalyzerPlugin())\nreturn config\n},\n}),\n}
\n// Reduce serverless function size:\n// - Use dynamic imports for heavy libs\n// - Check bundle with: npx @next/bundle-analyzer
\nUse preview deployments for PR reviews
\nWhen to use: Setting up team development workflow
\n// Every PR gets a unique preview URL automatically
\n// Protect preview deployments with password:\n// Vercel Dashboard → Settings → Deployment Protection
\n// Use different env vars for preview:\n// - PREVIEW: Use staging database\n// - PRODUCTION: Use production database
\n// In code, detect preview:\nif (process.env.VERCEL_ENV === 'preview') {\n// Show \"Preview\" banner\n// Use test payment processor\n// Disable analytics\n}
\n// Comment preview URL on PR (automatic with Vercel GitHub integration)
\nConfigure custom domains with proper SSL
\nWhen to use: Going to production
\n// In Vercel Dashboard → Domains
\n// Add domains:\n// - example.com (apex/root)\n// - www.example.com (subdomain)
\n// DNS Configuration (at your registrar):\n// Type: A, Name: @, Value: 76.76.21.21\n// Type: CNAME, Name: www, Value: cname.vercel-dns.com
\n// Redirect www to apex (or vice versa):\n// Vercel handles this automatically
\n// In next.config.js for redirects:\nmodule.exports = {\nasync redirects() {\nreturn [\n{\nsource: '/old-page',\ndestination: '/new-page',\npermanent: true, // 308\n},\n]\n},\n}
\nSeverity: CRITICAL
\nSituation: Using NEXT_PUBLIC_ prefix for sensitive API keys
\nSymptoms:
\nWhy this breaks:\nVariables prefixed with NEXT_PUBLIC_ are inlined into the JavaScript\nbundle at build time. Anyone can view them in browser DevTools.\nThis includes all your users and potential attackers.
\nRecommended fix:
\nOnly use NEXT_PUBLIC_ for truly public values:
\n// SAFE to use NEXT_PUBLIC_\nNEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co\nNEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ... // Anon key is designed to be public\nNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...\nNEXT_PUBLIC_GA_ID=G-XXXXXXX
\n// NEVER use NEXT_PUBLIC_\nSUPABASE_SERVICE_ROLE_KEY=eyJ... // Full database access!\nSTRIPE_SECRET_KEY=sk_live_... // Can charge cards!\nDATABASE_URL=postgresql://... // Direct DB access!\nJWT_SECRET=... // Can forge tokens!
\n// Access server-only vars in:\n// - Server Components (app router)\n// - API Routes\n// - Server Actions ('use server')\n// - getServerSideProps (pages router)
\nSeverity: HIGH
\nSituation: Not configuring separate environment variables for preview
\nSymptoms:
\nWhy this breaks:\nPreview deployments run untested code. If they use production database,\na bug in a PR can corrupt production data. Also, testers might create\ntest data that shows up in production.
\nRecommended fix:
\nSet up separate databases for each environment:
\n// In Vercel Dashboard → Settings → Environment Variables
\n// Production (production env only):\nDATABASE_URL=postgresql://prod-host/prod-db
\n// Preview (preview env only):\nDATABASE_URL=postgresql://staging-host/staging-db
\n// Or use Vercel's branching databases:\n// - Neon, PlanetScale, Supabase all support branch databases\n// - Auto-create preview DB for each PR
\n// For Supabase, create a staging project:\n// Production:\nNEXT_PUBLIC_SUPABASE_URL=https://prod-xxx.supabase.co
\n// Preview:\nNEXT_PUBLIC_SUPABASE_URL=https://staging-xxx.supabase.co
\nSeverity: HIGH
\nSituation: API route or server component has slow initial load
\nSymptoms:
\nWhy this breaks:\nVercel serverless functions have a 50MB limit (compressed).\nLarge functions mean slow cold starts (1-5+ seconds).\nHeavy dependencies like puppeteer, sharp can cause this.
\nRecommended fix:
\nReduce function size:
\n// 1. Use dynamic imports for heavy libs\nexport async function GET() {\nconst sharp = await import('sharp') // Only loads when needed\n// ...\n}
\n// 2. Move heavy processing to edge or external service\nexport const runtime = 'edge' // Much smaller, faster cold start
\n// 3. Check bundle size\n// npx @next/bundle-analyzer\n// Look for large dependencies
\n// 4. Use external services for heavy tasks\n// - Image processing: Cloudinary, imgix\n// - PDF generation: API service\n// - Puppeteer: Browserless.io
\n// 5. Split into multiple functions\n// /api/heavy-task/start - Queue the job\n// /api/heavy-task/status - Check progress
\nSeverity: HIGH
\nSituation: Using Node.js APIs in edge runtime functions
\nSymptoms:
\nWhy this breaks:\nEdge runtime runs on V8, not Node.js. Many Node APIs are missing:\nfs, path, crypto (partial), child_process, and most native modules.\nYour code will fail at runtime with \"X is not defined\".
\nRecommended fix:
\nCheck API compatibility before using edge:
\n// SUPPORTED in Edge:\n// - fetch, Request, Response\n// - crypto.subtle (Web Crypto)\n// - TextEncoder, TextDecoder\n// - URL, URLSearchParams\n// - Headers, FormData\n// - setTimeout, setInterval
\n// NOT SUPPORTED in Edge:\n// - fs, path, os\n// - Buffer (use Uint8Array)\n// - crypto.createHash (use crypto.subtle)\n// - Most npm packages with native deps
\n// If you need Node.js APIs:\nexport const runtime = 'nodejs' // Use Node runtime instead
\n// For crypto hashing in edge:\n// WRONG\nimport from 'crypto' // Fails in edge
\n// RIGHT\nasync function hash(message: string) {\nconst encoder = new TextEncoder()\nconst data = encoder.encode(message)\nconst hashBuffer = await crypto.subtle.digest('SHA-256', data)\nreturn Array.from(new Uint8Array(hashBuffer))\n.map(b => b.toString(16).padStart(2, '0'))\n.join('')\n}
\nSeverity: MEDIUM
\nSituation: Long-running operations timing out
\nSymptoms:
\nWhy this breaks:\nVercel has timeout limits:
\nOperations exceeding this are killed mid-execution.
\nRecommended fix:
\nHandle long operations properly:
\n// 1. Return early, process async\nexport async function POST(request: Request) {\nconst data = await request.json()
\n// Queue for background processing\nawait queue.add('process-data', data)
\n// Return immediately\nreturn Response.json({ status: 'queued' })\n}
\n// 2. Use streaming for long responses\nexport async function GET() {\nconst stream = new ReadableStream({\nasync start(controller) {\nfor (const chunk of generateChunks()) {\ncontroller.enqueue(chunk)\nawait sleep(100) // Prevents timeout\n}\ncontroller.close()\n}\n})\nreturn new Response(stream)\n}
\n// 3. Use external services for heavy processing\n// - Trigger serverless function, return job ID\n// - Process in background (Inngest, Trigger.dev)\n// - Client polls for completion
\n// 4. Increase timeout (Pro plan)\n// vercel.json:\n{\n\"functions\": {\n\"app/api/slow/route.ts\": {\n\"maxDuration\": 60\n}\n}\n}
\nSeverity: MEDIUM
\nSituation: Environment variable works in build but undefined at runtime
\nSymptoms:
\nWhy this breaks:\nSome env vars are only available at build time (hardcoded into bundle).\nIf you expect a runtime value but it was baked in at build, you get\nthe build-time value or undefined.
\nRecommended fix:
\nUnderstand when env vars are read:
\n// BUILD TIME (baked into bundle):\n// - NEXT_PUBLIC_* variables\n// - next.config.js\n// - generateStaticParams\n// - Static pages
\n// RUNTIME (read on each request):\n// - Server Components (without cache)\n// - API Routes\n// - Server Actions\n// - Middleware
\n// To force runtime reading:\nexport const dynamic = 'force-dynamic'
\n// For config that must be runtime:\n// Don't use NEXT_PUBLIC_, read on server and pass to client
\n// Check which env vars you need:\n// Build: URLs, public keys, feature flags (if static)\n// Runtime: Secrets, database URLs, user-specific config
\nSeverity: MEDIUM
\nSituation: Frontend on different domain can't call API routes
\nSymptoms:
\nWhy this breaks:\nBy default, browsers block cross-origin requests. Vercel doesn't\nautomatically add CORS headers. If your frontend is on a different\ndomain (or localhost in dev), requests fail.
\nRecommended fix:
\nAdd CORS headers to API routes:
\n// app/api/data/route.ts\nexport async function GET(request: Request) {\nconst data = await fetchData()
\nreturn Response.json(data, {\nheaders: {\n'Access-Control-Allow-Origin': '*', // Or specific domain\n'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',\n'Access-Control-Allow-Headers': 'Content-Type, Authorization',\n},\n})\n}
\n// Handle preflight requests\nexport async function OPTIONS() {\nreturn new Response(null, {\nheaders: {\n'Access-Control-Allow-Origin': '*',\n'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',\n'Access-Control-Allow-Headers': 'Content-Type, Authorization',\n},\n})\n}
\n// Or use next.config.js for all routes:\nmodule.exports = {\nasync headers() {\nreturn [\n{\nsource: '/api/:path*',\nheaders: [\n{ key: 'Access-Control-Allow-Origin', value: '*' },\n],\n},\n]\n},\n}
\nSeverity: MEDIUM
\nSituation: Updated data not appearing after new deployment
\nSymptoms:
\nWhy this breaks:\nVercel caches aggressively. Static pages are cached at the edge.\nEven dynamic pages may be cached if not configured properly.\nOld cached versions served until cache expires or is purged.
\nRecommended fix:
\nControl caching behavior:
\n// Force no caching (always fresh)\nexport const dynamic = 'force-dynamic'\nexport const revalidate = 0
\n// ISR - revalidate every 60 seconds\nexport const revalidate = 60
\n// On-demand revalidation (after mutation)\nimport { revalidatePath, revalidateTag } from 'next/cache'
\n// In Server Action:\nasync function updatePost(id: string) {\nawait db.post.update()\nrevalidatePath(/posts/${id}) // Purge this page\nrevalidateTag('posts') // Purge all with this tag\n}
// Purge via API (deployment hook):\n// POST https://your-site.vercel.app/api/revalidate?path=/posts
\n// Check caching in response headers:\n// x-vercel-cache: HIT = served from cache\n// x-vercel-cache: MISS = freshly generated
\nSeverity: CRITICAL
\nMessage: Secret exposed via NEXT_PUBLIC_ prefix. This will be visible in browser.
\nFix action: Remove NEXT_PUBLIC_ prefix and access only in server-side code
\nSeverity: WARNING
\nMessage: Hardcoded Vercel URL. Use VERCEL_URL environment variable instead.
\nFix action: Use process.env.VERCEL_URL or NEXT_PUBLIC_VERCEL_URL
\nSeverity: ERROR
\nMessage: Node.js module used in Edge runtime. fs/path not available in Edge.
\nFix action: Use runtime = 'nodejs' or remove Node.js dependencies
\nSeverity: WARNING
\nMessage: API route without CORS headers may fail cross-origin requests.
\nFix action: Add Access-Control-Allow-Origin header if API is called from other domains
\nSeverity: WARNING
\nMessage: API route without try/catch. Unhandled errors return 500 without details.
\nFix action: Wrap in try/catch and return appropriate error responses
\nSeverity: WARNING
\nMessage: Server secret accessed in static generation. Value baked into build.
\nFix action: Move secret access to runtime code or use NEXT_PUBLIC_ for public values
\nSeverity: WARNING
\nMessage: Large package imported. May cause slow cold starts. Consider alternatives.
\nFix action: Use lodash-es with tree shaking, date-fns instead of moment, @aws-sdk/client-* instead of aws-sdk
\nSeverity: WARNING
\nMessage: Dynamic page without revalidation config. Consider setting revalidation strategy.
\nFix action: Add export const revalidate = 60 for ISR, or 0 for no cache
\nSkills: vercel-deployment, nextjs-app-router, supabase-backend, nextjs-supabase-auth
\nWorkflow:
\n1. App configuration (nextjs-app-router)\n2. Database setup (supabase-backend)\n3. Auth config (nextjs-supabase-auth)\n4. Deploy (vercel-deployment)\nSkills: vercel-deployment, devops, qa-engineering
\nWorkflow:
\n1. Test automation (qa-engineering)\n2. Pipeline config (devops)\n3. Deploy strategy (vercel-deployment)\nWorks well with: nextjs-app-router, supabase-backend