Multi-zones

One address, two Next.js apps

The tea shop has a blog now. A content team writes it and wants to publish on its own schedule, without waiting for the shop's team to build and deploy. But customers should find it at the shop's own address, under /blog, with the same look. One answer is to make the blog a Next.js app of its own, and put it behind the shop's address.

Next.js calls this multi-zones. A zone is a normal Next.js app that serves some of a domain's paths. Here the blog zone serves /blog and everything under it, and the shop, the main zone, serves the rest. Each zone is built and deployed on its own, and the visitor sees one site. Both apps live in the repository from Monorepos, beside a shared package, @tea/session, used further down.

The example below is that repository, recorded with Next.js 16.4.3. The recorder ran npm install, built the blog and started it on its own port, then built and started the shop, and gave it the blog's address in BLOG_URL, as a deployment sets an environment variable. Every request went to the shop.

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  cacheComponents: true,5  partialPrefetching: true,6  async rewrites() {7    return [8      { source: "/blog", destination: `${process.env.BLOG_URL}/blog` },9      { source: "/blog/:path+", destination: `${process.env.BLOG_URL}/blog/:path+` },10      { source: "/blog-static/:path+", destination: `${process.env.BLOG_URL}/blog-static/:path+` },11    ];12  },13};14 15export default nextConfig;

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/blog-static/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/blog-static/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/blog-static/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/blog-static/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/blog-static/_next/static/chunks/turbopack-3_hx5-791cmba.js" async=""></script>
    <script src="/blog-static/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <script src="/blog-static/_next/static/chunks/21poqdgvjdll4.js" async=""></script>
    <title>Tea blog</title>
    <script src="/blog-static/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <nav><a href="/">Teas</a> <a href="/blog">Blog</a></nav>
    <!--&-->
    <!--&-->
    <main>
      <h1>Tea blog</h1>
      <ul>
        <li><a href="/blog/brewing-mint">How to brew mint tea</a></li>
        <li><a href="/blog/green-tea-water">Why green tea needs cooler water</a></li>
      </ul>
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/blog-static/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

The Network tab opens on /blog, asked of the shop. It answered 200 with the blog's page: Tea blog and its two posts. Now open the Terminal tab and find the shop's build, the last one: its routes are ◐ / and ○ /_not-found. The shop has no /blog page at all. The blog's build, above it, lists ○ /blog and the posts. Lines 8 to 10 of apps/shop/next.config.ts did it: they are rewrites, which answer a path with another address's answer while the visitor's address stays the same (Next.js as a backend for your frontend used one for a service).

Routing between zones: rewrites and assetPrefix

A Next.js page is more than its HTML. Its JavaScript and CSS files, the ones next build writes into .next/static, come from /_next/static/… on the same address. Both apps write files there, and the browser asks the shop for all of them. So each zone besides the main one moves its files to a path of its own:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  cacheComponents: true,5  partialPrefetching: true,6  assetPrefix: "/blog-static",7  experimental: {8    serverActions: {9      // The domain visitors use, as the multi-zones guide asks each zone to list.10      allowedOrigins: ["tea-shop.example"],11    },12  },13};14 15export default nextConfig;16 

Line 6 sets assetPrefix to /blog-static. The blog's pages now ask for /blog-static/_next/static/…, and the blog serves its files there; in Next.js 15 and later it needs no extra rewrite for that. The main zone doesn't need an assetPrefix. Lines 7 to 12 are for Server Actions, and come back further down. The shop's three rules then send the blog its paths:

1. Line 8: /blog itself goes to BLOG_URL + /blog.
2. Line 9: /blog/:path+, one or more parts after /blog/, like /blog/brewing-mint, goes to the same path on the blog.
3. Line 10: /blog-static/:path+, the blog's files, goes to the blog too.

Pick /blog/brewing-mint, its first script in the overview's Network tab: the recorder asked the shop for the first script that page loads, /blog-static/_next/static/chunks/…, and the shop passed it to the blog, which answered 200, with Cache-Control: public, max-age=31536000, immutable. A rewrite's destination is read when next build runs, so the shop is built again when BLOG_URL changes. The docs recommend rewrites, which add the least delay; when the routing has to be decided per request, like during a migration behind a feature flag, they suggest proxy.ts instead. The main zone doesn't have to route at all: any reverse proxy in front of the zones, like a load balancer or a CDN, can send each path to its zone, with the same paths and files.

Here is the blog's post page and its Like button, a Client Component. Until React has hydrated it in the browser, it says Loading likes… and can't be clicked:

1"use client";2 3import { useEffect, useState } from "react";4 5export default function LikeButton() {6  const [ready, setReady] = useState(false);7  const [likes, setLikes] = useState(0);8  // Effects run only in the browser, once React has hydrated this button.9  useEffect(() => setReady(true), []);10  return (11    <button disabled={!ready} onClick={() => setLikes(likes + 1)}>12      {ready ? `Likes: ${likes}` : "Loading likes…"}13    </button>14  );15}16 

Line 9 is an Effect, and Effects only run in the browser, after hydration: it turns ready on. Line 11 keeps the button disabled until then, and line 12 shows Loading likes…. So the button tells you whether the blog's JavaScript arrived and ran. Real Chrome opened the post on the shop's address, in three versions:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  cacheComponents: true,5  partialPrefetching: true,6  assetPrefix: "/blog-static",7  experimental: {8    serverActions: {9      // The domain visitors use, as the multi-zones guide asks each zone to list.10      allowedOrigins: ["tea-shop.example"],11    },12  },13};14 15export default nextConfig;

With both settings, every file answered 200, and the button worked. Without assetPrefix, the shop answered the blog's requests from its own build: the files that hold the same Next.js and React code have the same names in both builds, so they came back 200, but the file with the post's own code answered 404. Without the third rule, every file answered 404. Either way, the HTML arrived and nothing on the page ever ran.

Linking across zones: a plain <a>

Inside one app, Link makes a soft navigation: the router fetches the next page's RSC payload, the description of what its Server Components rendered, and swaps in only what changed, without loading the page again (Linking and navigating). Another zone's page is another app's, built separately. The shop's nav uses a plain <a> for it, on line 10:

1import Link from "next/link";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <nav>10          <Link href="/">Teas</Link> <a href="/blog">Blog</a>11        </nav>12        {children}13      </body>14    </html>15  );16}

The Steps tab opens on the click on Blog: one document request, the blog's whole page, then each of its scripts from /blog-static/_next/. The next steps stay in the blog. Its home page links to each post with Link, so the blog's router prefetched them, and clicking How to brew mint tea made one fetch for the post's RSC payload and no document: a soft navigation inside the zone. The last step clicks the blog's Teas, a plain <a href="/">: a document again, and the shop's scripts again. Now the same nav with a Link to the blog:

1import Link from "next/link";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <nav>10          <Link href="/">Teas</Link> <Link href="/blog">Blog</Link>11        </nav>12        {children}13      </body>14    </html>15  );16}

On the first step, the Link prefetched /blog: the shop passed the router's request to the blog, and the blog answered with its RSC payload. On the click, the router asked for /blog's RSC payload again, then made a document request for /blog: a full page load after all. The payload came from another build, and in Next.js 16.4.3 the router loads the page in full when the build in a response doesn't match its own (lines 259 to 265 of fetch-server-response.ts). Each row compares the two links to the blog, as recorded:

The Link worked, but made extra requests, and only because the router fell back to a full page load. The docs ask for a plain <a> between zones, and so does the blog's own layout:

1export const metadata = { title: "Tea blog" };2 3export default function BlogLayout({ children }: LayoutProps<"/">) {4  return (5    <html lang="en">6      <body>7        <nav>8          <a href="/">Teas</a> <a href="/blog">Blog</a>9        </nav>10        {children}11      </body>12    </html>13  );14}15 

Line 8 links to the shop and to the blog's home with plain <a> tags. The blog's home is in its own zone, so a Link would work there too; the blog's home page uses Link for its posts, on line 11:

1import Link from "next/link";2import { posts } from "./posts";3 4export default function BlogHome() {5  return (6    <main>7      <h1>Tea blog</h1>8      <ul>9        {posts.map((post) => (10          <li key={post.slug}>11            <Link href={`/blog/${post.slug}`}>{post.title}</Link>12          </li>13        ))}14      </ul>15    </main>16  );17}18 

One domain, one set of cookies

The browser keeps each cookie for a host and a path, not for an app. Both zones answer on one host, the shop's, so a cookie set for that host with Path=/ goes with every request to either zone, and the shop's rewrite passes it on. Here is how a sign-in service would set the session cookie; it isn't part of the recorded repository:

1// In the sign-in service, once it has checked who is signing in. Not recorded.2(await cookies()).set("session", `${name}.${signature}`, {3  path: "/",4  httpOnly: true,5  sameSite: "lax",6  secure: process.env.NODE_ENV === "production",7  maxAge: 60 * 60 * 8,8});

• There's no domain option, so it's a host-only cookie: only this exact host gets it, not other subdomains like jobs.tea-shop.example.
• Line 3, Path=/: every path on the host, /blog too. With Path=/blog, only the blog would get it.
• Line 4, HttpOnly: the page's own JavaScript can't read it. That doesn't stop a forged request, and it doesn't hide the cookie from any zone's server, which gets it with every request.
• Line 5, SameSite=Lax: the browser leaves it off requests that other sites' pages send, like a form posted from another site, and sends it when the visitor follows a link to the shop.
• Line 6, Secure in production: only sent over HTTPS. Line 7: it expires after eight hours.

1import { createPublicKey, verify } from "node:crypto";2import { cache } from "react";3import { cookies } from "next/headers";4 5// Zones get only the sign-in service's public key: it checks a signature but can't make one.6function publicKey() {7  const x = process.env.SESSION_PUBLIC_KEY ?? "";8  if (!/^[\w-]{43}$/.test(x)) throw new Error("SESSION_PUBLIC_KEY must be an Ed25519 public key in base64url");9  return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x }, format: "jwk" });10}11 12// The cookie is "name.signature": the sign-in service's Ed25519 signature of the name.13export const readSession = cache(async () => {14  const [name = "", signature = ""] = ((await cookies()).get("session")?.value ?? "").split(".");15  if (!name || !/^[\w-]{86}$/.test(signature)) return null;16  return verify(null, Buffer.from(name), publicKey(), Buffer.from(signature, "base64url")) ? { name } : null;17});18 

The cookie is Asha's name, a dot, and a signature: an Ed25519 signature of the name, which only the private key can make. Line 7 reads the public key from SESSION_PUBLIC_KEY, line 8 refuses one that isn't 43 base64url characters (32 bytes), and line 9 turns it into a key object. Line 14 splits the cookie, line 15 checks that the signature is 86 characters (64 bytes), and line 16 checks it with the public key. cache on line 13 runs it once per render pass. A real session also carries an expiry and an id that the sign-in service can revoke (Authentication). Each zone gets the public key; for the recording, from a file:

# Recording only: a key pair made for this example. Public, so it can be committed:
# it checks signatures and can't make them. The private key stays in the sign-in service.
SESSION_PUBLIC_KEY=YvLjkzkP-c0RGUQ7hvYV8jowOjJ-hmZ0Eb7FfcSQ_X0

That key pair is a recording-only fixture, made for this example, and Asha's cookie, signed with it once, never expires. A public key is no secret: a zone that leaks it leaks nothing that lets anyone sign. The blog's post page reads the session in a part made for each request:

1import { Suspense } from "react";2import { cookies } from "next/headers";3import { notFound } from "next/navigation";4import { readSession } from "@tea/session";5import { posts } from "../posts";6import { savePost } from "./actions";7import LikeButton from "./like-button";8 9export function generateStaticParams() {10  return posts.map((post) => ({ slug: post.slug }));11}12 13async function Reader({ slug }: { slug: string }) {14  const session = await readSession();15  if (!session) return <p>Not signed in.</p>;16  const saved = (await cookies()).get("saved")?.value === slug;17  return (18    <form action={savePost.bind(null, slug)}>19      <p>Signed in as {session.name}.</p>20      {saved ? <p>Saved for later.</p> : <button>Save for later</button>}21    </form>22  );23}24 25export default async function Post({ params }: PageProps<"/blog/[slug]">) {26  const { slug } = await params;27  const post = posts.find((item) => item.slug === slug);28  if (!post) notFound();29  return (30    <main>31      <h1>{post.title}</h1>32      <p>{post.body}</p>33      <LikeButton />34      <Suspense fallback={<p>Checking your session…</p>}>35        <Reader slug={slug} />36      </Suspense>37    </main>38  );39}40 

Line 14 reads the session with the shared code. Line 15 answers Not signed in. without one. Line 16 reads a second cookie, saved. Line 18 posts the form to a Server Action, savePost, with the post's slug bound to it, and line 20 shows Saved for later. or the button. The action checks the session again, because a Server Action is a public endpoint that anyone can call (Securing Server Actions):

1"use server";2 3import { cookies } from "next/headers";4import { redirect } from "next/navigation";5import { readSession } from "@tea/session";6import { posts } from "../posts";7 8export async function savePost(slug: string) {9  // An action is a public endpoint: check who is asking, and what they ask for.10  if (!(await readSession())) return;11  if (!posts.some((post) => post.slug === slug)) return;12  // A stand-in for saving it in a database: one cookie, for this recording.13  (await cookies()).set("saved", slug, { path: "/", httpOnly: true, sameSite: "lax" });14  redirect(`/blog/${slug}`);15}16 

Line 10 stops without a valid session, and line 11 for a slug that isn't a post. Line 13 saves the post in a cookie: a stand-in for a database, for the recording. Line 14 sends the visitor back to the post. The recorder sent these requests to the shop's address, without a cookie and then as Asha, with her signed cookie (the sign-in service isn't part of the example). The overview's Network tab holds each one:

The shop and the blog both checked the same session. The form was posted without JavaScript, so the answer was a 303 redirect, with the new cookie. It came from the blog, but the browser keeps it for the shop's host, with Path=/, and sends it with every later request there, to both zones: the next request showed Saved for later. Both zones share every cookie name, so agree on them, as you agree on paths.

Server Actions behind another zone

Before it runs an action, Next.js 16.4.3 compares the host in the form's Origin header, the address of the page that sent it, with the request's x-forwarded-host header, or with host when there's none. A different host is refused, unless it's in serverActions.allowedOrigins. A request with no Origin at all is let through, with a warning in the server's log (lines 729 to 745 of action-handler.ts). The multi-zones guide asks each zone to list the domain visitors use, and lines 7 to 12 of the blog's next.config.ts do:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  cacheComponents: true,5  partialPrefetching: true,6  assetPrefix: "/blog-static",7  experimental: {8    serverActions: {9      // The domain visitors use, as the multi-zones guide asks each zone to list.10      allowedOrigins: ["tea-shop.example"],11    },12  },13};14 15export default nextConfig;16 

In the recording, the visitors' host was 127.0.0.1, which that list doesn't name, and the action still ran. The shop's rewrite had set x-forwarded-host to the host the visitor used (lines 30 to 41 of proxy-request.ts), the same host as the Origin. That's what this setup did when it was recorded, not something to rely on. x-forwarded-host is only worth trusting when the server at your edge checks the Host header and writes the forwarded headers itself, replacing any a visitor sent; when a proxy between the visitor and a zone puts the zone's own address there, only allowedOrigins lets the action through. And the origin check only stops other sites' pages: the action still checks the session itself, as line 10 of actions.ts does.

When to split an app, and when not to

A zone is a second app to build, deploy, watch and upgrade. It pays off when the split follows a real boundary: a team that ships on its own schedule, pages that have little to do with the rest, or a part that uses another framework, which a zone may. It costs something on every crossing: the recordings show a full page load, and the next zone's scripts downloaded and run. Each row is one thing a split changes:

Keep pages that people move between often in one zone: the teas, their reviews, the cart and checkout. React state, like a half-typed search, doesn't survive a crossing. The zones also have to agree on what they share: which paths each one owns, where its files live, the cookie names and how sessions are checked, and the shared UI that makes them look like one site. They don't need the same Next.js version, or even the same framework. If the reason to split is a slow build, or a big folder, a monorepo with shared packages and Turborepo's cache solves that inside one app first.

Planning the tea shop's zones

The shop is growing. Sort each part: does it stay in the shop's zone, or get a zone of its own?

Common mix-ups

• "Zones are routes inside one app." No. Each zone is a whole Next.js app, with its own build. The shop's build has no /blog route at all.
• "The rewrites for the pages are enough." No. The zone's files need a path of their own (assetPrefix) and a rule in the main zone; without either, the recorded blog page never ran.
• "Link makes moving between zones fast." No. It prefetched, asked again, and then loaded the whole page anyway. Use a plain <a>.
• "Each zone needs its own sign-in." No. One host means one set of cookies, and each zone can check the same session. Give the zones a key that can check sessions but not make them, so a broken zone can't forge one.
• "Splitting into zones makes the site faster." Not for visitors who cross between them: each crossing is a full page load. Zones make teams independent; they don't make navigation faster.
• "A zone has to be a Next.js app." Not the other zones: the main zone's rewrites can send paths to an app built with anything.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  async rewrites() {
    return [
      { source: "/blog", destination: `${process.env.BLOG_URL}/blog` },
      { source: "/blog/:path+", destination: `${process.env.BLOG_URL}/blog/:path+` },
    ];
  },
};

export default nextConfig;

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  async rewrites() {
    return [
      { source: "/blog", destination: `${process.env.BLOG_URL}/blog` },
      { source: "/blog/:path+", destination: `${process.env.BLOG_URL}/blog/:path+` },
      { source: "/blog-static/:path+", destination: `${process.env.BLOG_URL}/blog-static/:path+` },
    ];
  },
};

export default nextConfig;

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  async rewrites() {
    return [
      { source: "/blog", destination: `${process.env.BLOG_URL}/blog` },
      { source: "/blog/:path+", destination: `${process.env.BLOG_URL}/blog/:path+` },
      { source: "/blog-static/:path+", destination: `${process.env.BLOG_URL}/blog-static/:path+` },
      // Add the docs zone's rules here
    ];
  },
};

export default nextConfig;

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  async rewrites() {
    return [
      { source: "/blog", destination: `${process.env.BLOG_URL}/blog` },
      { source: "/blog/:path+", destination: `${process.env.BLOG_URL}/blog/:path+` },
      { source: "/blog-static/:path+", destination: `${process.env.BLOG_URL}/blog-static/:path+` },
      { source: "/docs", destination: `${process.env.DOCS_URL}/docs` },
      { source: "/docs/:path+", destination: `${process.env.DOCS_URL}/docs/:path+` },
      { source: "/docs-static/:path+", destination: `${process.env.DOCS_URL}/docs-static/:path+` },
    ];
  },
};

export default nextConfig;

Check your understanding

For each question, think about which app answers, and what the browser sees.

Key takeaways

• A zone is a Next.js app that serves some of a domain's paths. The main zone answers everything and sends other zones their paths with rewrites.
• Every zone besides the main one sets assetPrefix, and the main zone rewrites that path too; otherwise the zone's JavaScript never arrives.
• Link to another zone with a plain <a>. Crossing is a full page load either way; a Link only adds requests.
• One host means one set of cookies: every zone gets the session. Let zones check it with a key that can't sign, so a broken zone can't forge one.
• List the visitors' domain in each zone's serverActions.allowedOrigins. Trust x-forwarded-host only when your edge writes it, and check the session in every action.
• Split along team boundaries and separate deploys, not through pages that people move between all the time.

Coming next: Project: a full-stack app. An invoices dashboard from start to finish: database, sign-in, Server Actions, caching, streaming, tests and deployment.