Templates and the file hierarchy

A wrapper that starts fresh for each page

In Layouts and pages you saw that a layout.tsx wraps every page in its folder, and stays on the screen, with its state, while the visitor moves between those pages. Most of the time that's what you want. Sometimes you want the opposite: a wrapper that starts fresh on each page. That's a template, a file named template.tsx.

Here are the tea shop's tea pages with both. The tea layout has the menu of teas and a cup counter. The template puts a box for tasting notes under each tea page. Like every example in this lesson, it's a real Next.js 16.4.3 project, built with next build and run with next start, and what it sent back was recorded.

1import NotesBox from "./notes-box";2 3export default function TeasTemplate({ children }: { children: React.ReactNode }) {4  return (5    <div>6      {children}7      <NotesBox />8    </div>9  );10}

app/teas/template.tsx, the file shown first, looks like a layout. Line 3 takes children, the page, and types it as React.ReactNode, anything React can render. Line 6 puts the page there, and line 7 puts NotesBox under it. Click app/teas/notes-box.tsx: it starts with "use client", which marks where the part of the app that also runs in the browser begins, and line 6 keeps the notes in state. The template itself is a Server Component, as layouts and pages are by default; NotesBox is where the client part starts.

The Browser tab shows /teas/green: the shop's links, the tea menu and Cups brewed: 0 from the tea layout, the page, then Tasting notes from the template. Open the Network tab to see the nesting in the HTML: the tea layout's <section> holds its <nav>, the counter, and then the template's <div>; the <div> holds the page's <main> and the notes' <label>. Pick /teas/mint: the same layout and the same template, around a different page.

The order of special files in one folder

Six of the special files a folder can hold wrap each other in a fixed order, the same in every folder, which Loading UI listed briefly. Each row is one file, from the outside in: what it wraps, and what that means for you.

You can see part of the order in a recording. Here the tea folder has all six files, plus a page for today's tea that reads its data for each request:

app/
  teas/
    green/
      page.tsx
    mint/
      page.tsx
    today/
      page.tsx
    error.tsx
    layout.tsx
    loading.tsx
    not-found.tsx
    page.tsx
    template.tsx
  layout.tsx
  page.tsx

1export default function Loading() {2  return <p>Loading the tea…</p>;3}

<!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="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/3oh00mkbkq8u6.js" async=""></script>
    <script src="/_next/static/chunks/44sbnxvltlcyy.js" async=""></script>
    <script src="/_next/static/chunks/02thki4p6-q9o.js" async=""></script>
    <script src="/_next/static/chunks/2xcgb3osv6l_b.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <nav><a href="/">Home</a> <a href="/teas">Teas</a></nav>
    <!--&-->
    <section>
      <nav><a href="/teas/green">Green tea</a> <a href="/teas/mint">Mint tea</a></nav>
      <p>Cups brewed: <!-- -->0<!-- --> <button>Brew a cup</button></p>
      <!--&-->
      <div>
        <!--$?-->
        <template id="B:0"></template>
        <p>Loading the tea…</p>
        <!--/$-->
        <label>Tasting notes <input value=""></label>
      </div>
      <!--/&-->
    </section>
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <div hidden="" id="S:0">
      <!--&-->
      <template id="P:1"></template>
      <!--$-->
      <!--/$-->
      <!--/&-->
    </div>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <div hidden="" id="S:1">
      <main>
        <h1>Tea of the day</h1>
        <p>Mint tea, brewed at 9.</p>
      </main>
    </div>
    <script>…</script>
    <script>…</script>
  </body>
</html>

app/teas/loading.tsx, shown first, returns Loading the tea… on line 2. In app/teas/today/page.tsx, line 4 calls connection(), which tells Next.js to make this page for each request, and line 6 waits a second, as a slow database would. The Terminal tab lists ◐ /teas/today: a static shell made during the build, and the page streamed in for each request.

The Network tab is open on /teas/today, and shows the HTML in the order it arrived. Inside the tea layout's <section> comes the template's <div>, and inside it, <p>Loading the tea…</p>, then the notes' <label>. So the loading state sits inside the template, and the template inside the layout: the menu, the counter and the notes box show at once, and only the page waits. The page itself arrives further down, in a hidden <div>, and takes the fallback's place. error.tsx and not-found.tsx add nothing to the HTML: nothing broke, and nothing was missing.

Two rules follow from the order. First, error.tsx catches errors from what's inside it, never from the layout.tsx or template.tsx of its own folder; an error there goes to the error.tsx of the folder above. Second, the layout and the template stay on the screen around the loading, error and not-found screens of their folder, so the menu keeps working while the page part waits or fails. Error handling and Not found, forbidden and unauthorized show those screens.

Folders inside folders

Each folder's files nest inside the folder above. On /teas/green, the root layout from app wraps everything from app/teas, and the tea files wrap the page from app/teas/green. Written by hand, the tree Next.js builds for that address in the full tea folder is roughly this:

<RootLayout>
  <TeasLayout>
    <TeasTemplate key="green">
      <ErrorBoundary fallback={<TeaError />}>
        <Suspense fallback={<Loading />}>
          <NotFoundBoundary fallback={<TeaNotFound />}>
            <GreenTeaPage />
          </NotFoundBoundary>
        </Suspense>
      </ErrorBoundary>
    </TeasTemplate>
  </TeasLayout>
</RootLayout>

Line 1 is the root layout, and line 2 the tea layout. Line 3 is the template, with a key: React makes a new component whenever its key changes, and Next.js takes the key from the folder below the template, here green. Lines 4 to 6 are the three boundaries from error.tsx, loading.tsx and not-found.tsx. Line 7 is the page. This is a sketch to read, not code you write: in Next.js's code, the three boundaries are called ErrorBoundary, LoadingBoundary and HTTPAccessFallbackBoundary.

A layout stays; a template starts again

Now the difference you came for. Clicks need a browser with the page's JavaScript running, so this recording was made in real Chrome. The recorder opened /teas/green, pressed Brew a cup twice, typed Grassy into the tasting notes, clicked Mint tea, then clicked Green tea. Before you open the Steps tab, guess what the counter and the notes show after each click.

1import NotesBox from "./notes-box";2 3export default function TeasTemplate({ children }: { children: React.ReactNode }) {4  return (5    <div>6      {children}7      <NotesBox />8    </div>9  );10}

The Steps tab is open on step 5, right after the click on Mint tea. Cups brewed: 2: the tea layout stayed on the screen, so its BrewCounter kept its state, as in the layouts lesson. But the tasting notes are empty. Mint tea is a new page under the template, so Next.js made a new copy of the template for it, with a new NotesBox and a new, empty state. The click made no request at all: the Mint tea page had been prefetched, loaded in the background, when its link appeared.

Now pick step 6, back on Green tea. The notes say Grassy again. Next.js didn't throw Green tea's copy away when you left. With Cache Components on, as in new projects, it hides the page you leave with React's Activity, state and all, and shows it again when you come back. At each level of folders, it keeps the page on the screen plus up to two you left: in bfcache-state-manager.ts, MAX_BF_CACHE_ENTRIES is 3 with Cache Components on, counting the visible one, and 1 without. The template's copy for Green tea is part of what it kept. So a template doesn't forget everything on each visit: each page under it has its own copy, and a page you return to soon gets its copy back.

Which navigations make a new copy? The template's key comes from the folder right below it, so a new copy comes when that part of the address changes: /teas to /teas/green, or /teas/green to /teas/mint. The docs add two cases this recording doesn't show: moving deeper below that folder doesn't make a new copy of a template higher up, and a change in the query, the part after ?, doesn't either.

When a template beats a layout

A new copy also means its Effects run again. That's the other reason to use a template: code that should run each time a page shows, like logging a page view. Here a small Client Component logs a view in an Effect, and shows how many it logged. app/teas/views.ts stands in for an analytics service:

import ViewLogger from "./view-logger";

export default function TeasTemplate({ children }: { children: React.ReactNode }) {
  return (
    <div>
      {children}
      <ViewLogger />
    </div>
  );
}

Line 1 imports ViewLogger, and line 7 puts it under each tea page. Both versions below use the same ViewLogger: once in the template, once in the layout. Each was clicked through in Chrome: Green tea, Mint tea, Green tea, Home, then Teas. Guess the counts first.

1import ViewLogger from "./view-logger";2 3export default function TeasTemplate({ children }: { children: React.ReactNode }) {4  return (5    <div>6      {children}7      <ViewLogger />8    </div>9  );10}

In the template, every tea page that shows runs the Effect: Views logged: 1, 2, 3, then 4 on Teas. Even Green tea's copy, shown again from hiding, ran it again: React runs a hidden component's Effects again when it shows. In the layout, the count stays at 1 while you move between teas, because the layout never left the screen. It only logs 2 after Home and Teas, when the whole tea layout was hidden and shown again.

Next.js's docs name three reasons to pick a template:

• State that belongs to one page. An input or a form that should start empty on each page, like the tasting notes.
• Effects that run on each page. Logging a view, or anything else that must happen each time a page shows.
• A loading state on every navigation. The docs say a Suspense in a layout shows its fallback only the first time, and one in a template shows it again on each navigation, because the template is new.

Everything else belongs in a layout. A template costs a new copy on each page, so use one only when you want that.

default.tsx: a first look

One more special file belongs in the hierarchy, though it only matters with slots. A slot is a folder whose name starts with @, like app/@offer. It's a second place for a page, beside children: the layout gets it as a prop named after the folder. Slots are part of parallel routes, which have a lesson of their own: Parallel routes. Here the shop shows a special offer above the home page:

1export default function OfferDefault() {2  return null;3}

In app/layout.tsx, line 3 takes offer next to children, and line 10 puts it above the page. app/@offer/page.tsx is the offer for /. But the slot has no page for /teas. app/@offer/default.tsx, the file shown first, is what it shows then: line 2 returns null, nothing.

The Steps tab shows when that happens. Step 1 opens /, with the offer. Step 2 clicks Teas, and the offer is still there: on a click, Next.js keeps showing the slot's last page. Step 4 opens /teas as a fresh page load, and the offer is gone. With nothing to keep, Next.js rendered default.tsx. The Network tab's /teas shows the same: no <aside>.

Without default.tsx, Next.js 16.4.3 doesn't build at all:

1import Link from "next/link";2 3export default function RootLayout({ children, offer }: LayoutProps<"/">) {4  return (5    <html lang="en">6      <body>7        <nav>8          <Link href="/">Home</Link> <Link href="/teas">Teas</Link>9        </nav>10        {offer}11        {children}12      </body>13    </html>14  );15}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...⚠ Strict route matching is enabled by default. This validation indicates a bug in your app's route structure, but you can temporarily restore loose route matching by setting `deprecated.looseRouteMatching` to `true` in your Next.js config. > Build error occurredError: Turbopack build failed with 2 errors:./app/layout.tsxError: Parallel route slots cannot render the same URLsThe following layouts have parallel route slots that cannot render the same URLs:app/layout.tsx- /teas is missing a matching page or default.tsx in @offer Every URL matched by one slot must have a matching page or default.tsx in every sibling slot. ./app/teas/page.tsxError: Unmatched app pagesThe following page files do not match any complete route:- app/teas/page.tsx Every page must be part of at least one complete route. Add matching pages or default files for the sibling parallel route slots, or remove the unreachable pages.     at ignore-listed frames

The build stops with Parallel route slots cannot render the same URLs, and names the problem: /teas is missing a matching page or default.tsx in @offer. So this named slot needs a default.tsx: on a fresh load of /teas, @offer has no page and no last page to keep. (children is a slot too, without the @. The docs page for default.js still describes the older behavior for it, a 404, but Next.js 16.4.3's strict route matching stops the build when children has no default.tsx for an address its sibling slots can show. Parallel routes records both.)

Reading the tree Next.js builds

The sketch earlier was written by hand. You can read the real thing in Next.js's source, at the release every example here was built with. Two files do the work. First, create-component-tree.tsx reads each folder's special files: layout, template, error, loading, not-found, and two more for access errors, forbidden and unauthorized. A folder without a template gets React's Fragment in its place, which renders only its children (lines 218 to 226). Then it hands them to a component called LayoutRouter, which fills the layout's children (lines 696 to 724).

Second, LayoutRouter, in layout-router.tsx, nests them. Simplified, with the props and the development-only parts left out, it renders this for the folder below a layout:

<Activity key={stateKey} mode={stateKey === activeStateKey ? "visible" : "hidden"}>
  <TemplateContext.Provider key={stateKey} value={
    <ErrorBoundary errorComponent={error}>
      <LoadingBoundary loading={parentLoadingData}>
        <HTTPAccessFallbackBoundary notFound={notFound} forbidden={forbidden} unauthorized={unauthorized}>
          <RedirectBoundary>
            <InnerLayoutRouter tree={tree} />
          </RedirectBoundary>
        </HTTPAccessFallbackBoundary>
      </LoadingBoundary>
    </ErrorBoundary>
  }>
    {template}
  </TemplateContext.Provider>
</Activity>

In plain words, from the outside in:

1. Line 1: with Cache Components on, an Activity for each page Next.js keeps, visible or hidden. This is what kept Green tea's notes.
2. Line 2: the template's place, with the key from the folder below. Your template gets lines 3 to 11 as its children; line 13 is your template.
3. Line 3: an error boundary with your error.tsx.
4. Line 4: a loading boundary with your loading.tsx.
5. Line 5: one boundary for not-found.tsx, forbidden.tsx and unauthorized.tsx.
6. Line 6: a boundary for redirects. It catches a redirect() that reaches the browser while the page renders, and moves the router to the new address (Redirects covers the function).
7. Line 7: the folder below, with its own layout and its own LayoutRouter, all the way down to the page.

That's the whole hierarchy: the order of the boundaries in this one component. How a route becomes a React tree, in the course's last stage, reads these files properly.

Layout or template for the tea shop?

Each row asks one question of both files:

Sort the tea shop's parts: which file should hold each one?

Common mix-ups

• "A template replaces the layout." No. It goes inside the layout of its folder, and a folder can have both, as the tea folder does.
• "A template starts fresh on every visit." No. Each page under it gets its own copy. Coming back to a page you left soon brings its copy back, with its state.
• "A template has to be a Client Component." No. Like a layout, it starts as a Server Component; the state lives in the Client Components it renders.
• "error.tsx catches errors in the layout beside it." No. The layout and the template are outside it. The error.tsx of the folder above catches those.
• "The loading state replaces the whole folder." No. It shows inside the layout and the template; only the page part waits.
• "default.tsx is the page for a folder." No. That's page.tsx. default.tsx stands in for a slot that has no page for the address.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page.

page.tsx
error.tsx
layout.tsx
not-found.tsx
template.tsx
loading.tsx

import { connection } from "next/server";

export default async function TodayPage() {
  await connection();
  // Wait a moment, as a real database would, so the recording can catch the loading state.
  await new Promise((resolve) => setTimeout(resolve, 1000));
  return (
    <main>
      <h1>Tea of the day</h1>
      <p>Mint tea, brewed at 9.</p>
    </main>
  );
}

import NotesBox from "./notes-box";

export default function TeasTemplate({ children }: { children: React.ReactNode }) {
  return (
    <div>
      {children}
      <NotesBox />
    </div>
  );
}

import ViewLogger from "./view-logger";

export default function TeasTemplate({ children }: { children: React.ReactNode }) {
  return (
    <div>
      {children}
      <ViewLogger />
    </div>
  );
}

// app/@offer/default.tsx
export default function OfferDefault() {
  // What should the offer slot show on pages it has no page.tsx for?
}

export default function OfferDefault() {
  return null;
}

Check your understanding

For each question, find the file in the nesting order, and ask whether a new copy of it was made.

Key takeaways

• In one folder, the special files nest in this order: layout, template, error, loading, not-found, page. A folder below nests inside the folder above.
• The layout and the template stay around the loading, error and not-found screens; error.tsx never catches errors from the layout or template beside it.
• A layout is one copy for all its pages. A template is a new copy for each page under it, so state inside it starts fresh on a new page.
• With Cache Components on, a page you leave is kept hidden with its state, template copy included, and comes back as it was.
• Effects in a template run each time a page shows. Use a template for per-page state and per-page Effects; use a layout for the rest.
• A named slot, a folder starting with @ like @offer, shows its default.tsx on a fresh load of an address it has no page for. Without one, this shop's build stopped.

Coming next: Server Components in Next.js. It starts the stage about where your code runs, with the kind of component every layout, template and page starts as.