Deploy Next.js + Supabase + Stripe Without Breaking Everything

Building a SaaS application locally feels great until you deploy it and everything breaks in spectacular ways. I've watched this stack fail at 2am on Black Friday, hit Supabase connection limits during a Product Hunt launch, and lose $12k in payments because webhooks were silently failing.

Here's what actually happens when you deploy Next.js + Supabase + Stripe to production, and the fixes that work when you're getting paged at 3am.

The Production Stack Components

Next.js 15 is solid until you deploy and realize the App Router caching aggressively caches things you don't want cached. Like user authentication state. Or API responses that should be dynamic. The caching works great locally but breaks in production because of CDN interactions you didn't expect.

Pro tip: Add export const dynamic = 'force-dynamic' to API routes that handle payments or user-specific data, or you'll spend hours debugging why users see each other's data.

Supabase works beautifully in development with unlimited local connections. Production? Welcome to connection limit hell. Supabase Pro gives you 60 connections and each Next.js serverless function grabs a new one. Do the math - you'll hit the limit around 400-800 concurrent users. The fun part? Supabase doesn't warn you until you're already down.

I learned this the hard way when our signup page went viral and Supabase started returning FATAL: remaining connection slots are reserved for non-replication superuser connections. The fix: enable connection pooling and prepare to upgrade plans sooner than expected.

Stripe webhooks are reliable... until they're not. Webhooks will randomly fail during high traffic, timeout because Vercel functions are slow, or get blocked by your firewall. The worst part? They fail silently.

You won't know payments are failing until customers email asking why their subscription isn't working. Always log webhook failures and set up alerts. And yes, implement idempotency - I've seen users charged 8 times for the same subscription because of webhook retries.

The Shit That Actually Breaks

Environment Variables Will Ruin Your Week: You'll accidentally use dev Stripe keys in production (this charges your card instead of test cards). Or forget to set NODE_ENV=production and wonder why Next.js is slow. Or mix up Supabase project URLs and users can see each other's data.

Copy this checklist and check it twice:

## Production environment must have:
NEXT_PUBLIC_SUPABASE_URL=your-prod-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-prod-service-role-key
STRIPE_SECRET_KEY=sk_live_...  # NOT sk_test_
STRIPE_WEBHOOK_SECRET=whsec_...

Connection Limits Hit During Success: Nothing kills your viral moment like hitting database connection limits. Supabase gives you 60 connections on Pro, but one Next.js API route can use 3-5 connections simultaneously. The math sucks:

• 20 users hitting your API = potential for 100+ connections
• Connection pool exhausted = your app dies while you frantically Google solutions
• Users see "Database unavailable" = they bounce forever

Enable connection pooling and monitor connection usage in the Supabase dashboard obsessively.

Webhooks Timeout and Lose Money: Stripe gives your webhook endpoint 20-30 seconds to respond (not 10 like I thought). Vercel functions timeout after 10 seconds on Hobby tier. You do the math.

Lost webhook = lost subscription update = angry customer = refund requests. Upgrade to Pro for 60-second timeouts or optimize your webhook processing.

Production-Ready Architecture Patterns

Don't dump everything in one API route: Split your routes by function - auth goes in /api/auth/*, payments in /api/payments/*, subscription management in /api/subscriptions/*, and webhooks get their own /api/webhooks/* space. Makes debugging way less painful when something breaks. I've spent hours tracking down payment issues buried in a 500-line catch-all API route.

Index your damn database or it'll be slow as hell: Your Supabase queries will timeout without proper indexes. I watched a startup's signup flow take 45 seconds because they didn't index user_id on their profiles table. Composite indexes on columns you query together (like user_id, created_at), partial indexes for status filtering (WHERE status = 'active'), and database functions for complex logic that would otherwise require 5 API calls.

Real-time updates are great until they break: Supabase's real-time features work well for live subscription updates and payment confirmations, but you need fallback logic when WebSocket connections drop. I've seen payment confirmations lost because developers assumed real-time would always work. Set up proper channel management, presence tracking, and always have a polling fallback for critical updates.

Set up automated deployments or enjoy fixing broken production every Friday

Vercel's Git integration automatically deploys when you push to main, which is great until you push broken code at 4:59 PM on Friday. Use preview deployments to test features in a production-like environment, set up database migration strategies that won't destroy your data, and have rollback capabilities ready because you WILL need them.

Test the critical path or users will find your bugs: Test Stripe webhook handling with actual events, verify your Supabase RLS policies don't leak data between users, and test Next.js API routes under error conditions. I've seen apps go live where sign-up worked but payment confirmation emails never sent because webhook testing was "on the TODO list."

Monitor everything or you'll find out from angry users: Vercel Analytics shows you basic performance, Supabase logs show database issues, and Stripe Dashboard tracks payments. But you need Sentry for error tracking and custom metrics for critical flows. Set up alerts that wake you up at 3am - better than waking up to support tickets.

Get this foundation right and you might actually sleep through the night after deployment. Ignore it and you'll be debugging payment failures while your users are trying to give you money.

Everything works great on localhost. Your tests pass, your demo looks slick, and you're ready to launch. Then you deploy to production and discover all the ways the real world breaks your assumptions. Here's what actually happens when you deploy this stack and how to fix it before users notice.

Next.js 15 Production: Where Vercel Actually Works (Surprisingly)

Vercel is surprisingly the least painful way to deploy Next.js: Vercel - and trust me, I've tried them all. Automatic optimization that actually works, edge caching that doesn't randomly break your auth, and serverless functions that scale without you babysitting servers. You need proper build settings though: pin your Node.js version (because Vercel will upgrade without asking and break your build), optimize your build commands, and configure output settings so your functions don't timeout.

## vercel.json production configuration
{
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm ci",
  "framework": "nextjs",
  "functions": {
    "app/api/webhooks/stripe/route.ts": {
      "maxDuration": 30
    }
  }
}

Environment variables will destroy your weekend: You need separate values for dev, staging, and production or you'll charge your own credit card in testing (been there). Next.js environment variables in Vercel's dashboard need proper prefixes and you need to double-check which keys are client-safe vs server-only.

Double-check these critical variables:

• NEXT_PUBLIC_SUPABASE_URL - Your production Supabase project URL (NOT your dev project)
• SUPABASE_SERVICE_ROLE_KEY - Server-side only, never expose to frontend
• STRIPE_SECRET_KEY - Production key starts with sk_live_, NOT sk_test_
• STRIPE_WEBHOOK_SECRET - Different secret for production webhooks
• DATABASE_URL - Direct connection for migrations (not the pooled URL)
• NODE_ENV=production - Actually enables optimizations

Performance optimization or your app will be slow: Enable image optimization because unoptimized images kill mobile performance, use static page generation for marketing pages that don't change, and run bundle analysis to find the bloated dependencies you forgot about. Next.js 15's Turbopack speeds up dev builds but needs extra config for production - don't assume it just works.

Supabase Production: Security That Actually Protects Your Data

Set up proper project security or get hacked: Production Supabase needs organizations for team access (don't share personal accounts), strong database passwords that aren't "password123", and API key management where you actually understand the difference between anon keys (frontend) and service role keys (backend only).

Row Level Security will save your ass from data breaches: RLS policies are your last line of defense when some developer exposes the service role key. Test your policies thoroughly - I've seen RLS that looked secure but had logic bugs that leaked data between users.

-- Example production RLS policy
CREATE POLICY "Users can only access own data" ON user_profiles
FOR ALL USING (auth.uid() = user_id);

-- Performance-optimized policy with proper indexing
CREATE INDEX idx_user_profiles_user_id ON user_profiles(user_id);

Connection pooling prevents the 3am pages when your app goes viral: Enable connection pooling in Supabase settings immediately - don't wait until you hit the 60 connection limit and your signup flow dies. You might also need client-side pooling and connection monitoring because 60 connections disappear faster than you think.

Database migrations will break in production if you don't test them: Use migration strategies that don't destroy your data. The Supabase CLI works great in development but production migrations need staging environment testing and rollback plans. Never run migrations during peak hours - I've seen 5-second migrations take 30 minutes on production data.

Stripe Production: Where Money Actually Changes Hands

Secure your webhooks or lose money to fraudsters: Production Stripe webhooks handle real money, so verify every request signature using Stripe's webhook verification. Add rate limiting (people will try to abuse your endpoints), log everything (you'll need it for debugging), and return proper error responses (Stripe's retry logic depends on it).

// Production webhook handler with proper security
export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get('stripe-signature');
  
  let event: Stripe.Event;
  
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature!,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error('Webhook signature verification failed:', err);
    return new Response('Webhook signature verification failed', { 
      status: 400 
    });
  }
  
  // Process event with idempotency protection
  return await processWebhookEvent(event);
}

Handle payment failures or users will get pissed: Production payments fail for card declines, network timeouts, and API rate limits. Implement retry logic with exponential backoff (don't hammer Stripe's API), show user-friendly error messages (not raw API errors), and log everything for debugging failed transactions.

Subscription management is harder than it looks: Handle all subscription states properly, set up dunning management for failed payments using subscription webhooks, and handle proration when users change plans mid-cycle. Log every state transition - you'll need this data when users complain about billing.

Monitor Everything or Learn About Problems From Angry Users

Track performance metrics or find out your app sucks from angry user emails: Monitor Core Web Vitals, API response times, and error rates. Vercel Analytics shows you the basics, but you'll need DataDog or Sentry when shit really hits the fan. Set up alerts for when things break - you want to know before users start complaining.

Watch your database health obsessively: Supabase monitoring shows connection counts, slow queries, and storage usage. Alert on connection pool exhaustion (you'll hit 60 faster than expected), slow query detection (bad indexes kill performance), and storage limits (running out of space is embarrassing).

Payment alerts are critical - money problems wake people up: Get immediate alerts for failed webhook processing, subscription cancellations, and payment failure spikes. Stripe Dashboard alerts are basic - integrate with Slack or PagerDuty so payment issues wake up the right person at 3am.

Security: Don't Let Hackers Steal Your Users' Money

Protect your API keys or get pwned: Never put secret keys in client-side code or commit them to git (check your commit history right now). Use Vercel environment variables for secure storage, rotate API keys regularly, and monitor for accidental key exposure in your codebase.

Content Security Policy prevents XSS attacks: Set up CSP headers to block malicious scripts, especially critical for payment apps. Allow legitimate third-party scripts (Stripe.js) while blocking everything else - attackers love injecting payment skimmers into unprotected apps.

HTTPS everywhere or payments will fail: All production traffic needs HTTPS - Stripe requires it for payments. Vercel handles SSL automatically, but custom domains need proper certificate configuration and monitoring for expiration. Don't be the dev who brings down production because the SSL cert expired.

Deploy this stack right and you might actually make money without getting hacked. Mess it up and you'll be explaining to customers why their payment data got stolen.