Route groups

An interactive explainer of Next.js route groups: how folders in parentheses leave the URL, share layouts, opt pages in and out, and isolate loading and error states.

The problem

Every page on this site sits inside one root layout that draws the header, the page frame and the footer. I want /contact to be just a name, a picture and four links, so it has to escape all of that without breaking anything else.

What the docs say

Read from the Next docs that ship in node_modules/next/dist/docs, since this version has breaking changes.

  • Layouts don't re-render on navigation. They keep their state and stay interactive while the page inside them changes. (Layouts and Pages.)
  • So a layout can't read the current path. The docs say layouts don't access the pathname because it would go stale. To use the path, read it in a Client Component with usePathname(). (Layout file convention.)
  • Route groups are folders in parentheses. They organise files and add nothing to the URL, and they can opt some pages into a layout while keeping others out. (Route Groups.)
  • Multiple root layouts are allowed, with a catch. Navigating between two different root layouts triggers a full page load instead of a soft navigation. (Route Groups, Layout file convention.)
  • Two groups can't claim the same URL, and without a top-level layout the home route has to live inside one of the groups.
  • loading, error and not-found are folder conventions, and a route group is a folder. The docs show a loading.tsx moved into an (overview) group so only the overview page gets the skeleton. (Project structure.)
  • Within one segment the order is layout, template, error, loading, not-found, page, each wrapping the next. So error.tsx and loading.tsx don't wrap the layout beside them. A broken root layout needs global-error.tsx, which brings its own html and body. (error.js, loading.js, not-found.js.)
  • With several root layouts there's no single layout to build a 404 from, which is what the experimental global-not-found.js is for. One root layout with nested groups doesn't need it. (not-found.js.)

Try it

Toy models of those rules, not Next itself. One tab per idea.

Bump the counters, then click between routes. Then switch to two root layouts and cross from /notes to /contact to see what the full page load costs.

Go to
Setup
app/layout.tsx<html> and <body>, fonts, metadata
app/(site)/layout.tsxheader, footer, page frame
app/(site)/about/page.tsx

Bump a counter, then click a route. Whatever survives kept its state.

The plan

Keep one root layout for the html and body, and put the chrome in a nested layout for one group. That's an ordinary nested layout, so navigating between the groups stays a soft navigation. Only separate root layouts reload the page.

Before

text
src/app/
├── layout.tsx          html, body, header, footer, page frame
├── page.tsx            /
├── about/page.tsx      /about
├── notes/page.tsx      /notes
└── contact/page.tsx    /contact (still wrapped in all the chrome)

After

text
src/app/
├── layout.tsx          html, body, fonts, metadata. Nothing visual.
├── (site)/
│   ├── layout.tsx      header, footer, page frame
│   ├── page.tsx        /
│   ├── about/page.tsx  /about
│   └── notes/page.tsx  /notes
└── (bare)/
    └── contact/page.tsx  /contact, with no chrome at all

The route sync already skips group folders when working out a page's URL, and pages are identified by the ID on their first line, so moving files doesn't change any page's identity.

The cheaper alternative

Because a client component can read the path, a small component in the root layout could simply render the chrome only on paths that aren't in a list of bare ones. It's smaller, but the root layout then has to know about specific pages.

Route groupsA client component that hides the chrome
HowChrome lives in (site)/layout.tsx; bare pages sit in a group without itA small client component in the root layout calls usePathname() and renders the chrome only on non-bare paths
Chrome in the HTML of bare pagesNoneNone (it renders nothing on those paths)
CostMove about 40 page folders into (site), and fix each CSS module's @reference depthA few lines, nothing moves
New bare page laterCreate a folder in (bare)Add its path to a list
Layout in the right placeYes: the folder says which pages have chromeNo: the root layout knows about specific pages
Page URLsUnchangedUnchanged
  • Layouts with route groups

    The plan to give each kind of page its own layout with Next.js route groups: (site), (notes) with a left notes aside, (bare), and (artifacts) for self-contained HTML files.

  • Table stress

    Tables with very wide cells, long unbroken words and many columns, to check how they scroll and wrap.

  • Code stress test

    Absurdly long identifiers, strings, paths, and files in inline code and code blocks.

  • Blue tester

    Candidate blues side by side across headings, links, and text.