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.
| Architecture | Client(s) | Key | Session storage |
|---|
| Next.js SSR | Server (cookies) + browser + admin | anon in-request, service_role server-only | HTTP cookies |
| SPA (React/Vue) | Single browser client | anon only | localStorage |
| Mobile (React Native) | Single native client | anon only | AsyncStorage |
| Serverless (Edge Functions) | Per-request client | anon (forwarded JWT) or service_role | none (stateless) |
| Multi-tenant | Any of the above | anon + RLS, or schema-per-tenant | per host pattern |
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:
'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!
)
}
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:
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
| Issue | Cause | Solution |
|---|
AuthSessionMissingError in Server Component | Cookies not passed to Supabase client | Use createServerClient from @supabase/ssr with cookie handlers |
| OAuth redirect fails in React Native | Missing deep link scheme | Add scheme to app.json and configure Supabase redirect URL |
service_role key in client bundle | Wrong env var prefix (NEXT_PUBLIC_) | Remove NEXT_PUBLIC_ prefix; only server code should access it |
| Multi-tenant data leak | Missing RLS policy or missing tenant_id filter | Verify RLS is enabled and policies check tenant_members |
Edge Function auth.getUser() returns null | Missing Authorization header | Forward user's JWT from the client call |
| Session not persisting on mobile | AsyncStorage not configured | Pass AsyncStorage in auth config; ensure package is installed |
Examples
Verify tenant isolation by impersonating a JWT and confirming RLS scopes the result:
SET request.jwt.claims = '{"sub": "user-uuid-1"}';
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
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.
