Deploying to Vercel: A Real Production Checklist

I have watched projects break in production that worked perfectly in development. Always the same culprits. Missing environment variables. Node.js version mismatch. Bundle size over limits. API routes that work on localhost timing out under Vercel's serverless function limits.

Vercel is genuinely excellent deployment infrastructure. These issues are not Vercel's fault. They are the predictable consequences of not knowing the checklist.

This is the checklist. Follow it and your deployments will work the first time.

Before You Touch the Vercel Dashboard

Most deployment failures are caught before you deploy if you run the right commands locally.

# Run the exact build that Vercel will run
npm run build

# If this fails locally, it will fail on Vercel
# Fix all build errors before touching the dashboard

# Check bundle sizes (important for performance)
npx @next/bundle-analyzer  # Add to package.json first

# Verify type safety
npx tsc --noEmit

# Run your full test suite
npm run test

Never push to production without a clean local build. This takes 2 minutes. The alternative is debugging a broken deployment in production, which takes much longer.

Environment Variables: The Biggest Source of Production Failures

Environment variable issues cause more production failures than anything else. Here is the complete system.

Organization

# .env.example (committed to version control)
# Copy this to .env.local and fill in values
# NEVER commit .env.local or .env.production

# App
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_APP_NAME=

# Database
CONVEX_DEPLOYMENT=
NEXT_PUBLIC_CONVEX_URL=

# Auth
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding

# Payments
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

# AI
ANTHROPIC_API_KEY=

# Email
RESEND_API_KEY=

The NEXT_PUBLIC Prefix Rule

Variables without NEXT_PUBLIC_ prefix are server-side only. Variables with the prefix are bundled into the client.

Common mistake: putting secret keys in NEXT_PUBLIC_ variables. They end up in the browser bundle. Anyone can read them. Stripe secret keys, Anthropic API keys, database credentials. Never NEXT_PUBLIC.

Common mistake #2: forgetting to add NEXT_PUBLIC_ to variables that client components need. They silently become undefined on the client. Add runtime validation:

// lib/env.ts
function getEnvVar(name: string, required = true): string {
  const value = process.env[name];
  if (required && !value) {
    throw new Error(
      `Missing required environment variable: ${name}\n` +
      `Check your .env.local file and Vercel environment variable settings.`
    );
  }
  return value ?? "";
}

export const env = {
  // Server-side only
  stripeSecretKey: getEnvVar("STRIPE_SECRET_KEY"),
  anthropicApiKey: getEnvVar("ANTHROPIC_API_KEY"),
  clerkSecretKey: getEnvVar("CLERK_SECRET_KEY"),

  // Client-safe
  appUrl: getEnvVar("NEXT_PUBLIC_APP_URL"),
  stripePublishableKey: getEnvVar("NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY"),
  convexUrl: getEnvVar("NEXT_PUBLIC_CONVEX_URL"),
} as const;

This fails fast and with a clear error message instead of a cryptic runtime failure.

Vercel Project Configuration

After connecting your repository:

Framework Settings

# Vercel usually detects these, but verify:
Framework Preset: Next.js
Root Directory: ./  (or the directory if it's a monorepo)
Build Command: npm run build  (or your actual build command)
Output Directory: .next  (Next.js default)
Install Command: npm install  (or yarn/pnpm/bun equivalent)
Node.js Version: 20.x  (match your local version)

Adding Environment Variables

In Vercel Dashboard > Project > Settings > Environment Variables:

1. Add each variable from your .env.example
2. Set the appropriate environment scope:
   • Production: your live site
   • Preview: pull request deploys
   • Development: vercel dev (rarely needed)
3. Be careful with values that differ between environments (like webhook URLs)

Critical Production-Only Variables

Some variables must be different in production:

# Development
NEXT_PUBLIC_APP_URL=http://localhost:3000
STRIPE_WEBHOOK_SECRET=whsec_local_from_stripe_cli

# Production
NEXT_PUBLIC_APP_URL=https://yourdomain.com
STRIPE_WEBHOOK_SECRET=whsec_live_from_stripe_dashboard

Vercel lets you set different values per environment. Use it.

Custom Domain Setup

For a custom domain at your registrar (GoDaddy, Namecheap, Cloudflare, etc.):

Option A: Vercel nameservers (easiest) Move your domain's nameservers to Vercel. Vercel manages all DNS.

Option B: CNAME record (most common)

Option C: A record for apex domain

For most setups, redirect the apex domain (yourdomain.com) to www.yourdomain.com. Vercel handles this automatically if you add both.

SSL is automatic on Vercel. It provisions certificates via Let's Encrypt within minutes of domain verification.

Webhook URLs in Production

This breaks everyone once. Different services need different webhook URLs:

# Stripe webhook
Stripe Dashboard > Developers > Webhooks > Add endpoint
Endpoint URL: https://yourdomain.com/api/stripe/webhook

# After creating, copy the webhook signing secret
# Add to Vercel as STRIPE_WEBHOOK_SECRET

# The local Stripe CLI secret is DIFFERENT from the production secret
# They are NOT interchangeable

If you forget to update the webhook URL, events will silently fail in production. Subscriptions won't update. Payments will process but your database won't know about them.

Serverless Function Limits

Next.js API routes run as Vercel serverless functions. They have limits:

The 10-second limit on Hobby kills many AI applications. AI API calls often take 5-15 seconds. A 10-second serverless limit means your AI routes fail in production.

// app/api/ai-analysis/route.ts
export const maxDuration = 60; // Only works on Pro plan

export async function POST(req: Request) {
  // This can now run for up to 60 seconds
  const result = await longRunningAiOperation();
  return Response.json(result);
}

For operations that might exceed even 60 seconds, move them to background jobs. Convex Actions and Trigger.dev are both good options.

The Pre-Deploy Checklist

Run through this before every production deploy:

## Environment
- [ ] All .env.example variables are set in Vercel for Production
- [ ] NEXT_PUBLIC_APP_URL points to production domain
- [ ] Stripe webhook URL is updated to production endpoint
- [ ] Stripe webhook secret matches the production webhook

## Build
- [ ] npm run build succeeds locally
- [ ] npx tsc --noEmit passes
- [ ] No type errors
- [ ] All tests pass

## Functionality
- [ ] Auth flow works on preview URL before switching to production
- [ ] Payment flow works in test mode on preview URL
- [ ] Critical user paths tested manually

## Performance
- [ ] Lighthouse score acceptable on preview URL
- [ ] No massive bundle size regressions
- [ ] Core Web Vitals in green range

Rollback When Things Go Wrong

Vercel makes rollback easy:

# Via CLI
vercel rollback  # Rolls back to previous deployment

# Via Dashboard
# Deployments tab > Click previous deployment > Promote to production

But rollback helps most when you have feature flags that let you disable a broken feature without a code rollback. Worth setting up even a simple feature flag system for major features.

Monitoring Your Deployment

After going live:

# Check your deployment
vercel logs --prod  # Stream production logs

# Or in dashboard:
# Project > Deployments > Select deployment > Functions tab
# Shows function invocations, errors, duration

Set up Sentry or similar for error tracking. Vercel logs are good for debugging, but you need alerting for errors you don't know to look for.

FAQ

Q: How do you deploy to Vercel?

Deploy to Vercel by connecting your GitHub repository, configuring environment variables, and pushing to your main branch. Vercel automatically builds, tests, and deploys your application. For AI applications, configure environment variables for API keys and set up edge functions for AI routes.

Q: What is the Vercel deployment checklist?

Before deploying: verify all environment variables are set, ensure build succeeds locally, check TypeScript types pass, run the test suite, verify API routes work, test responsive design, check Core Web Vitals, configure custom domain, and set up monitoring. AI agents can automate most of this checklist.

Q: How do you handle environment variables on Vercel?

Store environment variables in Vercel's dashboard under Project Settings, use .env.local for local development, never commit secrets to git, use Vercel's encryption for sensitive values, and separate variables by environment (development, preview, production). AI API keys should always be server-side only.

Sources

• Vercel Documentation (Official)
• Next.js Deployment Guide
• Vercel Serverless Function Limits

Further Reading

• How I Built a SaaS in 19 Days with AI
• Convex + AI: Build Real-Time Backend in Hours
• Stripe with AI: Build a Complete Billing System Fast
• Monitoring AI Agents in Production
• Deployment Automation with AI Agents