Building a SaaS That Actually Scales: Next.js 15 + Supabase + Stripe

I've been building SaaS apps for 8 years and I've seen some shit. Angular died while I was mid-project. React hooks broke half my components when they launched. I've had databases crash at 2am more times than my liver can handle. This stack - Next.js 15, Supabase, and Stripe - still pisses me off sometimes, but it's the first combo that doesn't make me want to set my laptop on fire.

The Stack That Sucks Less Than Everything Else

Let me be clear: there's no perfect stack. Every technology choice is a trade-off between pain points. But after building 12 SaaS apps and watching most of them die from technical debt or feature velocity problems, this combination of Next.js 15 + Supabase + Stripe is the first one that doesn't make me actively hate my job.

Next.js 15: Less Broken Than Before

Next.js 15 finally unfucked the caching disaster that made versions 13-14 completely unusable. I'm talking about users getting charged for subscriptions they cancelled, dashboards showing wrong data - the kind of bugs that make you question your career choices. They stopped caching GET Route Handlers by default. About fucking time.

The async Request APIs change will absolutely destroy your weekend if you're upgrading from 14. I spent 3 days fixing TypeScript errors that looked like this: Property 'get' does not exist on type 'Promise<ReadonlyRequestCookies>'. Every component that touched cookies() or headers() exploded. The codemod caught maybe 60% of the issues.

// This will break in Next.js 15
const cookieStore = cookies()

// This works 
const cookieStore = await cookies()

Turbopack finally works without crashing every 10 minutes. Our app with 200+ pages starts in 3 seconds instead of the 15-second webpack hell we lived with. Still slower than Vite, but I can actually develop without wanting to punch my monitor.

React 19 integration is a complete shitshow. Half the libraries you depend on will break. React Hook Form threw errors I'd never seen before. Radix Select components just... stopped working. Multiple popular libraries had compatibility issues. Spent a full day downgrading everything back to React 18 because deadlines don't care about bleeding edge features.

Supabase: PostgreSQL Without the DevOps Hell

Next.js handles your frontend and API routes, but every serious SaaS needs a real database that can handle complex queries, transactions, and actual scale. This is where most full-stack developers shit the bed.

Here's what nobody tells you: your full-stack developer who "knows PostgreSQL" will fuck up connection pooling, forget to add indexes, and write RLS policies that scan entire tables. I've seen it happen. Hell, I've done it. Supabase saves you from yourself until you're big enough to hire someone who actually knows databases.

The connection pool literally saved my business: Every morning at 9am PST, when West Coast users started logging in, I'd get the dreaded FATAL: too many connections for role "postgres" error. Users couldn't log in, payments couldn't process, and I'm frantically googling "postgresql connection limit" while my phone buzzes with angry support tickets. Supabase's PgBouncer setup fixed this automatically.

Row Level Security is a lifesaver: Instead of writing tenant isolation logic in every single query, RLS policies handle it at the database level. One wrong WHERE clause can expose customer data - I've seen it happen. RLS prevents that entire class of bugs.

But here's the gotcha that cost me 3 days of debugging: RLS policies can absolutely murder performance. Had this innocent-looking policy that was doing full table scans on 2.3 million rows. Every. Single. Query. Users were waiting 8 seconds for their dashboard to load. I learned to worship EXPLAIN ANALYZE after that shitshow.

The $25/month Pro plan is actually reasonable. You get:

• 8GB storage (enough for most MVPs)
• 100K monthly active users
• Built-in auth that doesn't suck
• Real-time subscriptions that work

Try building this yourself and you're looking at $300-500/month in AWS bills plus 3 weeks of your time setting up connection pooling, auth flows, and database migrations. I know because I tried it once. Spent more on therapy than I saved on hosting.

The gotchas that will bite you: Connection limits start choking at around 800 active users, not 1,000. That 60-connection pool gets exhausted fast when Next.js serverless functions each grab their own connection. And of course their dashboard went down during my first traffic spike - Murphy's Law in action.

Stripe: The Only Payment Processor That Doesn't Hate Developers

Database and frontend sorted, now you need to collect money. This is where shit gets real because payment processing touches legal compliance, international tax law, and financial regulations that can literally shut down your business if you fuck them up.

I've integrated PayPal (absolute nightmare), Braintree (they deprecated half their APIs mid-project), Square (works great if you only serve the US), and some fly-by-night processors that shall remain nameless. Stripe is the only one where I didn't want to quit programming halfway through.

Webhooks that don't make you cry: Stripe webhooks actually retry when they fail, use proper signatures so you know they're legit, and their dashboard shows you exactly what happened when shit breaks. PayPal webhooks? I once spent 6 hours debugging why they were sending duplicate payment_completed events. Turns out it was a "known issue" buried in some forum post.

The 2.9% + $0.30 fee hurts: At $10K monthly revenue, you're paying $320/month in fees. But I tried rolling my own payment processing once with a cheaper processor. Spent 4 months dealing with failed transactions, declined cards that should have worked, and customers who couldn't understand why their payment kept bouncing. Never. Again.

Subscription states are a minefield: active, past_due, canceled, incomplete, trialing, unpaid, incomplete_expired - 7 states because subscription billing is genuinely fucked up in ways you haven't thought of. I tried to "simplify" this once. Ended up with customers who thought they were subscribed but weren't getting charged. Financial reconciliation was a nightmare.

Webhook replay attacks are real: Store the processed event IDs in your database or you'll charge someone twice. Happened to me on a Sunday morning - customer's card got charged twice for their monthly subscription. Spent my entire Sunday morning on the phone with Stripe support and writing refund logic. The customer was... not happy.

Where This Stack Will Fuck You Over

Look, I just spent 600 words telling you why this stack is great. But I'm not trying to sell you anything, and every technology choice has downsides that'll bite you in the ass at the worst possible moment. Here's what to expect when the honeymoon period ends.

Database Performance Hell

Supabase is great until you hit their limits. Hit around 8,500 active users and shit starts breaking:

• Queries timing out during lunch hour traffic
• Connection pool exhausted errors during peak usage
• Supabase dashboard takes 30 seconds to load your tables

The read replica costs $100/month minimum. I thought I was being smart by waiting until I "needed" it. Woke up to a crashed database and 2 hours of downtime because I was too cheap to spend an extra hundred bucks.

Next.js Build Times

Complex SaaS apps take forever to build. Ours hits 12 minutes on Vercel's free tier. Every git push becomes a coffee break. The Pro plan drops it to 4 minutes for $20/month per developer. Worth every penny for developer sanity.

Stripe's International Nightmare

Stripe works in 40+ countries but tax compliance will make you want to die. EU VAT rates change by country. Canadian GST has different rules for digital services. US state taxes... just don't get me started on that clusterfuck. Stripe collects the money, but calculating and filing taxes? That's all you, buddy.

"Adaptive pricing" sounds fancy but it's just Stripe A/B testing how much they can charge your customers. Saw conversion rates drop 18% in Germany when they decided to test higher prices without telling me. Thanks, Stripe.

The Reality Check

This stack stops being cute around 40,000 users. After that, you're looking at some expensive decisions:

• Database migration: AWS RDS will cost 3x more but actually scales
• Caching layer: Redis becomes mandatory, not optional
• Real monitoring: Supabase's dashboard won't cut it when you're losing $1000/hour during outages

But here's the thing - if you're hitting these limits, you're making real money. This stack's job is to get you from zero to profitable without you having to become a database expert. Mission accomplished.

Too many developers start with Kubernetes and microservices on day one. This stack is the opposite - ship fast, figure out scaling when you actually have users who pay you money. Most startups die from lack of customers, not from technical debt.

Six months ago, my SaaS hit 4,847 users on a Tuesday morning and everything exploded. Database threw FATAL: remaining connection slots are reserved for non-replication superuser connections, Stripe webhooks timed out with 500 errors, and Next.js builds were taking 23 fucking minutes.

This is the part most tutorials skip: what actually breaks when you go from 100 test users to thousands of real people using your app 24/7. Here's what I learned when my cute little side project turned into actual responsibility.

Database Scaling Reality

Connection Pool Drama

Supabase gives you 60 connections on Pro. Sounds like plenty until you watch the connection count hit 59, 60, then boom - everything breaks. Next.js serverless functions don't reuse connections like a normal server would. Every API call grabs a new connection, uses it for 200ms, then holds onto it like a clingy ex.

The fix that saved my weekend:

// Don't do this - creates connections everywhere
const supabase = createClient(url, key)

// Do this - singleton pattern
let supabaseInstance: SupabaseClient | null = null

export function getSupabase() {
  if (!supabaseInstance) {
    supabaseInstance = createClient(
      process.env.NEXT_PUBLIC_SUPABASE_URL!,
      process.env.SUPABASE_SERVICE_ROLE_KEY!
    )
  }
  return supabaseInstance
}

Reality check: Even with this fix, you'll still hit the wall around 1,800 concurrent users. The read replica costs $100/month. I held off for 2 months because "it's just a hundred bucks." Cost me way more than that in lost sleep and angry customer emails.

RLS Policies That Kill Performance

Row Level Security is great for security, terrible for performance if you're not careful. We had this seemingly innocent policy:

CREATE POLICY tenant_isolation ON user_data 
FOR ALL USING (
  tenant_id = (
    SELECT tenant_id FROM user_profiles 
    WHERE id = auth.uid()
  )
);

This innocent looking subquery was running on every fucking row. Table had 127,000 rows. Each dashboard load was doing a full table scan 127,000 times. Queries were taking 8.3 seconds and users were bouncing. The fix:

CREATE POLICY tenant_isolation ON user_data 
FOR ALL USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

Set the tenant_id in the session instead of querying for it every time.

Query Performance Nightmares

Index your shit or die: Our biggest performance killer was missing indexes on foreign keys. Coming from MySQL, I assumed PostgreSQL would handle this automatically. It doesn't. PostgreSQL leaves you to figure this out yourself, which is both a blessing and a curse.

-- These indexes dropped query time from 8 seconds to 80ms
CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id);
CREATE INDEX CONCURRENTLY idx_subscriptions_customer_id ON subscriptions(customer_id);
CREATE INDEX CONCURRENTLY idx_invoices_created_at ON invoices(created_at);
-- Pro tip: CONCURRENTLY means it won't lock your table during creation

OFFSET pagination will kill your app: Page 1-10 load fine. Page 500? Your users are waiting 12 seconds for a page of old orders they don't even care about. Cursor-based pagination saved my sanity:

// Slow for large offsets
const { data } = await supabase
  .from('orders')
  .select('*')
  .range(5000, 5049)

// Fast at any depth
const { data } = await supabase
  .from('orders')
  .select('*')
  .gt('id', lastId)
  .limit(50)

Stripe Integration Hell

Database problems sorted? Great. Now let's talk about the part that can literally cost you money: payment processing at scale. Stripe makes it look easy in their docs, but there's a difference between processing 10 test payments and handling thousands of real transactions with angry customers and actual money at stake.

Webhook Idempotency (Or How I Charged Mrs. Peterson Twice and Ruined My Tuesday)

Stripe will send the same webhook multiple times if your server is slow to respond. Mrs. Peterson got charged $49.99 twice for her monthly subscription because I didn't handle webhook idempotency. She was not happy. I was not happy. My Tuesday was fucked.

// app/api/webhooks/stripe/route.ts
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, webhookSecret)
  } catch (err) {
    return Response.json({ error: 'Invalid signature' }, { status: 400 })
  }
  
  // THIS IS CRITICAL: Check if we've already processed this event
  const existingEvent = await supabase
    .from('processed_webhooks')
    .select('id')
    .eq('stripe_event_id', event.id)
    .single()
    
  if (existingEvent.data) {
    return Response.json({ message: 'Event already processed' })
  }
  
  // Process the event
  await processWebhook(event)
  
  // Record that we processed it
  await supabase
    .from('processed_webhooks')
    .insert({ stripe_event_id: event.id, processed_at: new Date() })
    
  return Response.json({ received: true })
}

Subscription State Management Will Drive You Insane

Stripe has 7 subscription statuses and they're all important in ways that will surprise you. incomplete means the initial payment failed - give them another chance. past_due means payment failed but they still have access (grace period). canceled means they cancelled but might still have access until the period ends. unpaid means you've given up and they're dead to you.

The state machine from hell:

• incomplete: Initial payment failed, give them another chance
• past_due: Payment failed, but subscription is still active (grace period)
• canceled: They cancelled, but might still have access until period_end
• unpaid: Multiple payment failures, subscription is effectively dead

Spent 2 weeks building a state machine to handle all these transitions. Initially tried to "simplify" it to just active and canceled. Big mistake. Ended up with customers who thought they were subscribed but weren't getting billed, and customers who were getting billed for subscriptions they thought they'd cancelled. Financial reconciliation was a nightmare.

Testing Webhooks Locally is Painful

The Stripe CLI helps, but it's still a pain in the ass:

## Install the CLI
brew install stripe/stripe-cli/stripe

## Login (opens browser)
stripe login

## Forward webhooks to your local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

Pro tip: Use ngrok instead. The Stripe CLI connection drops every 87 minutes like clockwork. Right in the middle of testing, always.

Next.js Production Gotchas

Payments working, database scaling, users happy. But there's one more thing that'll slowly drive you insane: Next.js itself. The framework that's supposed to make you productive has its own set of production landmines that nobody mentions in the "Getting Started" tutorials.

Build Times That Kill Developer Productivity

Our app takes 11 minutes to build on Vercel's free tier. Every git push becomes a bathroom break, coffee run, and existential crisis about career choices. Here's what helped:

1. Upgrade to Vercel Pro: $20/month per developer but builds drop to 4 minutes. Worth it.
2. Docker build caching: Cache node_modules between builds instead of re-downloading 400MB of dependencies every time
3. Split your monolith: Moved the admin dashboard to a separate Next.js app. Customer app builds in 6 minutes, admin builds in 2.

Server Actions vs API Routes: Choose Wisely

Server Actions work great for forms, but they're weird for everything else. I tried using them for API endpoints and it was like using a screwdriver as a hammer:

Use Server Actions for:

• Form submissions
• User-initiated actions (delete account, update profile)
• Things that redirect after completion

Use API Routes for:

• Webhooks (they need to return JSON)
• Third-party integrations
• Mobile app APIs
• Anything that needs custom headers

Middleware Performance Traps

Next.js middleware runs on every fucking request, including your CSS files, images, and favicon. I had middleware that checked subscription status by hitting the database. Every image load was doing a database lookup. Added 230ms to every page load.

// Bad - runs on every request including static assets
export function middleware(request: NextRequest) {
  const subscription = await checkSubscriptionStatus(userId)
  // This was hitting the database for favicon.ico requests
}

// Good - only runs on API routes and pages
export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|api/webhooks).*)
  ]
}

The $3,247/Month Bill That Made Me Spit Out My Coffee

Here's what this "cheap" stack actually cost me last month at $68K revenue:

• Vercel Pro (3 devs): $67/month (overages for build minutes)
• Supabase Pro + Read Replica: $143/month (went over storage)
• Stripe fees: $2,030/month (2.9% + $0.30 per transaction hurts)
• Monitoring (Sentry, LogRocket): $240/month (needed higher tiers)
• Email service (Resend): $89/month (transactional emails add up)
• Redis cache (Upstash): $47/month (needed more memory)
• Misc SaaS tools: $631/month (analytics, support, backups)

Total: $3,247/month and that's just the direct costs. Doesn't include the 43 hours I spent last month debugging connection pool issues, webhook failures, and build problems.

The trade-off is worth it if you're optimizing for shipping fast over saving money. But let's not pretend this is "cheap" - you're trading money for time and sanity.

When to Abandon Ship

This stack hits a wall eventually. Start planning your exit when:

• 8,000+ concurrent users: Connection pooling becomes a daily fire drill
• $80K+ monthly revenue: Stripe fees start feeling like rent payments
• Team of 8+ engineers: Everyone's stepping on each other's deployments
• Enterprise deals: They want SOC2, single sign-on, and 99.99% uptime SLAs that will make you laugh/cry

By then you'll have enough revenue to hire senior engineers who know how to build real infrastructure. That's the point - this stack gets you to that problem, which is a good problem to have.