In this lesson

Pathless Routes Route Groups When to Use What Practice Exercise Quick Quiz

Reference

Route Naming Cheat Sheet

Pathless Routes and Route Groups

Lesson 2 — Organizing routes without adding URL segments

You've seen _app/route.tsx wrapping child routes without adding a path segment. Now let's formalize pathless routes and route groups — two tools for organizing your route tree when the URL structure alone isn't enough.

Pathless Routes: The Underscore Prefix

A pathless route wraps its children but does not contribute to the URL. Prefix the folder with _:

routes/ ├── __root.tsx ├── _authenticated/ │ ├── route.tsx → pathless layout │ ├── index.tsx → / │ ├── dashboard/ │ │ └── route.tsx → /dashboard │ └── settings/ │ └── route.tsx → /settings └── login/ └── route.tsx → /login
⚡ Key insight The underscore prefix means "don't add a path segment". _authenticated/route.tsx is a layout route, but /dashboard — not /_authenticated/dashboard — is the URL.

What it's for

Pathless routes are perfect for shared behavior without URL segments:

// routes/_authenticated/route.tsx
import { Outlet, createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  beforeLoad: async ({ context }) => {
    if (!context.user) {
      throw redirect({ to: '/login' })
    }
  },
  component: AuthLayout,
})

function AuthLayout() {
  return (
    <div>
      <Header user={user} />
      <Outlet />  {/* child routes render here */}
    </div>
  )
}

Route Groups: Parentheses Prefix

A route group organizes related routes without affecting URLs. Wrap the folder name in parentheses:

routes/ ├── __root.tsx ├── (marketing)/ │ ├── route.tsx → / │ ├── about/ │ │ └── route.tsx → /about │ └── pricing/ │ └── route.tsx → /pricing └── (app)/ ├── route.tsx → / (CONFLICT!) └── dashboard/ └── route.tsx → /dashboard
⚠️ Warning Route groups do not create layouts. They are purely organizational. If (marketing)/route.tsx and (app)/route.tsx both map to /, TanStack will complain.

What it's for

Route groups are for file organization when you have many routes at the same level:

When to Use What

Pathless Route (_)

✅ Wraps children with a component

✅ Can run code before child loads (beforeLoad)

✅ Adds to the route tree

❌ Adds underscore to folder name

Route Group (( ))

✅ Pure organization, no component

✅ No runtime overhead

❌ Cannot wrap children or run code

❌ Adds parentheses to folder name

Rule of thumb: If you need to share code or UI across routes, use a pathless route. If you just want tidy folders, use a route group.

Practice Exercise

You're building a mobile app with three sections:

  1. Auth section: login, signup, forgot-password — all share a full-screen layout
  2. Main app: home feed, explore, profile — wrapped in bottom tab bar
  3. Settings section: account, notifications, privacy — grouped under /settings with a shared header

Design the route tree. Use pathless routes and route groups appropriately. Then check your answer below.

Show solution
routes/ ├── __root.tsx ├── (auth)/ │ ├── login/ │ │ └── route.tsx → /login │ ├── signup/ │ │ └── route.tsx → /signup │ └── forgot-password/ │ └── route.tsx → /forgot-password ├── _app/ │ ├── route.tsx → pathless layout (bottom tabs) │ ├── index.tsx → / │ ├── explore/ │ │ └── route.tsx → /explore │ └── profile/ │ └── route.tsx → /profile └── settings/ ├── route.tsx → /settings (layout) ├── account/ │ └── route.tsx → /settings/account ├── notifications/ │ └── route.tsx → /settings/notifications └── privacy/ └── route.tsx → /settings/privacy

Why this structure:

Quick Quiz

1. What does _admin/route.tsx do?

Adds /admin to the URL
Wraps children but doesn't add a URL segment
Hides all child routes from the router
The underscore prefix creates a pathless route. Children render inside it, but the route itself doesn't add a path segment.

2. When would you use a route group (marketing)?

When all marketing pages need a shared header component
When you want to organize marketing-related files in a folder without shared UI
When marketing pages should only load after user logs in
Route groups are purely organizational. If you need shared UI or logic, use a pathless route instead.

3. Which URL matches routes/(public)/about/route.tsx?

/(public)/about
/about
/public/about
Route groups don't affect URLs. The parentheses are ignored when building the path.

4. Can a pathless route have child routes?

No — pathless routes can't have children
Yes — children render without the parent's path segment
Yes — but children inherit the underscore prefix
Pathless routes can have children. Children just don't include the parent's path segment in the URL.

5. What happens if you nest route groups like (marketing)/(events)/?

Creates double nested route in URL
Both are ignored — purely organizational
Error — can't nest route groups
Route groups are purely organizational at every level. Nested groups still don't affect URLs.

6. When would you choose a pathless route over a route group?

When you want to organize many files
When you need shared UI or logic across routes
When you want to hide routes from the URL
Use pathless routes when you need to wrap children with a component or run code (like auth checks). Use route groups for file organization only.

7. How do pathless routes differ from Next.js route groups?

They're the same concept
Pathless routes add UI/logic, groups organize files
Next.js doesn't have route groups
In Next.js, (group) is for pathless layouts. In TanStack, _folder is pathless (with UI) and (folder) is organizational only.

8. Which file structure uses a pathless route for authentication?

routes/auth/login/route.tsx
routes/_auth/login/route.tsx
routes/(auth)/login/route.tsx
The underscore prefix _auth creates a pathless route. URLs like /login render inside it, but /_auth is not in the URL.

9. Can you mix pathless routes and route groups in the same app?

No — choose one approach
Yes — they serve different purposes
Yes — but they must be at the same level
Pathless routes and route groups work together. Use groups to organize files, pathless routes to wrap with UI/logic.

10. What's the URL for routes/_app/(routes)/dashboard/route.tsx?

/_app/dashboard
/dashboard
/app/dashboard
Both _app (pathless) and (routes) (route group) are ignored. The URL is just /dashboard.
← Lesson 1: Directory Routing Basics Lesson 3: Dynamic Routes & Splats →
🎓 Stuck on something?
Ask your teacher anything — when to use pathless routes vs route groups, how to refactor an existing route tree, or how this applies to your specific app structure.