Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 72 ยท Routing

Route Groups and Private Folders

Organize an App Router project without changing URLs: use (group) folders for shared layouts and multiple root layouts, and _private folders to keep files out of routing.

In the App Router, folders are URLs. That is great for small sites, but real projects have a marketing area, a shop, an account section and an admin panel, and the folder tree turns into a pile of unrelated pages. Worse, you sometimes want a layout for only some of the pages at the same level, or a different <html> shell for a different part of the site, and a folder cannot do that without adding a segment to the URL.

Next.js has two small naming conventions that solve the problem. A folder wrapped in parentheses, like (shop), is a route group: it organizes files and can own a layout, but it adds nothing to the URL. A folder that starts with an underscore, like _components, is a private folder: it is excluded from routing entirely. This lesson covers both, and ends with the one trap you should know about, which is what happens when two groups define their own root layout. It builds on File-Based Routing and Pages and Layouts.

Real framework or stand-in? The folder names and code in the tsx and text blocks are real Next.js and read-only. The two live examples are plain JavaScript stand-ins that apply the same naming rules to a list of file paths. They show you the result of the rules; they are not the real compiler.

Two folder tricks

(group) Organizes and can own a layout. Not in the URL.
_private Never becomes a route, even with a page.tsx.

Parentheses hide the folder name. An underscore hides the folder.

1 / 2

Route groups

Wrap a folder name in parentheses and Next.js ignores that segment when it builds the URL. Here is a site with two areas:

TEXT
app/
  (marketing)/
    layout.tsx          marketing shell
    page.tsx            -> /
    about/
      page.tsx          -> /about
  (shop)/
    layout.tsx          shop shell
    products/
      page.tsx          -> /products
    cart/
      page.tsx          -> /cart

The visitor never sees (marketing) or (shop). The URLs are /, /about, /products and /cart. What the groups do give you:

  • Organization. Your editor shows the marketing pages together and the shop pages together. The names are for people.
  • A layout for a subset of pages. app/(shop)/layout.tsx wraps /products and /cart, but not /about. Without a group you would need a shared parent folder, which would add a URL segment (for example /shop/products).
  • Section-specific special files. A loading.tsx or error.tsx inside a group applies only to that group's pages. See loading.tsx, error.tsx and not-found.tsx.
  • Several root layouts, covered next.

Groups can be nested ((shop)/(account)/orders/page.tsx is just /orders) and can sit at any level, even in the middle of a path: app/docs/(guides)/install/page.tsx is /docs/install.

One rule keeps you out of trouble: two groups must not produce the same URL. If (marketing)/pricing/page.tsx and (shop)/pricing/page.tsx both exist, they both claim /pricing, and Next.js reports a conflict at build time. Since the group name disappears, the folder path after the groups is what has to be unique.

Layouts for a subset of pages

A group layout is a normal layout: it receives children and wraps everything below it. This one adds a store navigation bar to the shop pages only:

TSX
// app/(shop)/layout.tsx (read-only)
import Link from 'next/link';

export default function ShopLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <nav aria-label="Store">
        <Link href="/products">Products</Link>
        <Link href="/cart">Cart</Link>
      </nav>
      {children}
    </>
  );
}

/about is in a different group, so it never gets this bar. Notice that nothing about the URL changed: this is the whole point of a group.

Multiple root layouts

Every App Router app needs a root layout, the top-most layout, which must render the <html> and <body> tags. Normally that is app/layout.tsx. If you delete app/layout.tsx and put a layout with <html> and <body> in each group instead, every group becomes its own root:

TSX
// app/(marketing)/layout.tsx (read-only)
export default function MarketingRoot({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className="marketing">{children}</body>
    </html>
  );
}
TSX
// app/(shop)/layout.tsx (read-only)
export default function ShopRoot({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className="shop">{children}</body>
    </html>
  );
}

This is useful when the two areas truly differ: different fonts, a different lang, a different theme, or a landing site that should not load the app's heavy providers. The price is real, though. Navigating between two different root layouts cannot be done by swapping the content of the page, because the <html> element itself changes. Next.js therefore does a full page load (a normal browser navigation) instead of its usual client-side transition. Inside one root layout, links stay fast and layouts keep their state.

Two more details:

  • If a group's layout lives below a root layout that already exists, it is an ordinary layout. Only the layout at the top of a page's chain is the root.
  • A page has to end up with exactly one root layout. A group without a layout and without a root above it is an error.

The first live example computes, for a list of files, which layouts wrap each page and whether moving from one URL to another is a client-side navigation or a full page load. You can read the rule in the code: compare the outermost layout of the two pages.

Node.js Which layouts wrap a page, and what does navigation cost?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

/orders has two layouts, the shop root and the nested (account) layout, so the account area can add its own sidebar while still sharing the shop shell. The two navigations that cross from the marketing group to the shop group are full page loads, because their outermost layouts are different files.

If the two areas do not need a different <html> element, keep a single app/layout.tsx and use groups only for nested layouts. You then get all the organization with none of the full-page loads.

Private folders

A route is only public when a folder contains a page.tsx (or route.ts). So a components folder next to your pages is already safe: without those files, nothing in it is reachable. Why would you need private folders, then?

  • A private folder (name starts with _) is skipped by the router completely, even if it contains a page.tsx. This makes the intent explicit and protects you from the accidental case, such as a prototype page you forgot about.
  • It separates UI logic from routing in the editor, so _components, _lib and _actions sit clearly apart from route folders.
  • It avoids name clashes with future Next.js file conventions, because the underscore marks "this is ours".
TEXT
app/
  blog/
    page.tsx             -> /blog
    _components/
      post-card.tsx      not routable
      page.tsx           not routable either (private)
    _lib/
      load-posts.ts      not routable
    [slug]/
      page.tsx           -> /blog/anything

If you really want a URL that starts with an underscore, write the folder name as %5Ffolder (the URL-encoded underscore). That is rare, but it exists.

Private folders are optional: many teams keep components in a top-level components/ directory outside app/, or place small helper files directly next to the page that uses them. Colocation is safe either way, because only page and route files are public.

Seeing the rules

The second stand-in applies the three rules (only page.tsx and route.ts count, _private folders are skipped, (groups) disappear) to a list of files, and reports URL conflicts. Run it, then add or remove files in the list to experiment.

Node.js From file tree to public URLs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first report shows the clean list: /, /about, /products, /cart and /api/health. The _drafts page is private, and card.tsx is just a file next to a page. In the second report, the two pricing pages claim the same URL, which is the conflict Next.js stops at build time.

Choosing a structure

A practical recipe for medium projects:

  1. Use one root layout (app/layout.tsx) with your fonts, providers and <html> unless two areas really need different shells.
  2. Add groups when a subset of pages needs its own layout, loading state or error boundary, or just to keep the tree readable.
  3. Use _private folders for components, helpers and actions that belong to a route and should never be a URL.
  4. Keep an eye on duplicate URLs when two teams own two groups.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. app/(shop)/cart/page.tsx is served at which URL?

    A folder in parentheses is a route group. It organizes files and can own a layout, but its name is not part of the URL.
  2. 2. What does a folder named _components containing a page.tsx do?

    Folders that start with an underscore are opted out of the router. Use %5F in the folder name if you need a literal underscore in a URL.
  3. 3. Why do app/(marketing)/pricing/page.tsx and app/(shop)/pricing/page.tsx cause a problem?

    The group names disappear from the URL, so the path after them has to be unique. Next.js reports the conflict instead of choosing one.
  4. 4. Your app has no app/layout.tsx, and two groups each render their own html and body. What happens when a visitor clicks a link from one group to the other?

    The html element belongs to the root layout, so moving between two root layouts cannot be a partial update. Next.js performs a normal browser navigation.
  5. 5. Which is the best reason to use a route group inside an app that has a single root layout?

    Groups let you attach layouts and special files to a subset of routes while keeping URLs untouched. Making a page private is the job of underscore folders.

Summary

  • (group) folders organize routes, can own layouts and special files, and add nothing to the URL.
  • Two groups must not resolve to the same URL; Next.js reports the conflict.
  • Removing app/layout.tsx and giving each group its own <html>/<body> layout creates multiple root layouts; navigating between them is a full page load.
  • _private folders are never routes, even with a page.tsx; use %5F to put a literal underscore in a URL.
  • Only page and route files make a folder public, so colocating components and helpers is safe.
  • Prefer one root layout plus groups for nested layouts unless two areas truly need different shells.

Next: Linking and Navigation