Route groups and private folders

Round brackets keep a folder out of the address

In File-system routing, each ordinary folder on the way to a page added one segment to the address: app/teas/page.tsx was the page for /teas. That works until you want to sort your folders in a way the address shouldn't show. The tea shop has pages for shopping, like the teas and the cart, and pages about the shop, like About. You want them in two folders, but you don't want addresses like /shop/teas.

A folder whose name is in round brackets, like (shop), is a route group. It sorts the files inside it, but it isn't part of the address. Here is the shop with two groups. 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. Click through its files, then its pages.

1export default function TeasPage() {2  return (3    <main>4      <h1>Our teas</h1>5      <ul>6        <li>Green tea: $4</li>7        <li>Mint tea: $3</li>8      </ul>9    </main>10  );11}

The file shown first, app/(shop)/teas/page.tsx, is the same teas page as before: line 1 exports it, and line 4 is its heading, Our teas. Only its place changed. It now sits in (shop), next to cart, and about sits in (info). app/page.tsx and the root layout, app/layout.tsx, stay at the top, outside both groups.

Open the Terminal tab. The route table that next build prints lists ○ /, ○ /_not-found, ○ /about, ○ /cart and ○ /teas. The ○ means "prerendered as static content": each page was made once, during the build. There's no (shop) and no (info) in any address. In the Browser tab, pick /shop/teas and /(shop)/teas: both answered 404, the page for addresses that don't exist. The group's name isn't in the address, with round brackets or without.

Each row is one page file of this shop: the group it's in, and the address the build gave it.

A layout for each section

Sorting files is only half of what groups do. The bigger reason is layouts. A layout.tsx in a folder goes around every page in that folder and in the folders below it (the Layouts and pages lesson shows layouts in full). Without groups, a layout for only the teas and the cart would need a folder they share, and that folder would add a segment: /shop/teas. A group gives them a folder to share with no segment.

Here, each group gets a layout. The shop's pages get a line about delivery, and the info pages get the opening hours at the bottom. A checkout page is added outside both groups:

1export default function ShopLayout({ children }: LayoutProps<"/">) {2  return (3    <>4      <p>Free delivery on orders over $20.</p>5      {children}6    </>7  );8}

In app/(shop)/layout.tsx, line 4 is the delivery line, and line 5, {children}, is where the page goes. In app/(info)/layout.tsx, line 4 places the page first and line 5 puts the opening hours under it. Line 1 of each types the props with LayoutProps<"/">, a type Next.js writes for you. The route it names is "/", not "/(shop)", because the group adds nothing to the address. Exercise 4 shows what the type check says otherwise.

Now pick each page in the Browser tab. /teas and /cart show Free delivery on orders over $20. above the page. /about shows Open every day, 9 to 5. under it. /checkout and / show only the root layout's links. The Terminal tab still lists plain addresses, with ○ /checkout added. Each row is one recorded page, with what goes around it, from the outside in:

This is also how you keep one page out of a layout that its neighbors share. The checkout page shouldn't tempt anyone to keep shopping, so it sits outside (shop). Try both places. Before you click, guess what /checkout shows in each:

1export default function CheckoutPage() {2  return (3    <main>4      <h1>Checkout</h1>5      <p>Enter your address to finish your order.</p>6    </main>7  );8}

Inside (shop), the checkout page gets the delivery line. Outside it, it doesn't. Its address is /checkout both times. Moving a folder in or out of a group changes which layouts go around its pages, and never their addresses.

One address, one page

Groups don't add segments, so two pages in two groups can end up with the same address. Say the shop wants a page about its teas in (shop), and puts it in about/page.tsx there too. Both files would be /about. Pick the second version to see what next build does with that:

1export default function AboutPage() {2  return (3    <main>4      <h1>About us</h1>5      <p>Asha and Ravi run the shop.</p>6    </main>7  );8}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (7/7)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ○ /about├ ○ /cart├ ○ /checkout└ ○ /teas ○  (Static)  prerendered as static content

The build stops with You cannot have two parallel pages that resolve to the same path. "Resolve to the same path" means both page files would answer the same address. Next.js doesn't pick one for you. Each address must belong to exactly one page, so give the second page an address of its own, like app/(shop)/teas/about/page.tsx for /teas/about.

Two root layouts in one app

The root layout is the layout at the top of the app. It's the one that writes <html> and <body>, and every page sits inside it. So far, that was app/layout.tsx. To be exact, a root layout is any layout with no other layout above it. Delete app/layout.tsx and give each group a layout with its own <html> and <body>, and the app has two root layouts.

That's useful when parts of one app look completely different. Here, the shop gets a blog called Tea notes, with its own header and its own page title:

1import Link from "next/link";2 3export const metadata = { title: "Tea notes" };4 5export default function BlogRootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <header>10          <p>Tea notes, a blog from the tea shop</p>11          <Link href="/">Back to the shop</Link>12        </header>13        {children}14      </body>15    </html>16  );17}

The file shown first is app/(blog)/layout.tsx. Line 3 gives the blog's pages the title Tea notes, lines 7 and 8 open its own <html> and <body>, and line 11 links back to the shop. In app/(shop)/layout.tsx, the same lines make the shop's document, with the title Tea shop on line 3 and the links Home, Teas and Blog on line 10. There's no app/layout.tsx. The home page moved into the group too, as app/(shop)/page.tsx, so that a root layout goes around it. In the Browser tab, / and /teas have the shop's links, and /blog has the blog's header.

Moving between the two has a cost. Inside one root layout, a click on a Link is a client-side navigation: the page's JavaScript swaps in the new page, and the layout and everything else on the screen stay (How Next.js works showed this). Between two root layouts that's impossible: the old <html> can't stay, because the new page needs its own. So Next.js does a full page load instead: the browser asks for a whole new HTML document and starts over, as if you typed the address.

This example was also clicked through in real Chrome. The Steps tab below lists four steps: open /, click Teas, click Blog, and click Back to the shop. Each step shows the page after it and the requests the page made, without the script and style files. It opens on step 3.

1import Link from "next/link";2 3export const metadata = { title: "Tea notes" };4 5export default function BlogRootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <header>10          <p>Tea notes, a blog from the tea shop</p>11          <Link href="/">Back to the shop</Link>12        </header>13        {children}14      </body>15    </html>16  );17}

• Step 1, open /: one request for a whole page, GET /, and then requests marked text/x-component. Those are prefetches: the page's JavaScript asking early for the linked pages, /teas and /blog, before anyone clicks. Both are ○ pages, made during the build, so the prefetches bring all of them.
• Step 2, click Teas: no requests at all. /teas shares the shop's root layout, and its prefetch had already arrived, so the page was swapped in place.
• Step 3, click Blog: GET /blog, marked a whole page. /blog was prefetched in step 1 too, but it has another root layout, so Next.js loaded it as a new document.
• Step 4, click Back to the shop: the same again the other way: GET /, a whole page.

A full page load means the browser runs the page's JavaScript again from the start, and anything only kept in the browser, like a half-typed form or a Client Component's state, is gone. Within the shop, or within the blog, nothing changes. So split an app into root layouts only where visitors rarely cross, like a shop and its blog, or a public site and a signed-in app. Next.js makes this decision by comparing the two routes' root layouts, in is-navigating-to-new-root-layout.ts if you want to read it.

Private folders: _folder

Project structure gave a first look at the other special folder name: a folder whose name starts with an underscore, like _components, is a private folder. Next.js leaves it out of routing, with every folder and file inside it. Here the teas page draws each tea with a card from its own private folder, and someone left a preview page in there too:

1import TeaCard from "./_components/tea-card";2 3export default function TeasPage() {4  return (5    <main>6      <h1>Our teas</h1>7      <ul>8        <TeaCard name="Green tea" price={4} />9        <TeaCard name="Mint tea" price={3} />10      </ul>11    </main>12  );13}

Line 1 of app/(shop)/teas/page.tsx imports TeaCard from ./_components/tea-card, and lines 8 and 9 draw a card for each tea. The /teas page shows Green tea: $4 and Mint tea: $3, so the import works like any other.

Now pick /teas/_components/preview. There's a page.tsx at app/(shop)/teas/_components/preview/page.tsx, two folders down, and still the server answered 404. So did /teas/_components/tea-card. The route table in the Terminal tab has no address with _components in it. An underscore at the start of a folder's name switches off routing for everything inside it, page files and route.ts files too.

The last address, /_help, answered 200 with the help page. What if you really want an address that starts with an underscore? Write the underscore as %5F, the way URLs write it in code: the folder app/%5Fhelp is the address /_help, and the build lists ○ /_help.

Now the same folder without its underscore. Guess first: does the preview page get an address?

1export default function CardPreview() {2  return (3    <main>4      <h1>Tea card preview</h1>5    </main>6  );7}

Without the underscore, components is an ordinary folder, and its page.tsx made a page anyone can open, at /teas/components/preview. That's the mistake a private folder rules out.

You don't need a private folder to keep a component beside a page: a tea-card.tsx straight in teas never gets an address either, as File-system routing showed. Private folders are still worth it:

• They keep the folders that make routes apart from the folders that hold your code, so a glance tells them apart.
• A stray page.tsx or route.ts inside one never becomes a route, as the preview page showed.
• Their names all start with _, so editors list them together.
• No file in one can clash with a special file name, like loading.tsx, including names Next.js adds in later versions.

Three ways to place your own files

Keeping a file next to the code that uses it is called colocation. Next.js doesn't mind where your components and data live, so teams pick a pattern. Each row is one of the three common ones:

The patterns mix well. Here is the tea shop using all three: the logo in components beside app, the teas in a private folder at the top of app, and the tea card in a private folder beside the teas page.

app/
  (info)/
    about/
      page.tsx
    layout.tsx
  (shop)/
    cart/
      page.tsx
    teas/
      _components/
        tea-card.tsx
      page.tsx
    layout.tsx
  _lib/
    teas.ts
  checkout/
    page.tsx
  layout.tsx
  page.tsx
components/
  logo.tsx

(info) and (shop) sort the pages and hold their layouts. _lib/teas.ts is shared data that any page can import, and teas/_components/tea-card.tsx belongs to the teas page alone. components/logo.tsx sits outside app. The next section runs this shop. Whichever pattern you choose, use it across the whole project, so everyone knows where to look.

The whole tea shop, organized

Here is the organized shop, built and run. The file shown first is the teas page:

1import { teas } from "@/app/_lib/teas";2import TeaCard from "./_components/tea-card";3 4export default function TeasPage() {5  return (6    <main>7      <h1>Our teas</h1>8      <ul>9        {teas.map((tea) => (10          <TeaCard key={tea.id} name={tea.name} price={tea.price} />11        ))}12      </ul>13    </main>14  );15}

Line 1 imports the teas from @/app/_lib/teas. @/ means the project's top folder, set in tsconfig.json. Line 2 imports the card from the private folder beside the page, and line 10 draws one for each tea. In app/layout.tsx, line 2 imports the logo from components.

Open the Terminal tab: the route table is /, /_not-found, /about, /cart, /checkout and /teas, the same addresses as before the shop was organized. In the Browser tab, /teas and /about work, each with its group's layout, and /_lib/teas and /components/logo answered 404. Organizing the files changed nothing a visitor can see.

Now sort the folder names from this lesson: which ones become part of an address?

Common mix-ups

• "A route group adds its name to the address." No. /shop/teas and /(shop)/teas answered 404; the page is /teas.
• "Two groups can each have their own /about." No. Both would be /about, and the build stops.
• "A group's layout goes around every page." No. Only around the pages inside the group: /checkout didn't get the shop's layout.
• "Moving between root layouts is a normal client-side navigation." No. Clicking Blog loaded /blog as a whole new page.
• "A page.tsx inside a private folder still makes a page." No. /teas/_components/preview answered 404.
• "A file in a private folder is hidden from the browser." No. It only has no address. A Client Component that imports it sends its code to the browser.

Each row is one kind of folder name: whether it becomes part of the address, and whether its pages can be visited.

Practice exercises

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

app/
  (info)/
    about/
      page.tsx
  (shop)/
    cart/
      page.tsx
    teas/
      page.tsx
  layout.tsx
  page.tsx

app/
  (shop)/
    teas/
      _components/
        preview/
          page.tsx
        tea-card.tsx
      page.tsx

app/
  (info)/
    about/
      page.tsx
    layout.tsx
  (shop)/
    cart/
      page.tsx
    teas/
      page.tsx
    layout.tsx
  checkout/
    page.tsx
  layout.tsx
  page.tsx

export default function ShopLayout({ children }: LayoutProps<"/(shop)">) {
  return (
    <>
      <p>Free delivery on orders over $20.</p>
      {children}
    </>
  );
}

export default function ShopLayout({ children }: LayoutProps<"/">) {
  return (
    <>
      <p>Free delivery on orders over $20.</p>
      {children}
    </>
  );
}

app/
  (blog)/
    blog/
      page.tsx
    layout.tsx
  (shop)/
    teas/
      page.tsx
    layout.tsx
    page.tsx
  about/
    page.tsx

export default function AboutPage() {
  return (
    <main>
      <h1>About us</h1>
      <p>Asha and Ravi run the shop.</p>
    </main>
  );
}

app/
  _help/
    page.tsx
  layout.tsx
  page.tsx

export default function HelpPage() {
  return (
    <main>
      <h1>Help</h1>
      <p>Write to us if a box arrives late.</p>
    </main>
  );
}

Check your understanding

Key takeaways

• A folder in round brackets, like (shop), is a route group. It sorts routes and never shows in the address: app/(shop)/teas/page.tsx is /teas.
• A layout.tsx in a group goes around the pages in that group only. Move a folder in or out to choose its layouts.
• Two groups can't both make the same address: the build stops.
• Without app/layout.tsx, each group can have its own root layout. Every page needs one, and moving between two root layouts is a full page load.
• A folder starting with _ is private: nothing inside it is a route. %5F gives a real underscore in the address.
• No address doesn't mean secret: keep secrets in code that only runs on the server.

Coming next: Loading UI. It shows loading.tsx, the file that shows a loading state while a page waits for its data.