Next.js Architecture for Multi-Client SaaS
A surprising number of "multi-tenant" Next.js products start as a single client's app with a config flag bolted on for client #2. It works for a while, then every new client adds another branch, and six months later nobody can tell what's shared logic versus one client's special case.
Decide tenancy at the data layer, not the component layer
The most durable pattern is to make every data-fetching function tenant-aware from day one — pass a `tenantId` through `getServerSideProps`/route handlers and scope every query by it, even for the first client. Retrofitting tenant scoping after a query layer has been written tenant-agnostic is far more error-prone than building it in from the start, because it's easy to miss one query and leak data across tenants.
Separate configuration from customization
Configuration — logo, colors, feature flags, copy — belongs in data (a database row or a config file keyed by tenant), not in code branches. Customization — a client needing genuinely different behavior, not just different values — is a sign that client needs its own component variant behind a shared interface, not an `if (tenant === 'acme')` scattered through a shared one. The test: if a non-engineer could plausibly change it, it's configuration; if it needs a developer, it's a variant.
One deployment, many tenants — or many deployments?
Next.js supports both, and the choice is mostly about isolation requirements, not framework limits. Shared deployment with middleware-based tenant resolution (subdomain or path) is simpler to operate and cheaper to run, and fine for most SaaS products. Per-tenant deployments make sense when clients need hard infrastructure isolation (compliance, custom domains with unusual TLS needs, or wildly different scaling profiles) — but that isolation comes at the cost of running N deployments instead of one, with N times the operational surface area.
Shared UI kit, not shared pages
Build a small internal component library (buttons, layout shells, data tables) that every tenant's pages consume, rather than copy-pasting a page per client. When a client needs a genuinely different page layout, that's a new page composed from the same building blocks — not a fork of an existing one. This is the difference between a codebase that gets easier to extend over time and one where every new client adds linear maintenance cost.
The common thread is deciding tenancy boundaries deliberately, early, at the layer where mistakes are expensive to unwind — not wherever the first branch happened to get added.