Supabase + Next.js + Stripe Integration: Technical Reference

Architecture Overview

Stack Components:

• Supabase: Authentication, database with Row Level Security (RLS)
• Next.js App Router: Server-side rendering with middleware
• Stripe: Payment processing, billing, customer management

Implementation Time: 1-2 weeks (actual), not 1 week (estimated)
Alternative Comparison: Custom auth takes 2-3 months with security vulnerabilities

Critical Configuration Requirements

Environment Variables Setup

# Supabase - Dashboard keys required
NEXT_PUBLIC_SUPABASE_URL=https://abcdefg.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

# Stripe - Test then production keys
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# App URL - Exact match required
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Critical Configuration Failures:

• Trailing slash in SITE_URL breaks OAuth redirects (3+ hours debugging)
• Missing NEXT_PUBLIC_ prefix makes client variables undefined
• Wrong SITE_URL causes CORS blocks everything

Node.js Version Requirements

• Use: Node.js 18.17+
• Avoid: 18.2.0-18.4.0 (OpenSSL bug causes crypto errors)

Database Schema Implementation

Core Profile Table Structure

CREATE TABLE public.profiles (
  id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  full_name TEXT,
  avatar_url TEXT,
  stripe_customer_id TEXT UNIQUE,
  subscription_status TEXT DEFAULT 'inactive',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
  PRIMARY KEY (id)
);

-- Enable Row Level Security
ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;

-- User access policies
CREATE POLICY "Users can view own profile" ON public.profiles
  FOR SELECT USING (auth.uid() = id);
CREATE POLICY "Users can update own profile" ON public.profiles  
  FOR UPDATE USING (auth.uid() = id);

Auto-Profile Creation Trigger

CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS trigger AS $$
BEGIN
  INSERT INTO public.profiles (id, full_name, avatar_url)
  VALUES (new.id, new.raw_user_meta_data->>'full_name', new.raw_user_meta_data->>'avatar_url');
  RETURN new;
END;
$$ language plpgsql security definer;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();

Critical Race Condition: Profile creation trigger is async, causing 30% failure rate in Stripe customer creation without retry logic.

Authentication Implementation

Two-Client Architecture (Required)

Server Client (lib/supabase/server.ts):

• Reads cookies server-side
• Used in server components and API routes
• Cannot write cookies (explodes with cryptic errors)

Browser Client (lib/supabase/client.ts):

• Handles real-time updates
• Used in client components
• Can modify cookies

Critical Failure: Mixing clients causes 3+ hours debugging where auth works on page load but dies on interaction.

Middleware Configuration

// middleware.ts - Runs on Edge Runtime (30-second timeout)
export async function middleware(request: NextRequest) {
  // Token refresh logic - fails silently when Supabase has issues
  const { data: { user } } = await supabase.auth.getUser()
  
  // Protected routes
  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/auth/signin', request.url))
  }
}

Production Failures:

• Edge Runtime times out after 30 seconds (undocumented)
• Tokens expire exactly every hour like clockwork
• Failed refresh kicks users to login mid-session
• Cookie handling breaks randomly

Stripe Integration Critical Points

Customer Creation with Race Condition Fix

export async function createStripeCustomer(userId: string, email: string, name?: string) {
  // Race condition retry logic - essential for production
  let profile = null
  let attempts = 0
  while (!profile && attempts < 5) {
    const { data } = await supabase
      .from('profiles')
      .select('stripe_customer_id')
      .eq('id', userId)
      .single()
    
    if (data) {
      profile = data
      break
    }
    
    await new Promise(resolve => setTimeout(resolve, 1000))
    attempts++
  }
  // Additional customer creation logic...
}

Without Retry Logic: 30%+ failure rate, users can't access paid features

Webhook Handler Requirements

// app/api/webhooks/stripe/route.ts
export async function POST(req: NextRequest) {
  const body = await req.text() // MUST be text(), not json()
  const signature = headers().get('stripe-signature')!
  
  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
  } catch (err) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }
  // Event handling logic...
}

Critical Webhook Failures:

• Using req.json() instead of req.text() breaks signature verification
• Responses taking 30+ seconds cause infinite Stripe retries
• Missing idempotency handling corrupts subscription states
• Out-of-order webhook delivery creates data inconsistencies

Performance Characteristics

Expected Performance Metrics

• Auth Speed: Usually fast, occasionally 500ms+ (connection pool issues)
• Cold Starts: 100-300ms Edge Runtime delay, up to 2+ seconds first deploy
• Stripe API: Reliable until traffic spikes, then 2+ seconds response time
• Database: Fast until 50k users, then connection limits hit

Scaling Breakpoints

• 50k users: Database connection pooling becomes critical
• High traffic: Webhook processing bottlenecks appear
• Geographic distribution: Supabase distance affects performance significantly

Security Model

Row Level Security (RLS)

Automatic Data Filtering: Database queries auto-filter by user ID from JWT token
Critical Requirements:

• Never use service role key client-side (bypasses ALL security)
• RLS policies only work when auth.uid() returns valid user
• Service role required for webhook operations

Production Security Checklist

• Webhook signature verification implemented
• RLS policies tested with multiple users
• Service role key never exposed to client
• HTTPS enforced in production
• OAuth redirect URLs configured exactly

Common Production Failures

Authentication Issues

Problem	Symptom	Root Cause	Fix
Random logouts	Users kicked mid-session	Token refresh logic broken	Implement proper refresh handling
"User undefined"	Auth state mismatches	Server/client hydration mismatch	Add loading states, handle gracefully
Social login redirects wrong	OAuth fails in production	Site URL configuration wrong	Match domain exactly, no trailing slash

Payment Processing Issues

Problem	Symptom	Root Cause	Fix
Subscription status wrong	Database doesn't match Stripe	Webhook processing failures	Add retry logic, handle duplicates
Customer creation fails	"User not found" errors	Race condition in profile creation	Implement retry with delays
Webhooks timeout	Infinite Stripe retries	Response takes >30 seconds	Optimize database operations

Database Issues

Problem	Symptom	Root Cause	Fix
Connection errors	"Too many connections"	Pool exhaustion under load	Enable connection pooling
RLS blocking queries	No data returned	Missing auth context	Check auth.uid() in policies
Slow auth responses	500ms+ response times	Complex RLS policies	Add indexes, simplify logic

Critical Warnings

Data Synchronization Reality

"Eventually Consistent" = "Your data is broken but might fix itself later"

• Webhooks arrive out of order randomly
• Stripe webhooks can be 6+ hours late without notification
• Race conditions between user signup and customer creation
• No atomic transactions across Supabase and Stripe

Development vs Production Differences

Always breaks differently in production:

• Webhook endpoints must be HTTPS (no local HTTP)
• Environment variables handled differently per platform
• CORS restrictions stricter in production
• Performance characteristics completely different

Vendor Lock-in Considerations

Trade-off Analysis:

• Benefits: PCI compliance handled, security patches automatic, 2FA/social login included
• Costs: Vendor dependency, limited customization, potential service outages
• Alternative Cost: 2-3 months custom implementation + ongoing security maintenance

Testing Strategy

Local Development Setup

# Stripe webhook forwarding - required for testing
stripe listen --forward-to localhost:3000/api/webhooks/stripe

Test Card Numbers

• 4242424242424242 - Successful payments
• 4000000000000002 - Declined transactions
• 4000000000003220 - 3D Secure authentication required

Production Testing Checklist

• User signup creates profile in database
• Stripe customer creation with retry logic works
• Webhooks update subscription status correctly
• Auth state persists across browser refresh
• Users cannot access other users' data (test this manually)
• Social login redirects to correct URLs
• Payment flow completes end-to-end

Resource Requirements

Time Investment

• Initial Implementation: 1-2 weeks (with experienced developer)
• Custom Alternative: 2-3 months (auth + payments from scratch)
• Ongoing Maintenance: Minimal (vendor-managed) vs. high (custom)

Expertise Requirements

• Next.js App Router patterns (server/client components)
• PostgreSQL RLS and trigger functions
• Stripe webhook handling and signature verification
• JWT token management and refresh logic

Financial Costs

• Supabase: Free tier, then usage-based pricing
• Stripe: 2.9% + 30¢ per transaction
• Alternative: Custom infrastructure + security audits + PCI compliance

Breaking Changes and Migrations

Next.js Updates

Risk Level: High - App Router patterns change frequently
Mitigation: Pin Next.js version, test updates in staging

Supabase Updates

Risk Level: Medium - Database migrations can be complex
Mitigation: Use Supabase CLI for migration management

Stripe API Changes

Risk Level: Low - Stripe maintains backward compatibility well
Mitigation: Use API versioning, test webhook changes

Support and Community Quality

Supabase

• Documentation: Excellent, regularly updated
• Community: Active Discord with core team participation
• Response Time: Usually within hours for critical issues

Stripe

• Documentation: Industry standard, comprehensive
• Community: Large developer community, official Discord
• Support: Premium support available, extensive API documentation

Next.js

• Documentation: Comprehensive but assumes prior knowledge
• Community: Large GitHub discussions, Stack Overflow presence
• Updates: Frequent, sometimes breaking changes

Decision Matrix: When This Stack Makes Sense

Use This Stack When:

• Building standard SaaS application with subscriptions
• Need to ship quickly (weeks, not months)
• Team lacks deep auth/payment security expertise
• Require PCI compliance without internal audits
• Need social logins and 2FA without custom implementation

Consider Alternatives When:

• Require complex custom billing logic
• Need complete control over user data
• Have strict data residency requirements
• Building non-standard authentication flows
• Have dedicated security/infrastructure team

Success Metrics

• Implementation Speed: 1-2 weeks vs. 2-3 months custom
• Security Posture: PCI compliant out-of-box
• Maintenance Overhead: Minimal vs. ongoing custom maintenance
• Feature Completeness: Full auth + payment flows included