How do you build a multi-tenant Next.js app with subdomain routing?

Q: How do you build a multi-tenant Next.js app with subdomain routing?

**Target Audience:** Full-stack engineers preparing for senior Next.js or system design interviews — assumes App Router routing and basic DNS knowledge. **Difficulty:** Hard > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js 16.4.2 docs shipped with the package and, in the **Verified** section, against a running 16.4.2 lab app hit with `curl` and different `Host` headers, plus Chromium for `*.localhost`. The 16.4.2 multi-tenant guide itself is one paragraph that points to Vercel's Platforms starter kit; the architecture below is the one that starter uses (proxy plus rewrite to a tenant segment), built and tested from scratch here. ## 1. Why This Even Matters — A Story First A shopping mall has one building, one set of escalators, one security team, and two hundred shops. Each shop has its own sign and its own stock, and customers think of "the Acme shop", not "unit 1

The problem

Question presented to candidate: "We are building a store builder: every customer gets name.example.com, and paying customers can bring their own domain. Design the Next.js side: one app, many tenants. How do requests reach the right tenant, and what can go wrong?"

What a strong answer should cover:

One deployment serves every tenant; wildcard DNS and TLS for *.example.com, plus per-domain certificates for custom domains.
proxy.ts reads the Host header, resolves the tenant (subdomain or custom-domain lookup), and rewrites the URL to an internal route such as /s/[tenant]/... while the browser URL stays unchanged.
The tenant is part of the route path, so ISR and caches are keyed per tenant; generateStaticParams can prerender known tenants and new ones render on demand.
Isolation is enforced in the data layer (every query scoped by tenant), and the internal /s/* paths must not be reachable directly.
Edge cases: unknown hosts, cached 404s for tenants created later, cookies scoped per host, Server Actions allowedOrigins for custom domains, and per-tenant metadata.

Clarifying questions expected:

"Custom domains, or only subdomains?" — custom domains add certificate automation and a domain table.
"How different are tenants: theme only, or features and data residency?" — that decides one app versus several deployments.

Code / implementation expected: Yes — a proxy.ts that rewrites by host, and the tenant route it rewrites to.

nextjs
multi-tenant
proxy
architecture

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Full-stack engineers preparing for senior Next.js or system design interviews — assumes App Router routing and basic DNS knowledge. Difficulty: Hard

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js 16.4.2 docs shipped with the package and, in the Verified section, against a running 16.4.2 lab app hit with curl and different Host headers, plus Chromium for *.localhost. The 16.4.2 multi-tenant guide itself is one paragraph that points to Vercel's Platforms starter kit; the architecture below is the one that starter uses (proxy plus rewrite to a tenant segment), built and tested from scratch here.

1. Why This Even Matters — A Story First

A shopping mall has one building, one set of escalators, one security team, and two hundred shop

The solution is hidden so you can try first

10 min read · 9 sections

Read the code

proxy.ts: map subdomains and custom domains to an internal route

// proxy.ts
import { NextRequest, NextResponse } from "next/server";
import { ROOT_DOMAIN, tenantFromCustomDomain } from "./lib/tenants";

function resolveTenant(host: string): string | null {
  const hostname = host.split(":")[0].toLowerCase();
  if (hostname === ROOT_DOMAIN || hostname === `www.${ROOT_DOMAIN}`) return null; // marketing site
  if (hostname.endsWith(`.${ROOT_DOMAIN}`)) return hostname.slice(0, -(ROOT_DOMAIN.length + 1));
  return tenantFromCustomDomain(hostname); // custom domain, or null
}

export function proxy(request: NextRequest) {
  const host = request.headers.get("host") ?? "";
  const { pathname, search } = request.nextUrl;
  const tenant = resolveTenant(host);

  // Nobody may reach the internal /s/* tree directly.
  if (pathname.startsWith("/s/")) return new NextResponse("Not found", { status: 404 });

  if (!tenant) return NextResponse.next(); // root domain: the marketing pages in app/

  const url = request.nextUrl.clone();
  url.pathname = `/s/${tenant}${pathname}`;
  url.search = search;
  const res = NextResponse.rewrite(url);
  res.headers.set("x-tenant", tenant);
  return res;
}

export const config = {
  matcher: ["/((?!_next/|favicon.ico|.*\\..*).*)"],
};

app/s/[tenant]/page.tsx: one prerendered page per tenant

// app/s/[tenant]/page.tsx
import { notFound } from "next/navigation";
import { getTenant, allTenantSlugs } from "@/lib/tenants";

export const revalidate = 60;
export function generateStaticParams() {
  return allTenantSlugs().map((tenant) => ({ tenant }));
}

export default async function TenantHome({ params }: { params: Promise<{ tenant: string }> }) {
  const { tenant: slug } = await params;
  const tenant = await getTenant(slug);
  if (!tenant) notFound();
  return <main><h1>{tenant.name}</h1><p>plan: {tenant.plan}</p></main>;
}

lib/tenants.ts: the tenant lookup

// lib/tenants.ts
export type Tenant = { slug: string; name: string; plan: "free" | "pro"; customDomain?: string };

// In a real app this is a database or edge config lookup.
const TENANTS: Tenant[] = [
  { slug: "acme", name: "Acme Corp", plan: "pro", customDomain: "shop.acme.test" },
  { slug: "globex", name: "Globex", plan: "free" },
];

export const ROOT_DOMAIN = process.env.ROOT_DOMAIN ?? "example.com";

export async function getTenant(slug: string): Promise<Tenant | null> {
  return TENANTS.find((t) => t.slug === slug) ?? null;
}

export function tenantFromCustomDomain(host: string): string | null {
  return TENANTS.find((t) => t.customDomain === host)?.slug ?? null;
}

export function allTenantSlugs() {
  return TENANTS.map((t) => t.slug);
}

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.