Menú
Expert knowledge for deploying to Vercel with Next.js
Use when CrossFrame Suite routes explicit Chinese casebook work: turning materials into reusable cases, anonymized entries, mechanisms, and retrieval indexes.
Use only when the user explicitly names crossframe-critical for a Chinese structural critique dossier, article plan, or long-form critical essay.
Use when CrossFrame Suite routes explicit Chinese proposition testing, debate analysis, hidden-premise review, rebuttal design, or withdrawal condition checks.
Use when CrossFrame Suite routes explicit Chinese reader replies, editor responses, consultation-style short answers, or boundary-aware structural advice.
Use when explicit CrossFrame work needs a Chinese critical insight essay, commentary, concept essay, public piece, or structure-to-article draft after diagnosis.
Use when CrossFrame Suite routes explicit Chinese notes for books, theories, articles, excerpts, bidirectional reading, absorption, or conflict mapping.
| name | vercel-deployment |
| description | Expert knowledge for deploying to Vercel with Next.js |
| risk | safe |
| source | vibeship-spawner-skills (Apache 2.0) |
| date_added | "2026-02-27T00:00:00.000Z" |
Expert knowledge for deploying to Vercel with Next.js
Properly configure environment variables for all environments
When to use: Setting up a new project on Vercel
// Three environments in Vercel: // - Development (local) // - Preview (PR deployments) // - Production (main branch)
// In Vercel Dashboard: // Settings → Environment Variables
// PUBLIC variables (exposed to browser) NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
// PRIVATE variables (server only) SUPABASE_SERVICE_ROLE_KEY=eyJ... // Never NEXT_PUBLIC_! DATABASE_URL=postgresql://...
// Per-environment values: // Production: Real database, production API keys // Preview: Staging database, test API keys // Development: Local/dev values (also in .env.local)
// In code, check environment: const isProduction = process.env.VERCEL_ENV === 'production' const isPreview = process.env.VERCEL_ENV === 'preview'
Choose the right runtime for your API routes
When to use: Creating API routes or middleware
// EDGE RUNTIME - Fast cold starts, limited APIs // Good for: Auth checks, redirects, simple transforms
// app/api/hello/route.ts export const runtime = 'edge'
export async function GET() { return Response.json({ message: 'Hello from Edge!' }) }
// middleware.ts (always edge) export function middleware(request: NextRequest) { // Fast auth checks here }
// SERVERLESS (Node.js) - Full Node APIs, slower cold start // Good for: Database queries, file operations, heavy computation
// app/api/users/route.ts export const runtime = 'nodejs' // Default, can omit
export async function GET() { const users = await db.query('SELECT * FROM users') return Response.json(users) }
Optimize build for faster deployments and smaller bundles
When to use: Preparing for production deployment
// next.config.js /** @type {import('next').NextConfig} */ const nextConfig = { // Minimize output output: 'standalone', // For Docker/self-hosting
// Image optimization images: { remotePatterns: [ { hostname: 'your-cdn.com' }, ], },
// Bundle analyzer (dev only) // npm install @next/bundle-analyzer ...(process.env.ANALYZE === 'true' && { webpack: (config) => { const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer') config.plugins.push(new BundleAnalyzerPlugin()) return config }, }), }
// Reduce serverless function size: // - Use dynamic imports for heavy libs // - Check bundle with: npx @next/bundle-analyzer
Use preview deployments for PR reviews
When to use: Setting up team development workflow
// Every PR gets a unique preview URL automatically
// Protect preview deployments with password: // Vercel Dashboard → Settings → Deployment Protection
// Use different env vars for preview: // - PREVIEW: Use staging database // - PRODUCTION: Use production database
// In code, detect preview: if (process.env.VERCEL_ENV === 'preview') { // Show "Preview" banner // Use test payment processor // Disable analytics }
// Comment preview URL on PR (automatic with Vercel GitHub integration)
Configure custom domains with proper SSL
When to use: Going to production
// In Vercel Dashboard → Domains
// Add domains: // - example.com (apex/root) // - www.example.com (subdomain)
// DNS Configuration (at your registrar): // Type: A, Name: @, Value: 76.76.21.21 // Type: CNAME, Name: www, Value: cname.vercel-dns.com
// Redirect www to apex (or vice versa): // Vercel handles this automatically
// In next.config.js for redirects: module.exports = { async redirects() { return [ { source: '/old-page', destination: '/new-page', permanent: true, // 308 }, ] }, }
Severity: CRITICAL
Situation: Using NEXT_PUBLIC_ prefix for sensitive API keys
Symptoms:
Why this breaks: Variables prefixed with NEXT_PUBLIC_ are inlined into the JavaScript bundle at build time. Anyone can view them in browser DevTools. This includes all your users and potential attackers.
Recommended fix:
Only use NEXT_PUBLIC_ for truly public values:
// SAFE to use NEXT_PUBLIC_ NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ... // Anon key is designed to be public NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_... NEXT_PUBLIC_GA_ID=G-XXXXXXX
// NEVER use NEXT_PUBLIC_ SUPABASE_SERVICE_ROLE_KEY=eyJ... // Full database access! STRIPE_SECRET_KEY=sk_live_... // Can charge cards! DATABASE_URL=postgresql://... // Direct DB access! JWT_SECRET=... // Can forge tokens!
// Access server-only vars in: // - Server Components (app router) // - API Routes // - Server Actions ('use server') // - getServerSideProps (pages router)
Severity: HIGH
Situation: Not configuring separate environment variables for preview
Symptoms:
Why this breaks: Preview deployments run untested code. If they use production database, a bug in a PR can corrupt production data. Also, testers might create test data that shows up in production.
Recommended fix:
Set up separate databases for each environment:
// In Vercel Dashboard → Settings → Environment Variables
// Production (production env only): DATABASE_URL=postgresql://prod-host/prod-db
// Preview (preview env only): DATABASE_URL=postgresql://staging-host/staging-db
// Or use Vercel's branching databases: // - Neon, PlanetScale, Supabase all support branch databases // - Auto-create preview DB for each PR
// For Supabase, create a staging project: // Production: NEXT_PUBLIC_SUPABASE_URL=https://prod-xxx.supabase.co
// Preview: NEXT_PUBLIC_SUPABASE_URL=https://staging-xxx.supabase.co
Severity: HIGH
Situation: API route or server component has slow initial load
Symptoms:
Why this breaks: Vercel serverless functions have a 50MB limit (compressed). Large functions mean slow cold starts (1-5+ seconds). Heavy dependencies like puppeteer, sharp can cause this.
Recommended fix:
Reduce function size:
// 1. Use dynamic imports for heavy libs export async function GET() { const sharp = await import('sharp') // Only loads when needed // ... }
// 2. Move heavy processing to edge or external service export const runtime = 'edge' // Much smaller, faster cold start
// 3. Check bundle size // npx @next/bundle-analyzer // Look for large dependencies
// 4. Use external services for heavy tasks // - Image processing: Cloudinary, imgix // - PDF generation: API service // - Puppeteer: Browserless.io
// 5. Split into multiple functions // /api/heavy-task/start - Queue the job // /api/heavy-task/status - Check progress
Severity: HIGH
Situation: Using Node.js APIs in edge runtime functions
Symptoms:
Why this breaks: Edge runtime runs on V8, not Node.js. Many Node APIs are missing: fs, path, crypto (partial), child_process, and most native modules. Your code will fail at runtime with "X is not defined".
Recommended fix:
Check API compatibility before using edge:
// SUPPORTED in Edge: // - fetch, Request, Response // - crypto.subtle (Web Crypto) // - TextEncoder, TextDecoder // - URL, URLSearchParams // - Headers, FormData // - setTimeout, setInterval
// NOT SUPPORTED in Edge: // - fs, path, os // - Buffer (use Uint8Array) // - crypto.createHash (use crypto.subtle) // - Most npm packages with native deps
// If you need Node.js APIs: export const runtime = 'nodejs' // Use Node runtime instead
// For crypto hashing in edge: // WRONG import { createHash } from 'crypto' // Fails in edge
// RIGHT async function hash(message: string) { const encoder = new TextEncoder() const data = encoder.encode(message) const hashBuffer = await crypto.subtle.digest('SHA-256', data) return Array.from(new Uint8Array(hashBuffer)) .map(b => b.toString(16).padStart(2, '0')) .join('') }
Severity: MEDIUM
Situation: Long-running operations timing out
Symptoms:
Why this breaks: Vercel has timeout limits:
Operations exceeding this are killed mid-execution.
Recommended fix:
Handle long operations properly:
// 1. Return early, process async export async function POST(request: Request) { const data = await request.json()
// Queue for background processing await queue.add('process-data', data)
// Return immediately return Response.json({ status: 'queued' }) }
// 2. Use streaming for long responses export async function GET() { const stream = new ReadableStream({ async start(controller) { for (const chunk of generateChunks()) { controller.enqueue(chunk) await sleep(100) // Prevents timeout } controller.close() } }) return new Response(stream) }
// 3. Use external services for heavy processing // - Trigger serverless function, return job ID // - Process in background (Inngest, Trigger.dev) // - Client polls for completion
// 4. Increase timeout (Pro plan) // vercel.json: { "functions": { "app/api/slow/route.ts": { "maxDuration": 60 } } }
Severity: MEDIUM
Situation: Environment variable works in build but undefined at runtime
Symptoms:
Why this breaks: Some env vars are only available at build time (hardcoded into bundle). If you expect a runtime value but it was baked in at build, you get the build-time value or undefined.
Recommended fix:
Understand when env vars are read:
// BUILD TIME (baked into bundle): // - NEXT_PUBLIC_* variables // - next.config.js // - generateStaticParams // - Static pages
// RUNTIME (read on each request): // - Server Components (without cache) // - API Routes // - Server Actions // - Middleware
// To force runtime reading: export const dynamic = 'force-dynamic'
// For config that must be runtime: // Don't use NEXT_PUBLIC_, read on server and pass to client
// Check which env vars you need: // Build: URLs, public keys, feature flags (if static) // Runtime: Secrets, database URLs, user-specific config
Severity: MEDIUM
Situation: Frontend on different domain can't call API routes
Symptoms:
Why this breaks: By default, browsers block cross-origin requests. Vercel doesn't automatically add CORS headers. If your frontend is on a different domain (or localhost in dev), requests fail.
Recommended fix:
Add CORS headers to API routes:
// app/api/data/route.ts export async function GET(request: Request) { const data = await fetchData()
return Response.json(data, { headers: { 'Access-Control-Allow-Origin': '*', // Or specific domain 'Access-Control-Allow-Methods': 'GET, POST, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', }, }) }
// Handle preflight requests export async function OPTIONS() { return new Response(null, { headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', }, }) }
// Or use next.config.js for all routes: module.exports = { async headers() { return [ { source: '/api/:path*', headers: [ { key: 'Access-Control-Allow-Origin', value: '*' }, ], }, ] }, }
Severity: MEDIUM
Situation: Updated data not appearing after new deployment
Symptoms:
Why this breaks: Vercel caches aggressively. Static pages are cached at the edge. Even dynamic pages may be cached if not configured properly. Old cached versions served until cache expires or is purged.
Recommended fix:
Control caching behavior:
// Force no caching (always fresh) export const dynamic = 'force-dynamic' export const revalidate = 0
// ISR - revalidate every 60 seconds export const revalidate = 60
// On-demand revalidation (after mutation) import { revalidatePath, revalidateTag } from 'next/cache'
// In Server Action:
async function updatePost(id: string) {
await db.post.update({ ... })
revalidatePath(/posts/${id}) // Purge this page
revalidateTag('posts') // Purge all with this tag
}
// Purge via API (deployment hook): // POST https://your-site.vercel.app/api/revalidate?path=/posts
// Check caching in response headers: // x-vercel-cache: HIT = served from cache // x-vercel-cache: MISS = freshly generated
Severity: CRITICAL
Message: Secret exposed via NEXT_PUBLIC_ prefix. This will be visible in browser.
Fix action: Remove NEXT_PUBLIC_ prefix and access only in server-side code
Severity: WARNING
Message: Hardcoded Vercel URL. Use VERCEL_URL environment variable instead.
Fix action: Use process.env.VERCEL_URL or NEXT_PUBLIC_VERCEL_URL
Severity: ERROR
Message: Node.js module used in Edge runtime. fs/path not available in Edge.
Fix action: Use runtime = 'nodejs' or remove Node.js dependencies
Severity: WARNING
Message: API route without CORS headers may fail cross-origin requests.
Fix action: Add Access-Control-Allow-Origin header if API is called from other domains
Severity: WARNING
Message: API route without try/catch. Unhandled errors return 500 without details.
Fix action: Wrap in try/catch and return appropriate error responses
Severity: WARNING
Message: Server secret accessed in static generation. Value baked into build.
Fix action: Move secret access to runtime code or use NEXT_PUBLIC_ for public values
Severity: WARNING
Message: Large package imported. May cause slow cold starts. Consider alternatives.
Fix action: Use lodash-es with tree shaking, date-fns instead of moment, @aws-sdk/client-* instead of aws-sdk
Severity: WARNING
Message: Dynamic page without revalidation config. Consider setting revalidation strategy.
Fix action: Add export const revalidate = 60 for ISR, or 0 for no cache
Skills: vercel-deployment, nextjs-app-router, supabase-backend, nextjs-supabase-auth
Workflow:
1. App configuration (nextjs-app-router)
2. Database setup (supabase-backend)
3. Auth config (nextjs-supabase-auth)
4. Deploy (vercel-deployment)
Skills: vercel-deployment, devops, qa-engineering
Workflow:
1. Test automation (qa-engineering)
2. Pipeline config (devops)
3. Deploy strategy (vercel-deployment)
Works well with: nextjs-app-router, supabase-backend