supabase-architecture-variants

Supabase Architecture Variants

Overview

Every Supabase createClient configuration turns on two questions: where the client runs (browser vs server) and which key it uses (anon respects RLS; service_role bypasses it). This skill supplies production-ready patterns for five architectures — Next.js SSR, SPA, Mobile, Serverless Edge Functions, and Multi-tenant isolation.

Prerequisites

• @supabase/supabase-js v2+ installed
• @supabase/ssr package for Next.js SSR (v0.5+)
• Supabase project with URL, anon key, and service_role key
• TypeScript project with generated database types (supabase gen types typescript)
• For mobile: React Native with Expo or bare workflow

Instructions

Pick the architecture that matches the target stack, then follow the linked walkthrough for the full, copy-ready client setup.

Step 1 — Next.js SSR (App Router)

Next.js App Router needs two separate clients: a server client that reads/writes auth cookies via @supabase/ssr, and a browser client for client components. A third service_role admin client is used only in Server Actions/Route Handlers and must never reach the browser. The browser client is the minimal skeleton:

// lib/supabase/client.ts
'use client'
import { createBrowserClient } from '@supabase/ssr'
import type { Database } from '../database.types'

export function createSupabaseBrowser() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!  // anon key only — respects RLS
  )
}

Full walkthrough — server client, admin client, middleware session refresh, server component usage, Server Actions, and the OAuth callback route: Next.js SSR patterns.

Step 2 — SPA (React/Vue) and Mobile (React Native)

SPAs and mobile apps both use a single browser/native client with the anon key; all authorization is enforced by RLS and the service_role key is never bundled. They differ only in session storage (localStorage for SPA, AsyncStorage for mobile) and OAuth handling (URL detection for SPA, deep links for mobile). Minimal SPA skeleton:

// src/lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

export const supabase = createClient<Database>(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
  { auth: { autoRefreshToken: true, persistSession: true, detectSessionInUrl: true } }
)

Full walkthrough — SPA singleton + auth-state listener, React Query hooks, React Native AsyncStorage client, mobile OAuth with deep links, and Expo app.json config: SPA and mobile patterns.

Step 3 — Serverless (Edge Functions) and Multi-Tenant

Edge Functions create a per-request client from the forwarded JWT (stateless, no session persistence), escalating to service_role only for privileged operations. Multi-tenant isolation is either RLS-based (a tenant_members lookup gates every row) or schema-per-tenant.

Full walkthrough — Edge Function per-request clients, admin escalation, RLS multi-tenant isolation, and tenant-scoped SDK queries: serverless and multi-tenant patterns.

Output

• Next.js SSR setup with server client (cookies-based auth), browser client, and middleware
• Server Actions using admin client with service_role for privileged operations
• SPA pattern with singleton client, React Query integration, and auth state listener
• React Native setup with AsyncStorage, deep link OAuth, and in-app browser
• Edge Function patterns for per-request auth and admin escalation
• Multi-tenant RLS isolation with tenant_members lookup and scoped queries
• Decision matrix for choosing the right architecture per stack

Error Handling

Examples

Verify tenant isolation by impersonating a JWT and confirming RLS scopes the result:

-- Test that RLS properly isolates tenants
SET request.jwt.claims = '{"sub": "user-uuid-1"}';

-- Should only return projects for user-uuid-1's tenant
SELECT * FROM public.projects;

More runnable examples — the Next.js OAuth callback route and further end-to-end flows: Next.js SSR patterns and examples.

Resources

• Supabase SSR (Next.js)
• Supabase React Native
• Supabase Edge Functions
• Multi-Tenant with RLS
• Supabase Auth Deep Linking
• @supabase/ssr Package

Next Steps

After wiring the client for your architecture, review supabase-known-pitfalls for common mistakes and anti-patterns to avoid, then generate database types with supabase gen types typescript and enable RLS on every table before shipping.