Multi-Zone Architecture

The plain-language idea

A zone is a full, separately-deployed Next.js application that owns one slice of a shared domain — say, everything under /docs. A multi-zone setup is several of these apps, each with its own repo, build, and deploy pipeline, stitched together behind a single domain so a visitor never sees the seam. example.com/ might be one app, example.com/docs a second, example.com/blog a third — three separate next builds, three separate deploys, one address bar.

This is not code-splitting and it is not a monorepo package. Each zone is a complete, independently-runnable Next.js app with its own node_modules, its own dependency versions, and its own release schedule. The only thing that unifies them is routing at the edge: one zone's next.config rewrites requests for another zone's path prefix to that zone's real deployed URL.

See it in a real thing: a marketing app and a docs app sharing one domain

The main app owns / and everything not claimed elsewhere. It rewrites /docs/* out to the docs app's own deployment:

// main app: next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  async rewrites() {
    return [
      {
        source: "/docs",
        destination: "https://docs-zone.example-internal.com/docs",
      },
      {
        source: "/docs/:path*",
        destination: "https://docs-zone.example-internal.com/docs/:path*",
      },
    ];
  },
};

The docs app, on the other side, has to know it's being served from under /docs rather than its own root — it sets basePath so every route, asset, and internal link resolves correctly:

// docs zone: next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  basePath: "/docs",
};

From the browser's point of view this is one seamless site. From the infrastructure's point of view it's two unrelated deployments, and the rewrite in the main app's next.config is the only thing gluing them together.

What people usually miss

Watch out

• Each zone is a fully separate build, not a shared runtime. There's no shared React tree, no shared client-side router state, and no shared data cache across the boundary — a navigation from the main app into /docs is a genuine hard navigation, even though it looks instant on a fast connection.
• The rewrite destination must be reachable by the server doing the rewriting. In production this is usually an internal URL or another Vercel deployment, resolved at request time — a typo or an unreachable destination surfaces as a broken page under that path prefix, not a build error, because rewrites are evaluated per-request.
• basePath isn't optional busywork — every route, static asset, and internal link in the owned zone depends on it. Forget it and the docs app works fine on its own subdomain but silently 404s on every asset once it's mounted under /docs, because it's still generating root-relative paths.

The genealogy: this is rewrites, pointed at a different server

Multi-zone routing leans on the exact same rewrite mechanism this track's request-interception lesson covers — the only difference is the rewrite destination is a whole other deployed application instead of another route in the same app. If you understand how a rewrite silently swaps one URL for another before rendering, you already understand the entire mechanism a multi-zone setup depends on.