A-10 — Multi-Zones, Multi-Tenant, and Distributed Architecture

A concrete example with Auth.js (NextAuth), which is the common case since most teams already run it somewhere in the zone stack:

// auth.ts — identical in EVERY zone's deployment
import NextAuth from 'next-auth';
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [/* ... */],
  secret: process.env.AUTH_SECRET, // same value in every zone's env
  cookies: {
    sessionToken: {
      name: 'next-auth.session-token',
      options: {
        domain: '.example.com', // parent domain — readable by every zone
        path: '/',
        httpOnly: true,
        sameSite: 'lax',
        secure: true,
      },
    },
  },
});

Deploy this same auth.ts (same AUTH_SECRET env var, same cookie config) to both the marketing zone and the docs zone. Neither zone is "the" auth server — a request to either one runs Auth.js's own JWT verification against the cookie it finds. If the signature checks out, that zone renders the authenticated view. If a user logs in on zone A, the cookie Auth.js sets is visible to zone B on the very next request, and zone B's own Auth.js instance verifies it independently.

The two failure modes worth knowing before you hit them in production:

• Cookie scoped to a subdomain by accident. If any zone is deployed on its own subdomain (docs.example.com behind a rewrite from example.com/docs, rather than served path-based), double-check the Domain attribute actually resolves to a value covering all zones. This is the single most common reason "shared auth" silently doesn't share.
• Secret drift between zones. Different teams, different deploy pipelines, different secrets managers — it's easy for zone B's AUTH_SECRET to fall out of sync with zone A's after a rotation. Rotate this secret through a single source of truth (a shared secrets manager entry all zone CI pipelines pull from), not copy-pasted into each zone's environment variables independently.

---

Multi-Tenant Architecture — One App, Many Customers

Multi-tenancy is a different problem entirely. One Next.js application serves multiple customers (tenants), each with their own data, potentially their own domain, and sometimes their own branding.

The three flavours of multi-tenancy in Next.js:

Path-based: example.com/team-a/dashboard, example.com/team-b/dashboard Subdomain-based: team-a.example.com, team-b.example.com Custom domain: dashboard.team-a-company.com, portal.team-b.com

---

Path-Based Multi-Tenancy

The simplest. The tenant identifier is in the URL path, available to Server Components as a route param:

app/
  [tenant]/
    layout.tsx    ← load tenant config, validate slug
    dashboard/
      page.tsx
    settings/
      page.tsx

// app/[tenant]/layout.tsx
export default async function TenantLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ tenant: string }>;
}) {
  const { tenant } = await params;
  const tenantConfig = await db.tenants.findUnique({ where: { slug: tenant } });
 
  if (!tenantConfig) notFound();
 
  return (
    <TenantProvider config={tenantConfig}>
      {children}
    </TenantProvider>
  );
}

---

Subdomain-Based Multi-Tenancy with Middleware

Subdomain tenancy requires Middleware to extract the tenant from the hostname and inject it into the request:

// middleware.ts
export async function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') ?? '';
  const subdomain = hostname.split('.')[0];
 
  // Skip for www, app (non-tenant subdomains)
  const nonTenantSubdomains = new Set(['www', 'app', 'api']);
  if (nonTenantSubdomains.has(subdomain)) {
    return NextResponse.next();
  }
 
  // Rewrite the request to include the tenant in the URL
  const url = request.nextUrl.clone();
  url.pathname = `/${subdomain}${url.pathname}`;
 
  return NextResponse.rewrite(url);
}

This rewrite is invisible — team-a.example.com/dashboard is rewritten to serve content from /team-a/dashboard internally, but the URL in the browser stays as team-a.example.com/dashboard.

---

Custom Domain Multi-Tenancy

Custom domains — where tenants use their own domain (app.customer.com) pointing to your application — are the most complex variant. The tenant-to-domain mapping must be stored in a database and the Middleware must look it up.

The challenge: Middleware can't use Prisma. The solution is a lightweight, edge-compatible lookup:

// middleware.ts
export async function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') ?? '';
 
  // Skip your own domains
  if (hostname.endsWith('.example.com') || hostname === 'example.com') {
    return NextResponse.next();
  }
 
  // Look up the tenant for this custom domain
  // Must be an edge-compatible lookup (HTTP API, not database)
  const tenantResponse = await fetch(
    `https://api.example.com/tenant-by-domain?domain=${hostname}`,
    { next: { revalidate: 300 } } // cache for 5 minutes
  );
 
  if (!tenantResponse.ok) {
    return NextResponse.redirect(new URL('/404', request.url));
  }
 
  const { tenantId } = await tenantResponse.json();
 
  const url = request.nextUrl.clone();
  url.pathname = `/${tenantId}${url.pathname}`;
 
  return NextResponse.rewrite(url);
}

The next: { revalidate: 300 } on the lookup fetch is critical — without caching, every request to a custom domain triggers a lookup API call, adding latency and load to your lookup service.

For scale, replace the HTTP lookup with Vercel's Edge Config or Upstash Redis — both are edge-compatible and have sub-millisecond read latency for cached values.

---

Tenant Data Isolation

Multi-tenancy requires rigorous data isolation. The most common architecture:

Row-level isolation (single database): All tenants share a database. Every table has a tenantId column. All queries are scoped with WHERE tenantId = ?. Prisma makes this manageable with middleware:

// lib/db.ts — Prisma client with tenant scoping
import { PrismaClient } from '@prisma/client';
import { AsyncLocalStorage } from 'async_hooks';
 
const tenantStorage = new AsyncLocalStorage<string>();
 
export const db = new PrismaClient().$extends({
  query: {
    $allModels: {
      async $allOperations({ args, query, model }) {
        const tenantId = tenantStorage.getStore();
 
        if (tenantId && args.where !== undefined) {
          args.where = { ...args.where, tenantId };
        }
 
        return query(args);
      },
    },
  },
});
 
export function withTenant<T>(tenantId: string, fn: () => T): T {
  return tenantStorage.run(tenantId, fn);
}

Schema isolation (single database, multiple schemas): Each tenant gets a PostgreSQL schema. More isolation, more complexity, harder to query across tenants.

Database isolation (separate databases): Maximum isolation. Most expensive. Used when regulatory requirements mandate tenant data separation (healthcare, finance).

For most SaaS applications, row-level isolation with a Prisma extension is the correct default. It handles 99% of use cases and doesn't require complex database management.

---

Vercel Edge Config for Tenant Routing

Vercel Edge Config is a key-value store readable at the edge with sub-millisecond latency — purpose-built for the tenant routing problem:

// middleware.ts
import { get } from '@vercel/edge-config';
 
export async function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') ?? '';
 
  // Sub-millisecond lookup — Edge Config is always in memory at the edge
  const tenantId = await get<string>(`domain:${hostname}`);
 
  if (!tenantId) {
    return NextResponse.redirect(new URL('/not-found', request.url));
  }
 
  const url = request.nextUrl.clone();
  url.pathname = `/${tenantId}${url.pathname}`;
  return NextResponse.rewrite(url);
}

Edge Config is populated by your backend when a new custom domain is added — you write to it via the Edge Config API after verifying the domain. The edge reads it in Middleware with no HTTP round trip.

---

assetPrefix for Tenant-Specific CDN Origins

Every one of the tenant-routing patterns above deals with pages — which HTML gets rendered for which hostname. There's a separate, often-missed problem for white-labeled multi-tenant setups: where do a zone or deployment's static assets (_next/static/* — your JS chunks, CSS, fonts) get served from?

By default, they're served from the same origin as the page. That's fine until a tenant wants their deployment to look and feel like it's fully theirs — served entirely from assets.tenant-company.com, fronted by a CDN they control or that you've provisioned per-tenant, rather than everything hanging off your shared example.com origin. assetPrefix in next.config.ts is the knob for this:

// next.config.ts
const config: NextConfig = {
  assetPrefix:
    process.env.NODE_ENV === 'production'
      ? 'https://cdn.tenant-a-company.com'
      : undefined,
};

With this set, every reference Next.js emits to _next/static/* — in the HTML <script>/<link> tags, in the client runtime's chunk-loading logic — points at https://cdn.tenant-a-company.com/_next/static/* instead of a relative path on the serving origin. That's the mechanism white-labeled deployments use: tenant A's custom domain fronts a CDN pointed at tenant A's asset origin, tenant B's fronts a different one, and the two never share a static asset path even though they might be running the same underlying build.

The constraint this implies — and it trips people up: assetPrefix gets baked into the HTML and the client bundle at build time. It is not something you can read from a request and swap in dynamically per-tenant inside Middleware or a Server Component — by the time a request arrives, the asset URLs are already fixed strings inside the already-built HTML and JS. This means:

• If every tenant needs a genuinely different assetPrefix, you need a separate build per tenant (or per asset-origin), each with its own next.config.ts value baked in, not one shared build serving all tenants.
• If tenants can share the same static assets — which is the common case, since white-labeling is usually about the domain and branding, not different compiled JavaScript — a single build with one shared CDN origin (or none at all) is simpler and is what most teams actually want. Reach for per-tenant assetPrefix only when tenants genuinely need assets served from their own domain or CDN account, not by default.
• Tenant detection for the purpose of choosing which assetPrefix to bake in has to happen at build time (an env var set per CI job, a build matrix keyed by tenant), not at request time. If you find yourself wanting "read the hostname, then pick the asset origin," that's a sign you actually want per-tenant builds, not a single dynamic build.

---

Where We Go From Here

A-11 goes under the hood of the build system — Turbopack replacing Webpack, SWC replacing Babel, and what these changes mean for build times, bundle analysis, and custom configuration. After the architecture patterns of A-10, A-11 explains the engine that produces the deployable output.

---