How to Build a SaaS With Next.js and Supabase

Building a production-ready SaaS application requires solving authentication, database management, real-time updates, file storage, and API development all before writing a single line of business logic. This infrastructure overhead can delay your product launch by weeks or months. The Next.js and Supabase combination eliminates this problem by providing a full-stack framework with built-in authentication, PostgreSQL database, real-time subscriptions, and edge functions out of the box.

This guide walks through building a complete SaaS application from project setup to deployment. You'll learn how to structure a Next.js app with Supabase, implement row-level security for multi-tenancy, handle subscription billing, and optimize for production performance. Unlike generic tutorials that skip the hard parts, this covers the specific architectural decisions that distinguish hobby projects from production SaaS applications.

We'll build a task management SaaS with team collaboration features, subscription tiers, and real-time updates to demonstrate these patterns in a realistic context.

Why Next.js and Supabase for SaaS

The technology stack you choose for a SaaS application determines your development velocity, hosting costs, and ability to scale. Next.js combined with Supabase addresses the three primary constraints most developers face: time to market, infrastructure complexity, and operational costs.

Next.js provides server-side rendering, API routes, and edge runtime capabilities in a single framework. This eliminates the need to maintain separate frontend and backend codebases. The App Router introduced in Next.js 13 enables React Server Components, which reduce JavaScript sent to the client and improve initial page load times by up to 40% compared to client-side rendering approaches.

Supabase replaces what would typically require four separate services: PostgreSQL for your database, Auth0 or Firebase for authentication, Pusher for real-time features, and S3 for file storage. Each of these services would require separate configuration, monitoring, and billing. Supabase consolidates all four into a single platform with a unified API.

From a cost perspective, this stack remains cost-effective as you scale. Supabase's free tier supports up to 500MB database and 50,000 monthly active users. Next.js deploys efficiently on Vercel's edge network with automatic scaling. A typical SaaS serving 1,000 paying customers can run for under $100/month on this stack, compared to $500+ on AWS with separate services for auth, database, and hosting.

Project Setup and Architecture

Proper project structure prevents technical debt that becomes expensive to refactor once you have users in production. The architecture outlined here separates concerns while maintaining the simplicity needed for rapid development.

Start by creating a new Next.js project with TypeScript. TypeScript is non-negotiable for SaaS development as it catches type-related bugs during development rather than in production.

npx create-next-app@latest saas-app --typescript --tailwind --app
cd saas-app
npm install @supabase/supabase-js @supabase/auth-helpers-nextjs

Your project structure should separate concerns into clear directories. Here's the recommended organization:

src/
├── app/                    # Next.js App Router pages
│   ├── (auth)/            # Auth-related pages (login, signup)
│   ├── (dashboard)/       # Protected dashboard pages
│   └── api/               # API routes
├── components/            # React components
│   ├── ui/               # Reusable UI components
│   ├── features/         # Feature-specific components
│   └── layouts/          # Layout components
├── lib/                   # Business logic
│   ├── supabase/         # Supabase client and utilities
│   ├── stripe/           # Payment processing
│   └── utils/            # Helper functions
└── types/                 # TypeScript type definitions

Create a Supabase client that works across server and client components. Next.js App Router requires different client initialization depending on the rendering context.

// lib/supabase/client.ts - For client components
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

// lib/supabase/server.ts - For server components
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export function createClient() {
  const cookieStore = cookies()

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value
        },
      },
    }
  )
}

Authentication and User Management

SaaS authentication requires more than just login and logout. You need email verification to prevent spam signups, password reset flows that don't compromise security, and session management that works across server and client components.

Supabase Auth handles these requirements with minimal configuration. Enable email authentication in your Supabase dashboard under Authentication settings. For production, configure your custom SMTP server to avoid Supabase's rate limits on their default email service.

// app/(auth)/login/page.tsx
'use client'

import { createClient } from '@/lib/supabase/client'
import { useState } from 'react'
import { useRouter } from 'next/navigation'

export default function Login() {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [loading, setLoading] = useState(false)
  const router = useRouter()
  const supabase = createClient()

  async function handleLogin(e: React.FormEvent) {
    e.preventDefault()
    setLoading(true)

    const { error } = await supabase.auth.signInWithPassword({
      email,
      password,
    })

    if (error) {
      alert(error.message)
    } else {
      router.push('/dashboard')
    }

    setLoading(false)
  }

  return (
    <form onSubmit={handleLogin}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Loading...' : 'Login'}
      </button>
    </form>
  )
}

For signup, implement email confirmation to verify user email addresses. This prevents fake account creation and improves deliverability for transactional emails.

// app/(auth)/signup/page.tsx
async function handleSignup(e: React.FormEvent) {
  e.preventDefault()
  setLoading(true)

  const { error } = await supabase.auth.signUp({
    email,
    password,
    options: {
      emailRedirectTo: `${window.location.origin}/auth/callback`,
    },
  })

  if (error) {
    alert(error.message)
  } else {
    alert('Check your email to confirm your account')
  }

  setLoading(false)
}

The authentication callback route handles the redirect after email confirmation. Create this route to exchange the auth code for a session:

// app/auth/callback/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const requestUrl = new URL(request.url)
  const code = requestUrl.searchParams.get('code')

  if (code) {
    const supabase = createClient()
    await supabase.auth.exchangeCodeForSession(code)
  }

  return NextResponse.redirect(new URL('/dashboard', request.url))
}

Database Schema and Multi-Tenancy

Your database schema must enforce data isolation between customers from day one. Retrofitting multi-tenancy into an existing schema after you have paying customers is risky and time-consuming. The pattern shown here uses row-level security to ensure users can only access data belonging to their organization.

Create the core tables in Supabase's SQL editor:

-- Organizations table
create table organizations (
  id uuid default gen_random_uuid() primary key,
  name text not null,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  subscription_tier text default 'free' not null,
  subscription_status text default 'active' not null
);

-- Organization members junction table
create table organization_members (
  id uuid default gen_random_uuid() primary key,
  organization_id uuid references organizations(id) on delete cascade not null,
  user_id uuid references auth.users(id) on delete cascade not null,
  role text default 'member' not null,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  unique(organization_id, user_id)
);

-- Tasks table
create table tasks (
  id uuid default gen_random_uuid() primary key,
  organization_id uuid references organizations(id) on delete cascade not null,
  title text not null,
  description text,
  status text default 'todo' not null,
  assigned_to uuid references auth.users(id) on delete set null,
  created_by uuid references auth.users(id) on delete set null not null,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  updated_at timestamp with time zone default timezone('utc'::text, now()) not null
);

Row-level security policies enforce multi-tenancy at the database level. This is more secure than application-level checks because it's impossible for a bug in your application code to leak data across organizations.

-- Enable RLS on all tables
alter table organizations enable row level security;
alter table organization_members enable row level security;
alter table tasks enable row level security;

-- Organizations: Users can only see organizations they're members of
create policy "Users can view their organizations"
  on organizations for select
  using (
    exists (
      select 1 from organization_members
      where organization_members.organization_id = organizations.id
      and organization_members.user_id = auth.uid()
    )
  );

-- Tasks: Users can view tasks in their organizations
create policy "Users can view organization tasks"
  on tasks for select
  using (
    exists (
      select 1 from organization_members
      where organization_members.organization_id = tasks.organization_id
      and organization_members.user_id = auth.uid()
    )
  );

-- Tasks: Users can create tasks in their organizations
create policy "Users can create tasks in their organizations"
  on tasks for insert
  with check (
    exists (
      select 1 from organization_members
      where organization_members.organization_id = tasks.organization_id
      and organization_members.user_id = auth.uid()
    )
  );

Building the Dashboard Interface

The dashboard is where users spend most of their time in your SaaS. It needs to load quickly, update in real-time, and work reliably across devices. Using Next.js Server Components for the initial render and client components for interactivity achieves this balance.

// app/(dashboard)/dashboard/page.tsx
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import TaskList from '@/components/features/TaskList'

export default async function Dashboard() {
  const supabase = createClient()

  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    redirect('/login')
  }

  // Fetch initial tasks server-side for fast initial render
  const { data: tasks } = await supabase
    .from('tasks')
    .select('*')
    .order('created_at', { ascending: false })

  return (
    <div>
      <h1>Dashboard</h1>
      <TaskList initialTasks={tasks || []} />
    </div>
  )
}

The TaskList component subscribes to real-time updates so users see changes instantly when team members create or update tasks:

// components/features/TaskList.tsx
'use client'

import { createClient } from '@/lib/supabase/client'
import { useEffect, useState } from 'react'
import type { Database } from '@/types/database'

type Task = Database['public']['Tables']['tasks']['Row']

export default function TaskList({ initialTasks }: { initialTasks: Task[] }) {
  const [tasks, setTasks] = useState(initialTasks)
  const supabase = createClient()

  useEffect(() => {
    const channel = supabase
      .channel('tasks')
      .on(
        'postgres_changes',
        { event: '*', schema: 'public', table: 'tasks' },
        (payload) => {
          if (payload.eventType === 'INSERT') {
            setTasks((current) => [payload.new as Task, ...current])
          } else if (payload.eventType === 'UPDATE') {
            setTasks((current) =>
              current.map((task) =>
                task.id === payload.new.id ? (payload.new as Task) : task
              )
            )
          } else if (payload.eventType === 'DELETE') {
            setTasks((current) =>
              current.filter((task) => task.id !== payload.old.id)
            )
          }
        }
      )
      .subscribe()

    return () => {
      supabase.removeChannel(channel)
    }
  }, [supabase])

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task.id}>{task.title}</li>
      ))}
    </ul>
  )
}

Implementing Subscription Billing

Subscription billing is what transforms your application from a demo into a business. The Stripe integration shown here handles subscription creation, plan changes, cancellations, and webhook processing for payment events.

Install Stripe dependencies:

npm install stripe @stripe/stripe-js

Create a Stripe instance for server-side operations:

// lib/stripe/server.ts
import Stripe from 'stripe'

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-11-20.acacia',
  typescript: true,
})

Create an API route to generate Stripe Checkout sessions. This handles the initial subscription creation:

// app/api/checkout/route.ts
import { createClient } from '@/lib/supabase/server'
import { stripe } from '@/lib/stripe/server'
import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const supabase = createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { priceId } = await request.json()

  const session = await stripe.checkout.sessions.create({
    customer_email: user.email,
    line_items: [{ price: priceId, quantity: 1 }],
    mode: 'subscription',
    success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/dashboard?success=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/pricing`,
    metadata: {
      user_id: user.id,
    },
  })

  return NextResponse.json({ sessionId: session.id })
}

Handle Stripe webhooks to update subscription status in your database. Webhooks are how Stripe notifies your application about subscription changes, payment failures, and cancellations:

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe/server'
import { createClient } from '@supabase/supabase-js'
import { NextResponse } from 'next/server'

const supabaseAdmin = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

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) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object
      const userId = session.metadata?.user_id

      // Update user's subscription status
      await supabaseAdmin
        .from('organizations')
        .update({
          subscription_tier: 'pro',
          subscription_status: 'active',
        })
        .eq('id', userId)
      break
    }

    case 'customer.subscription.deleted': {
      const subscription = event.data.object
      // Handle subscription cancellation
      break
    }
  }

  return NextResponse.json({ received: true })
}

Real-Time Features and Collaboration

Real-time updates transform single-player experiences into collaborative workspaces. Supabase's real-time engine uses PostgreSQL's replication system to broadcast database changes to connected clients with sub-second latency.

The real-time subscription shown in the TaskList component earlier demonstrates the basic pattern. For more complex scenarios like presence indicators showing which users are currently viewing a task, use Supabase's presence feature:

// components/features/TaskPresence.tsx
'use client'

import { createClient } from '@/lib/supabase/client'
import { useEffect, useState } from 'react'

export default function TaskPresence({ taskId }: { taskId: string }) {
  const [presences, setPresences] = useState([])
  const supabase = createClient()

  useEffect(() => {
    const channel = supabase.channel(`task:${taskId}`)

    channel
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState()
        setPresences(Object.values(state).flat())
      })
      .subscribe(async (status) => {
        if (status === 'SUBSCRIBED') {
          const { data: { user } } = await supabase.auth.getUser()
          if (user) {
            await channel.track({
              user_id: user.id,
              user_email: user.email,
            })
          }
        }
      })

    return () => {
      supabase.removeChannel(channel)
    }
  }, [taskId, supabase])

  return (
    <div>
      {presences.length > 0 && (
        <p>{presences.length} user(s) viewing this task</p>
      )}
    </div>
  )
}

For features requiring conflict resolution like simultaneous edits to the same task, implement optimistic updates with rollback on conflict. This provides instant feedback while handling edge cases gracefully.

File Storage and Media Management

SaaS applications frequently need file upload capabilities for user avatars, document attachments, or media assets. Supabase Storage provides S3-compatible object storage with the same row-level security policies as your database.

Create a storage bucket in your Supabase dashboard and configure access policies:

-- Create bucket (via Supabase dashboard or SQL)
insert into storage.buckets (id, name, public)
values ('attachments', 'attachments', false);

-- Policy: Users can upload files to their organization's folder
create policy "Users can upload to organization folder"
on storage.objects for insert
with check (
  bucket_id = 'attachments' and
  (storage.foldername(name))[1] in (
    select organization_id::text from organization_members
    where user_id = auth.uid()
  )
);

Implement a file upload component with progress tracking:

// components/features/FileUpload.tsx
'use client'

import { createClient } from '@/lib/supabase/client'
import { useState } from 'react'

export default function FileUpload({ organizationId }: { organizationId: string }) {
  const [uploading, setUploading] = useState(false)
  const [progress, setProgress] = useState(0)
  const supabase = createClient()

  async function uploadFile(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0]
    if (!file) return

    setUploading(true)
    const filePath = `${organizationId}/${Date.now()}-${file.name}`

    const { error } = await supabase.storage
      .from('attachments')
      .upload(filePath, file, {
        onUploadProgress: (progress) => {
          setProgress((progress.loaded / progress.total) * 100)
        },
      })

    if (error) {
      alert(error.message)
    } else {
      alert('File uploaded successfully')
    }

    setUploading(false)
    setProgress(0)
  }

  return (
    <div>
      <input type="file" onChange={uploadFile} disabled={uploading} />
      {uploading && <progress value={progress} max="100" />}
    </div>
  )
}

API Routes and Edge Functions

Not all logic belongs in client components or server components. Long-running tasks, third-party API integrations, and scheduled jobs require dedicated API routes or edge functions.

Use Next.js API routes for synchronous operations that respond to user actions:

// app/api/tasks/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const supabase = createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { title, description, organizationId } = await request.json()

  const { data, error } = await supabase
    .from('tasks')
    .insert({
      title,
      description,
      organization_id: organizationId,
      created_by: user.id,
    })
    .select()
    .single()

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 400 })
  }

  return NextResponse.json({ data })
}

For asynchronous operations like sending email notifications or processing webhooks, use Supabase Edge Functions. These run on Deno's edge runtime and can be triggered by database events:

// supabase/functions/send-task-notification/index.ts
import { serve } from 'https://deno.land/[email protected]/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { record } = await req.json()

  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  // Get assigned user's email
  const { data: user } = await supabase.auth.admin.getUserById(record.assigned_to)

  // Send email notification (using Resend, SendGrid, etc.)

  return new Response(JSON.stringify({ success: true }), {
    headers: { 'Content-Type': 'application/json' },
  })
})

Performance Optimization

Performance directly impacts conversion rates and user retention. A 100ms increase in page load time can decrease conversions by 1%. The optimizations shown here address the most common performance bottlenecks in Next.js and Supabase applications.

Enable Next.js Image optimization for user-uploaded images. This automatically serves images in modern formats like WebP and generates responsive sizes:

import Image from 'next/image'

<Image
  src={avatarUrl}
  alt="User avatar"
  width={40}
  height={40}
  className="rounded-full"
/>

Implement query result caching for data that doesn't change frequently. Organization settings, subscription tiers, and user profiles are good candidates:

// lib/supabase/queries.ts
import { createClient } from '@/lib/supabase/server'
import { unstable_cache } from 'next/cache'

export const getOrganization = unstable_cache(
  async (organizationId: string) => {
    const supabase = createClient()
    const { data } = await supabase
      .from('organizations')
      .select('*')
      .eq('id', organizationId)
      .single()
    return data
  },
  ['organization'],
  { revalidate: 3600 } // Cache for 1 hour
)

Use database indexes on frequently queried columns. Without proper indexes, queries slow down exponentially as your data grows:

-- Index on organization_id for faster task lookups
create index tasks_organization_id_idx on tasks(organization_id);

-- Index on user_id for faster membership checks
create index organization_members_user_id_idx on organization_members(user_id);

-- Composite index for common query patterns
create index tasks_org_status_idx on tasks(organization_id, status);

Security Best Practices

Security vulnerabilities in SaaS applications can destroy customer trust and create legal liability. The practices outlined here prevent the most common security issues in Next.js and Supabase applications.

Never trust client input. Always validate and sanitize data on the server before database operations:

// lib/validation.ts
import { z } from 'zod'

export const taskSchema = z.object({
  title: z.string().min(1).max(200),
  description: z.string().max(2000).optional(),
  organizationId: z.string().uuid(),
})

// In API route
const result = taskSchema.safeParse(await request.json())
if (!result.success) {
  return NextResponse.json({ error: result.error }, { status: 400 })
}

Implement rate limiting on API routes to prevent abuse. Without rate limiting, attackers can exhaust your database connections or API quotas:

// middleware.ts
import { Ratelimit } from '@upstash/ratelimit'
import { Redis } from '@upstash/redis'

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '10 s'),
})

export async function middleware(request: Request) {
  const ip = request.headers.get('x-forwarded-for') ?? 'anonymous'
  const { success } = await ratelimit.limit(ip)

  if (!success) {
    return new Response('Too Many Requests', { status: 429 })
  }
}

Enable Content Security Policy headers to prevent XSS attacks. Add this to your next.config.js:

const securityHeaders = [
  {
    key: 'Content-Security-Policy',
    value: "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"
  },
  {
    key: 'X-Frame-Options',
    value: 'DENY'
  },
  {
    key: 'X-Content-Type-Options',
    value: 'nosniff'
  },
]

module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: securityHeaders,
      },
    ]
  },
}

Deployment and DevOps

Your deployment strategy determines how quickly you can ship features and how reliably your application runs. The workflow shown here enables continuous deployment while maintaining production stability.

Deploy your Next.js application to Vercel for optimal performance with zero configuration. Connect your GitHub repository to enable automatic deployments on every push:

1. Push your code to GitHub
2. Import the repository in Vercel dashboard
3. Add environment variables (Supabase URL, keys, Stripe keys)
4. Deploy

Set up database migrations using Supabase's migration system to version control your schema changes:

-- Create migration file
npx supabase migration new add_tasks_table

-- Write SQL in generated file under supabase/migrations/
-- Apply migrations
npx supabase db push

Implement preview deployments for every pull request. Vercel automatically creates preview environments with unique URLs, allowing you to test changes before merging to production.

Set up error tracking with Sentry to catch production errors before users report them:

npm install @sentry/nextjs

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
})

Monitoring and Analytics

You can't improve what you don't measure. Effective monitoring tracks both technical metrics like error rates and business metrics like feature adoption.

Use Vercel Analytics to monitor Web Vitals and user experience metrics. Enable it in your Vercel project settings and add the Analytics component:

// app/layout.tsx
import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

Track business metrics by logging events to your database or a dedicated analytics platform. This helps you understand which features drive retention and conversion:

// lib/analytics.ts
export async function trackEvent(
  event: string,
  properties?: Record<string, any>
) {
  const supabase = createClient()
  const { data: { user } } = await supabase.auth.getUser()

  await supabase.from('events').insert({
    event,
    properties,
    user_id: user?.id,
    timestamp: new Date().toISOString(),
  })
}

Frequently Asked Questions

Can I use a different database instead of PostgreSQL?

While Supabase is built on PostgreSQL, you can use other databases, but you'll lose Supabase's row-level security, real-time subscriptions, and built-in auth integration. These features are what make the Next.js and Supabase combination compelling for SaaS development. If you need a different database, consider whether the additional integration complexity is worth the tradeoff.

How do I handle database migrations in production without downtime?

Use Supabase's migration system to version control schema changes. Test migrations in a staging environment first. For large tables, create new columns instead of modifying existing ones, migrate data in batches, then drop old columns once complete. Always add new indexes with the CONCURRENTLY option to avoid locking tables during creation.

What's the recommended approach for handling file uploads larger than 50MB?

For files larger than 50MB, implement resumable uploads using Supabase Storage's multipart upload API. This allows uploads to resume after network interruptions and provides better progress tracking. Alternatively, generate presigned URLs and have clients upload directly to storage, bypassing your application server entirely to reduce bandwidth costs.

How do I implement feature flags to control feature rollouts?

Add a feature_flags JSONB column to your organizations table. Store feature flags as key-value pairs, check them in your components, and update via API routes. For more sophisticated targeting and gradual rollouts, integrate a dedicated feature flag service like LaunchDarkly or PostHog's feature flags, which offer percentage rollouts and user targeting.

Should I use Server Actions instead of API routes for mutations?

Server Actions are ideal for simple form submissions and mutations that don't require complex response handling. Use API routes when you need fine-grained control over response headers, status codes, or when integrating with third-party webhooks. Server Actions reduce boilerplate but API routes provide more flexibility for complex scenarios.

How do I test row-level security policies before deploying to production?

Write SQL tests that verify each policy with different user contexts. Use Supabase's auth.uid() function with set_config to simulate different users. Create a test suite that attempts unauthorized access and verifies it fails. Run these tests in CI/CD pipelines before deploying schema changes to production.

What's the best way to handle soft deletes while maintaining referential integrity?

Add a deleted_at timestamp column instead of actually deleting records. Update your queries to filter WHERE deleted_at IS NULL. For referential integrity, keep foreign key constraints but use ON DELETE SET NULL or ON DELETE CASCADE appropriately. Create database views that filter out deleted records to simplify queries.

How do I optimize Supabase queries that return thousands of records?

Implement pagination using range() or limit/offset. For infinite scroll, use cursor-based pagination with created_at timestamps instead of offset-based pagination for better performance on large datasets. Add database indexes on columns used in WHERE clauses and ORDER BY clauses. Consider implementing search with PostgreSQL's full-text search or Supabase's pg_trgm extension.

Can I self-host Supabase if my SaaS grows large enough to justify it?

Yes, Supabase is fully open source and can be self-hosted using Docker. This makes sense when you exceed Supabase's largest paid tier or have specific compliance requirements. The tradeoff is operational complexity—you become responsible for database backups, security patches, and scaling infrastructure. Most SaaS companies don't reach the scale where self-hosting provides meaningful cost savings.

How do I implement SSO for enterprise customers?

Use Supabase's SAML 2.0 integration available on the Pro plan and above. Configure SAML providers in your Supabase dashboard, then redirect enterprise users to the appropriate SSO flow based on their email domain. Store organization-level SSO configuration in your organizations table and check it during the login flow to route users correctly.

Conclusion

Building a production-ready SaaS with Next.js and Supabase requires understanding three core architectural patterns: proper multi-tenancy with row-level security, real-time collaboration with Supabase's presence and broadcast features, and subscription management with Stripe webhooks. The combination eliminates weeks of infrastructure work that would otherwise delay your product launch.

The patterns demonstrated here scale from prototype to thousands of paying customers without requiring architectural rewrites. Row-level security policies prevent data leaks as your team grows, server components optimize initial page loads, and Supabase's edge functions handle background processing without additional infrastructure. Start with these foundations and iterate based on your specific product requirements rather than rebuilding basic SaaS infrastructure from scratch.