Module A-10·25 min read

Next.js multi-zones for independent team deploys, basePath and reverse proxy wiring, shared auth across zones, multi-tenant subdomain routing with per-tenant database isolation, and assetPrefix for tenant CDN origins.

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

Q: When using a Multi-Zone architecture to host multiple independent Next.js applications on the same domain, what is a key limitation regarding navigation between the zones?

Client-side navigation (using ` `) between zones is not possible; it will trigger a full page reload and the target zone will boot fresh. — Because each zone is a completely separate Next.js application, they do not share a React tree or Router Cache. A link crossing from one zone to another acts like a standard HTML link, resulting in a full page load.

Q: In a custom domain multi-tenancy architecture (e.g., `app.customer.com`), why is it recommended to use an edge-compatible store like Vercel Edge Config or Upstash Redis in Middleware, rather than querying a primary database like PostgreSQL?

Middleware cannot establish TCP connections to relational databases like PostgreSQL, necessitating an HTTP-based or edge-compatible lookup. — Middleware runs in the Edge Runtime, which restricts the use of Node.js APIs like native TCP connections required by Prisma and PostgreSQL. You must use edge-compatible key-value stores or cached HTTP endpoints to perform lookups.

Q: What is the most common and generally recommended approach for enforcing tenant data isolation in a standard SaaS application utilizing a single database?

Row-level isolation: adding a `tenantId` column to all tables and scoping all queries (e.g., using a Prisma middleware or extension) to that specific ID. — Row-level isolation is the most practical balance of security and maintainability for the vast majority of SaaS apps. Tools like Prisma extensions can automatically append `tenantId` filters to queries, mitigating the risk of accidental cross-tenant data leaks.

Who this is for: Architects building applications that have outgrown a single Next.js codebase — either because different teams own different parts of the product (multi-zone), or because the same codebase needs to serve multiple customers with isolated data and custom domains (multi-tenant). This module covers the architectural patterns for both.

Multi-Zone Architecture — One Domain, Multiple Apps

A Next.js multi-zone deployment lets you host multiple independent Next.js applications on the same domain. Each application owns a path prefix, and a reverse proxy routes requests to the right app.

The canonical use case: a large organisation where the marketing site (/), the documentation (/docs), and the main application (/app) are maintained by different teams with different release cycles. Rather than forcing them all into one repository and one deployment, each is an independent Next.js app.

text

example.com/          → Marketing Next.js app (marketing team, deploys 3x/week)
example.com/docs/*    → Docs Next.js app (developer experience team, deploys on content changes)
example.com/app/*     → Application Next.js app (product team, deploys 5x/day)

On Vercel, this is configured through the project settings as a "multi-zone" setup — each project gets a Vercel domain, and a rewrites config in the primary project routes traffic:

// next.config.ts (in the primary / zone)
const config: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: 'https://docs-zone.vercel.app/docs/:path*',
      },
      {
        source: '/app/:path*',
        destination: 'https://app-zone.vercel.app/app/:path*',
      },
    ];
  },
};

Each zone's next.config.ts sets a basePath so internal links resolve correctly:

// next.config.ts (in the /docs zone)
const config: NextConfig = {
  basePath: '/docs',
};

Multi-Zone Constraints

Multi-zone has real constraints that trip up teams the first time they try it.

Client-side navigation between zones is not possible. The App Router's client-side navigation works within a single Next.js app. A link from the marketing zone to /docs/getting-started causes a full page navigation — the docs zone app boots fresh. There's no shared React tree between zones.

This is actually fine for the canonical use case (marketing → docs → app are all different products) but becomes a problem if you're trying to use multi-zone for micro-frontend architecture where seamless navigation is expected.

Shared layouts require duplication. If you want a consistent header across all zones, each zone must implement it separately. There's no "shared layout" that spans zones. The coordination problem is usually solved with a shared npm package for the header component.

Router Cache doesn't cross zones. Each zone has its own Router Cache. Navigating from the marketing zone to the docs zone clears the Router Cache.

When Multi-Zone Is the Right Choice

Use multi-zone when:

Different parts of the site have legitimately different deployment cadences
Different teams own different parts and shouldn't share CI/CD pipelines
You're migrating from one architecture to another incrementally (old Pages Router app on /legacy, new App Router app on everything else)
Bundle size and cold start time are affected by mixing concerns (a marketing site and a data-heavy application have very different dependencies)

Don't use multi-zone for:

Micro-frontend architecture where seamless navigation is required
Sharing significant state between zones
Performance-critical flows that span zone boundaries

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:

text

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

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.

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.

Knowledge Check

When using a Multi-Zone architecture to host multiple independent Next.js applications on the same domain, what is a key limitation regarding navigation between the zones?

In a custom domain multi-tenancy architecture (e.g., app.customer.com), why is it recommended to use an edge-compatible store like Vercel Edge Config or Upstash Redis in Middleware, rather than querying a primary database like PostgreSQL?

What is the most common and generally recommended approach for enforcing tenant data isolation in a standard SaaS application utilizing a single database?

Test your knowledge with more question sets

PreviousModule A-9: Edge Compute, Feature Flags, and Geo-Routing Next Module A-11: Build Engine Internals — Turbopack, SWC, and Memory Optimisation

Discussion

Join the discussion

Loading comments...