| name | supabase-architecture-variants |
| description | Use when choosing how to integrate Supabase into a specific stack — setting up
Next.js SSR auth flows, wiring an SPA or React Native client, configuring mobile
deep links, or designing multi-tenant data isolation. Covers where the client runs
(browser vs server) and which key it uses (anon respects RLS, service_role bypasses it).
Trigger with phrases like "supabase next.js", "supabase SSR", "supabase react native",
"supabase SPA", "supabase serverless", "supabase multi-tenant", "supabase server component",
"supabase architecture", "supabase service_role server".
|
| allowed-tools | Read, Write, Edit, Bash(supabase:*), Bash(npx:*), Grep |
| version | 1.53.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","supabase","architecture","nextjs","ssr","spa","mobile","multi-tenant","serverless"] |
| compatibility | Designed for Claude Code |
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:
