Building a Multi-Tenant SaaS on a Single Supabase Database

A createTenant() factory function merges per-tenant overrides with shared defaults and computes the convenience booleans automatically:

This means adding a new tenant is a config entry, not code changes. The type system enforces completeness — if you miss a required field, TypeScript tells you before the build finishes.

Step 2: A Feature Flag System#

Each tenant exposes a distinct surface area. ExpertSapiens has the full feature set. MrVisaKorea shows visa guides and hides the property listings. ApostilleFirst has no expert directory — it's a document legalization service, not a marketplace.

Rather than scattering if (tenant.id === "mrvisakorea") checks everywhere, I use a TenantFeatures interface with every flag defaulting to false. Each tenant only enables what it needs:

Components check tenant.features.showVisaGuides rather than the tenant ID. The flag name expresses intent; the ID is implementation detail. This also makes it easy to toggle features across tenants without touching component code.

Step 3: Hostname Resolution at the Middleware Layer#

Tenant resolution happens once — in Next.js middleware — before any page renders. The middleware reads the request hostname and calls getTenantByHostname():

The resolved tenant is forwarded as an x-tenant header and picked up by server components via headers(). No prop drilling, no context providers wrapping the entire app — every server component can resolve its tenant in one line.

For local development, a NEXT_PUBLIC_TENANT_OVERRIDE env var (or a cookie set by an in-app dev switcher) lets you browse any tenant on localhost without changing the hostname.

Step 4: Data Isolation with a Single Database#

All tenants share one Supabase project. The experts table has a sites column — a text[] array of which tenant keys that expert belongs to. Tenant-scoped queries filter with sites @> ARRAY['mrvisakorea'], using a GIN index on the column for performance.

This means a single expert can appear on multiple tenants — or none. The admin panel has per-expert toggles. No duplicated rows, no cross-tenant joins.

Row-Level Security policies enforce the same isolation at the database layer:

RLS means even a bug in application code can't return another user's bookings. The enforcement happens in Postgres, not in a middleware function that could be bypassed.

Step 5: Tenant-Aware Routing#

Some tenants have entirely different page universes. MrVisaKorea has visa guide pages that don't exist on ExpertSapiens. ApostilleFirst has apostille service pages. SeoulHomes has property listings.

categoryFilter on the tenant config handles this at the routing layer — if a tenant has categoryFilter: ["immigration", "legal"], then /category/[slug] returns 404 for any other slug. No accidental content leakage across tenant surfaces.

For selecting per-tenant values in components, a selectByTenant() utility keeps the code clean:

This is more readable than a switch statement and fully typed — TypeScript will error if you reference a TenantId that doesn't exist.

What This Looks Like in Practice#

Seven live sites. One vercel deploy. When I fix a bug in the booking flow, all seven tenants get the fix simultaneously. When I add a new page type, I add one feature flag and enable it on the tenants that need it.

The tradeoff is complexity in the config layer and careful discipline around data isolation. The config is verbose — each TenantConfig object is ~40 lines — but it's all in one file (src/lib/tenant.ts) and the TypeScript compiler catches any inconsistencies.

For projects where each client needs meaningfully different behavior but shares a common platform, this pattern is significantly more maintainable than separate repositories.

What This Architecture Requires#

• Next.js App Router — server components and middleware make tenant resolution clean and zero-overhead
• Supabase — array column with GIN index for multi-tenant DB queries; RLS for security
• TypeScript — the config system only works well with types enforcing completeness
• Disciplined feature flagging — resist the urge to use tenant.id directly in components; flags are more refactorable

If you're building a platform that needs to support multiple brands, clients, or subdomains from a single codebase — this is a pattern worth considering. I've used it across multiple production projects and it's held up well.

Get in touch if you'd like to discuss your project →