Dynamic Routes & Route Groups

The Bookshelf book page is the canonical [slug]-style route. The segment is called id because the data layer looks books up by id, but the shape is identical to the official [slug] example:

PageProps<'/[locale]/books/[id]'> is a globally available type helper (the next sections explain it). The segment [locale] above is also a param, so the page receives { locale, id }, not just { id }: a route’s params holds every dynamic segment from the root to the page.

Source: Dynamic Segments: Convention

A static folder next to a dynamic one wins for its own URL. The Bookshelf has books/new/page.tsx beside books/[id]/page.tsx:

So /en/books/new is the form page and is never captured as id = 'new'. In the same experiment a sibling catch-all books/[...all] lost to [id] for /en/books/2 and won for /en/books/2/extra: a static folder beats a dynamic one, which beats a catch-all, so you can add specific pages next to a general route without restructuring it.

Source: Dynamic Route Segments

The Bookshelf shelf is a hierarchy of unknown depth (fiction/sci-fi, non-fiction/science, and so on). A catch-all route captures it as an array:

/en/shelf is a 404 because a plain catch-all needs at least one segment. The decodeURIComponent call is deliberate: in Next.js 16.3.8 the values are handed over percent-encoded (see Pitfalls and Errors).

Source: Catch-all Segments

For the Bookshelf documentation, one file serves /en/docs and every deeper page:

An optional catch-all claims the bare path, so a sibling docs/page.tsx would resolve to the same route. Next.js refuses it at build time:

Delete the extra page.tsx and branch on slug === undefined instead.

Source: Optional Catch-all Segments

The book page above is the case: an async component, await params, destructure. The same holds for layouts and for generateMetadata, which also receives params as a Promise:

Route Handlers get their params through a second argument typed with RouteContext:

Source: page.js, route.js

A Client Component page receives the same Promise. React’s use API unwraps it; because a Client Component cannot be async, await is not available. The Bookshelf reviews page is a Client Component, for instance because it will hold interactive state:

Source: Dynamic Segments: In Client Components, use

use(params) only works where the Promise was passed down as a prop. A breadcrumb inside the layout needs the same values without receiving a prop, which is what the useParams hook is for. It is a Client Component hook that returns the params of the current URL:

useParams returns an object whose keys are the active dynamic segments; each value is a string, or an array of string for catch-all segments; a route with no dynamic segments gives {}. In the Pages Router the same hook returns null on the first render until the router is ready (it was introduced in 13.3.0).

Source: useParams

Under the previous model, awaiting params anywhere is fine. With cacheComponents: true the rule changes, and the rule depends on whether generateStaticParams covers the route. Without it, the param values are unknown while prerendering, so reading them is runtime data and must sit inside a <Suspense> boundary or the build fails. The documented pattern is to pass the Promise down and await it in a child:

Without the Suspense boundary the same build stops with this error (verified on 16.3.8):

useParams follows the same rule: when every param of the route is known at build time (a static route, or one covered by generateStaticParams) it needs no boundary; for params not covered it suspends, and the call site needs <Suspense> or the build fails with blocking-prerender-client-hook. In a layout, do not await params at the top level: that blocks the layout from being prerendered. Pass the Promise to the component that needs it instead.

Source: Dynamic Segments: With Cache Components, blocking-prerender-dynamic, blocking-prerender-client-hook

A URL path is text, and nothing in a folder name such as [id] says "number", so Next.js never converts: id is '1', never 1. The contract also runs the other way. Returning numbers from generateStaticParams passes the TypeScript step and then stops the build:

A string for a catch-all fails the same way (A required parameter (slug) was not provided as an array received string). Map ids with String(book.id).

The helper types come from .next/types/routes.d.ts, which next build, next dev and next typegen write. It is keyed by the route pattern without route groups:

So every group layout of the Bookshelf is typed LayoutProps<'/[locale]'>, like the root layout (there is no (shop) entry to choose), and the literal for a page is the pattern printed by next build.

Source: Layout Props Helper, generateStaticParams

A param is typed string, but most have a much smaller set of valid values. The documented approach is runtime validation with an assertion function: invalid values go to notFound(), and the rest of the code works with the narrower type. This is also the security rule for the whole page: a param is user input. Validation scattered over pages drifts, so the Bookshelf keeps the rules in one server module that pages, layouts, generateMetadata and Route Handlers call before touching data. The root layout calls assertLocale, so /fr/…​ is a 404 before any page runs; the book page calls parseId (a zod schema such as z.string().regex(…​) works just as well):

Source: Dynamic Segments: TypeScript, PageProps helper, notFound

Why a pattern and not Number(id)? Number('1e3') is 1000, Number('') is 0 and parseInt('1abc', 10) is 1: each turns a junk URL into a real book page and a separate cache entry. The nine-digit cap stays below Number.MAX_SAFE_INTEGER. Spellings the pattern does accept, such as 01, are sent to the canonical URL with permanentRedirect (308), so search engines and the ISR cache see one URL per book. Narrowing works because notFound() and permanentRedirect() throw and are typed never.

Check per-page params (id, slug) in the page, not a layout: a layout does not re-run on a soft navigation between its children. And give generateMetadata the same guard, or it can build a <title> from an invalid value.

Never interpolate a raw param into a query string, a file path or a command: a slug captured into an fs path allows .. tricks (see Special Characters in Segments: Encoding and Decoding), and a slug concatenated into a GROQ or SQL query allows injection. The consulted e-commerce book, for instance, interpolates the slug into a CMS query; the correct form passes it as a query parameter.

The same generated types also check the other direction: with typedRoutes: true, a link such as /${locale}/book/${id} (a typo for books) fails the TypeScript step of next build with TS2322, while /${locale}/books/${id} passes. Prefer template literals for links to dynamic routes; a concatenated string is not checked and needs an as Route cast. The option is covered in Configuration, TypeScript and Environment Variables.

Source: TypeScript: Statically Typed Links

You can generate params for segments above the current file, never below. Two approaches work. Bottom up: the leaf page returns every combination at once. Top down: the parent layout returns its own segment and the child’s generateStaticParams runs once per parent value, receiving what the parent generated:

The build table above lists /en/authors/herbert/dune, /en/authors/herbert/children-of-dune and /en/authors/gibson/neuromancer (and the three es twins). Inside a nested generateStaticParams a root parameter can also be read directly with its next/root-params getter instead of destructuring it from params.

What happens for a value that generateStaticParams did not return is controlled by the dynamicParams route segment config (it replaces the fallback: true | false | 'blocking' option of the Pages Router’s getStaticPaths):

The Bookshelf book page prerenders ids 1 and 2. With the default dynamicParams = true, id 3 renders on demand, and the second request is already a cache hit. Setting dynamicParams = false makes id 3 a 404:

To prerender nothing at build time and everything on first visit, return an empty array. The first request is a cache MISS that renders and stores the page, the second a HIT (the response headers below come from a build whose generateStaticParams returns []):

You must always return an array, even an empty one; otherwise the route is dynamically rendered. (export const dynamic = 'force-static' is the other documented way to get the same first-visit ISR.)

With cacheComponents: true the contract of generateStaticParams changes. It supplies samples: param values used at build time to run the route and validate that it accesses runtime data correctly. The rules, all verified on 16.3.8:

The Bookshelf book page under Cache Components. generateStaticParams keeps the two samples, the param read moves into a child under <Suspense>, and notFound() still works:

Id 1 is a cache hit (prerendered), id 3 is rendered on the first request, and id 99 answers 200 — not 404 — because the shell, with its Loading book... fallback, has already been sent when notFound() runs inside the streamed boundary. Handle this with a noindex meta tag or by validating before the boundary (see Pitfalls and Errors).

A layout’s generateStaticParams can supply the samples for everything below it, but in this experiment a Client Component page below a layout that had the samples still failed the Cache Components build with the unresolved [id] placeholder. The fix was a thin Server Component page.tsx that exports generateStaticParams and passes the params Promise to the Client Component:

The route table of that build marks the routes ◐ Partial Prerender (static shell plus streamed content) instead of ●. With partialPrefetching: true as well, 16.3 adds ISR with App Shell: a visit to a URL whose params were not generated is answered instantly with the App Shell and upgraded in the background; later visits get the cached full page. It is the Cache Components equivalent of fallback: true in the Pages Router.

Source: generateStaticParams, dynamicParams, ISR with Cache Components, empty-generate-static-params

A catch-all answers URLs of every depth, so here generateStaticParams and dynamicParams interact least intuitively. The caching mechanics are covered in Static Site Generation: dynamicParams, Static Site Generation: with Cache Components and Incremental Static Regeneration; this subsection shows only which URLs exist. Each entry describes one full URL as an array; for an optional catch-all, the empty array stands for the bare path:

At request time the bare path still arrives as slug: undefined, not [] (the page printed data-slug="null" for /en/docs), so branch on !slug?.length. Then both pages got export const dynamicParams = false;:

With dynamicParams = false a catch-all is not a prefix match: the parent /en/shelf/fiction and the child /en/shelf/fiction/sci-fi/x of a generated path are both 404. If the parent levels of a hierarchy are pages too, return them as samples (['fiction'] as well as ['fiction', 'sci-fi']). The same build with Cache Components (cacheComponents: true, no dynamicParams) marked the sample paths ○ and the routes ◐; /en/shelf/fiction answered x-nextjs-cache: MISS and then HIT, /en/docs was a HIT and /en/shelf a 404:

Under Cache Components, unknown catch-all paths can only be rejected in your code (notFound() after validating the decoded segments, with the status caveat above). Build-time validation covers only the branches the samples execute, so include one sample per depth that takes a different code path.

Source: generateStaticParams: Catch-all Dynamic Segment, generateStaticParams: disable rendering for unspecified paths, Dynamic Segments: With Cache Components

A route inherits every layout on its folder path, and there is no "skip the parent layout" switch. A route group is how you give a layout to some siblings without inventing a URL segment. In the URL map, (shop) holds the shop navigation, (account) the account navigation (in the full Bookshelf it also runs the session check of the Data Access Layer), and (marketing) a plain wrapper. (checkout) has no layout: to remove checkout from the shop chrome you do not configure checkout, you move it next to (shop) instead of inside it. The probe confirms it: /en/checkout returns 200 with no data-group="shop" element.

The same move scopes loading.tsx, error.tsx and not-found.tsx to one route. Groups are only needed at the same level: books/new/page.tsx never sees books/[id]/layout.tsx, because it is not below that folder.

Source: Route Groups: Use cases, layout.js

Groups and dynamic segments decide which layouts React keeps mounted on a client-side navigation. To see it, the (shop), books/[id] and (account) layouts each render a StateProbe, a Client Component (in app/[locale]/_components/) whose button shows a useState click counter. In Chromium against the production server, a script clicked the shop counter twice and the book counter once, set window.__marker, then followed the links:

A final router.push('/es/books') kept window.__marker and updated <html lang> to es in place.

Source: Layouts and Pages, Route Groups: Caveats

A group costs nothing in the URL, so it can follow the organisation chart: one group per team or feature, each with its own layout and error UI, and a CODEOWNERS entry per group:

(CODEOWNERS does not support [ ] ranges, hence the *.) The router’s only constraint is that two groups must not define the same URL.

The segment hooks do report group folders, which matters for breadcrumbs and analytics labels:

The documented filter removes the groups; a catch-all is one joined string (fiction/sci-fi). The segment hooks are covered in Linking and Navigation.

Source: useSelectedLayoutSegments, GitHub: About code owners

Delete the top-level layout.tsx and give each group a layout that renders <html> and <body>. Each group is then a separate application shell. The experiment used a (shop) and a (marketing) group at the top of app/:

(/cart lives in (shop); /blog, /about and / live in (marketing).) Three caveats are real constraints, not style advice:

Also, a root layout is only a root layout when nothing above it declares <html>. The first attempt at the Bookshelf experiment kept a stale app/layout.tsx next to app/[locale]/layout.tsx; next/root-params then had no locale export, because [locale] was not above the root layout. Remove the old file so that app/[locale]/layout.tsx is the root layout.

Source: Route Groups, Root layout

To measure the "full page load" caveat, a second variant deleted app/[locale]/layout.tsx and gave each group a layout with <html> and <body> (and the locale generateStaticParams). The same browser script ran against both builds; the navigation entry is performance.getEntriesByType('navigation')[0].name, which changes only when the browser loads a new document:

Crossing root layouts discarded the JavaScript state, the React tree and the router cache, like a plain <a href>.

So keep one root layout for areas users move between all the time (the Bookshelf’s catalogue, account and checkout), and reserve one root layout per group for areas they rarely cross, such as a public site and an admin console that needs a different <html>, theme or analytics. With several roots, a root parameter missing from some of them is typed string | undefined by next/root-params. The file-level rules are in Layouts, Templates and Special Files.

Source: Route Groups: Caveats, Root layout

In the Pages Router the route params and the query string arrive in one object. The URL map app also had a pages/legacy/[id].tsx whose getServerSideProps returned ctx.params and ctx.query as props, and which rendered them next to useRouter().query; a sibling pages/legacy/[...slug].tsx rendered its ctx.params:

Four behaviours differ from the App Router:

Source: useRouter: router object, useRouter: resetting state after navigation, Pages Router: Dynamic Routes

Source: Pages Router: Dynamic Routes, getStaticPaths, useRouter