Route groups as module boundaries: per-domain shells, colocation, and the full-reload tax

The URL is not your module system

The app router maps folders to URL segments, which quietly couples your code organization to your public information architecture: if /pricing and /dashboard/billing must live at those URLs, their code apparently must live at those paths. Route groups break the coupling. A folder named in parentheses — (marketing), (app), (admin) — is stripped from the URL entirely: app/(marketing)/pricing/page.tsx still serves /pricing. That makes groups pure organization, which is exactly what a module boundary needs to be: you can carve a 214-folder flat namespace into domains owned by squads — one CODEOWNERS line per group — without a single redirect, and refactor incrementally because the URL space never notices. Each group can carry its own layout.tsx, loading.tsx, and error.tsx, so a group is not just a folder: it is a scope for the rendering shell, the suspense boundary, and the error boundary of one domain.

Per-group root layouts and the reload tax

The strongest version of the boundary is deleting the top-level app/layout.tsx and giving each group its own root layout — each one rendering the html and body tags itself. Now marketing gets a static shell: fonts, the analytics script, zero client providers. The app group gets the session provider, sidebar chrome, and theme context. In the SaaS above, moving providers and the analytics bundle out of the marketing shell took landing-page first-load JS from 212 kB to 89 kB — the marketing pages stopped paying for a dashboard they never render.

The price is structural, not incidental: navigating across root layouts cannot be a client-side transition. The router patches the part of the tree below the shared layout, and when even the html element differs there is nothing shared to patch — Next falls back to a full document navigation. Every piece of client state dies with the document: context values, in-memory caches, an open toast, a half-typed form living in a provider. The transition costs a network round-trip plus full hydration — roughly 0.5–1.5 s on mid-tier mobile against ~100 ms for a client navigation. The design rule falls out directly: cut root layouts only along seams users rarely cross mid-session. Marketing to app is crossed once, at login — a fine place to pay a reload. Dashboard to settings is crossed forty times a day — if that pair lands in different root layouts, the group cut is wrong.

Colocation, private folders, and earning promotion

Only page.tsx and route.ts create URLs, so colocating non-route files next to the routes that use them is safe by default. The convention worth enforcing is the underscore: _components/, _lib/ — private folders that are opted out of routing entirely, a loud signal that everything inside belongs to this route and nothing else. The discipline has two halves. First: code lives next to the only route that uses it — a checkout-only price formatter lives in (checkout)/_lib/, not in a global utils file. Second: shared code must earn promotion out. A reasonable bar: used by two or more domains, has a named owner, has its own tests — then it moves to shared/ (or, later, a workspace package). The payoff is an invariant senior teams prize: deleting a route folder deletes its UI, dead code cannot hide. The failure mode of skipping this is the one from the hook — app/components/ as a 200-file commons where every PR conflicts, nothing can be deleted because nobody knows who imports it, and duplicate components breed because search returns 40 candidates.

Conventions do not compile — lint the direction

Here is the mechanism honesty that the docs will not volunteer: route groups and private folders change zero module-resolution semantics. Any file can import any other file across groups; TypeScript resolves it, the bundler ships it, CI stays green. The architecture diagram where (billing) never reaches into (admin) is a wish until a tool fails the build. The standard tool is an ESLint boundary rule:

// eslint.config.js — import/no-restricted-paths zones
{
  rules: {
    'import/no-restricted-paths': ['error', {
      zones: [
        // domains may not import each other — only shared/
        { target: './app/(app)', from: './app/(marketing)' },
        { target: './app/(marketing)', from: './app/(app)' },
        { target: './app/(admin)', from: './app/(app)' },
        // shared/ may not import upward into any domain
        { target: './src/shared', from: './app' },
      ],
    }],
  },
}

Groups import from shared/; never sideways into each other; shared/ imports from no group — dependencies point one way, downward. With the zones in CI, a sideways import is a red build instead of a review comment someone forgets to leave. This is the only form of architecture that survives 40 engineers shipping in parallel.

Parallel routes: composition for dashboards

One more tool belongs in the modularity kit: parallel routes. A layout can declare slots — @revenue, @alerts, @activity — and receive each as a prop, rendering them side by side; each slot folder carries its own loading.tsx and error.tsx, plus a default.tsx for when the slot has no match. That gives a dashboard exactly what a composed screen of independently owned panels needs: the revenue squad’s panel can stream late or fail without touching the alerts panel, and each squad owns its slot folder outright. The honest scoping: slots add real file-system complexity and subtle soft-navigation behavior — when you reach for them, ask whether the panels genuinely have independent data and error lifecycles, not just independent visual placement.