Route Groups

Basic Structure

1src/pages/
2├── (website)/
3│   ├── _layout.tsx
4│   ├── index.tsx        → /
5│   ├── about.tsx        → /about
6│   └── contact.tsx      → /contact
7├── (portal)/
8│   ├── _layout.tsx
9│   ├── dashboard.tsx    → /dashboard
10│   └── tasks.tsx        → /tasks
11└── (auth)/
12    ├── _layout.tsx
13    ├── login.tsx        → /login
14    └── register.tsx     → /register

In the example above, (website), (portal), and (auth) are organizational folders only. They never appear in the browser URL.

Why Use Route Groups

• Split marketing, application, admin, or auth flows without polluting URLs.
• Attach different layouts to different parts of the app.
• Keep feature areas isolated while preserving file-based routing.
• Group future SSR or SSG pages by concern instead of by URL shape.

Layouts and Hierarchy

Layouts are resolved using the real folder structure, including route groups. That means group layouts stay isolated, while the root layout still wraps everything.

1src/pages/
2├── _layout.tsx                    # RootLayout - all pages
3├── (portal)/
4│   ├── _layout.tsx                # PortalLayout - only portal pages
5│   ├── dashboard.tsx              # [RootLayout → PortalLayout]
6│   └── settings/
7│       ├── _layout.tsx            # SettingsLayout - only settings pages
8│       └── profile.tsx            # [RootLayout → PortalLayout → SettingsLayout]
9└── (website)/
10    ├── _layout.tsx                # WebsiteLayout - only website pages
11    └── about.tsx                  # [RootLayout → WebsiteLayout]

Dynamic Routes Inside Groups

Route groups work the same way with dynamic and catch-all routes. Only the folder name in parentheses is removed.

1src/pages/
2└── (portal)/
3    ├── tasks/
4    │   ├── index.tsx      → /tasks
5    │   └── [id].tsx       → /tasks/:id
6    └── docs/
7        └── [...slug].tsx  → /docs/*

Collision Detection

If two files resolve to the same public route, HeliumTS warns and only the first file wins.

1❌ Route collision detected! Multiple files resolve to the same path "/":
2   - /src/pages/index.tsx
3   - /src/pages/(website)/index.tsx
4Only the first file will be used.

Common collision sources are duplicate index.tsx files, repeated filenames across groups, or mixing grouped and non-grouped pages for the same URL.

Best Practices

1. Use the root layout for global providers and chrome.
2. Use group layouts for section-specific navigation, auth gates, or themes.
3. Choose descriptive group names like (marketing), (app), or (admin).
4. Avoid deep nesting unless the UI hierarchy genuinely needs it.