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.tsxmoved 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.tsxandloading.tsxdon't wrap the layout beside them. A broken root layout needsglobal-error.tsx, which brings its ownhtmlandbody. (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.jsis 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.
app/layout.tsx<html> and <body>, fonts, metadataapp/(site)/layout.tsxheader, footer, page frameapp/(site)/about/page.tsxBump 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
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
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 allThe 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.
Related
- 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.