Chapter 15: Routing Concepts

Core Idea

TanStack Router builds a nested route tree from route segments, each with well-defined semantics (index, dynamic, splat, optional, layout, pathless, non-nested, excluded, grouped), that together let you express nearly any URL structure declaratively.

Key Concepts

• createFileRoute(path): Defines a route in file-based routing; the path string argument is auto-managed by the Router Bundler Plugin/CLI and is what gives TypeScript the context needed for type safety.
• Root Route: Created with createRootRoute() (or createRootRouteWithContext<T>() for typed router context). Has no path, is always matched, and its component always renders as the outermost wrapper.
• Basic Route: Matches an exact path (e.g. /about).
• Index Route: Matches its parent exactly when no child matches; declared with a trailing slash, e.g. createFileRoute('/posts/').
• Dynamic Segment ($param): A path segment prefixed with $ (e.g. $postId) captures that URL part into params, accessible via Route.useParams() or in a loader.
• Splat/Catch-All Route ($): A route whose path is just $ captures the rest of the URL into params._splat (or params['*'] in v1 for backward compatibility).
• Optional Path Parameter ({-$param}): Segment that may or may not be present in the URL; matches with the param as undefined when absent. Multiple optional params can be chained. Ranked lower priority than exact matches.
• Layout Route: A route (e.g. app.tsx) that wraps children with a shared component via <Outlet />, and can enforce loaders, search param validation, and shared context on all children.
• Pathless Layout Route (_prefix): Wraps children without adding a URL segment; the part after _ becomes the route's required unique ID. Cannot contain dynamic segments directly (the dynamic segment must be a separate path segment).
• Non-Nested Route (parent_.child): A trailing underscore on the parent segment un-nests a route from its parent's component tree, e.g. posts_.$postId.edit.tsx renders standalone, not nested inside <Posts>.
• Excluded Files (-prefix): Files/folders prefixed with - are ignored by route generation, letting you colocate non-route logic (e.g. -components/) and import from it in route files.
• Pathless Route Group ((group)): Parenthesized directories are purely organizational, do not affect the route tree/URL/component tree.

Code Examples

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/{-$category}')({
  component: PostsComponent,
})

function PostsComponent() {
  const { category } = Route.useParams()
  return <div>{category ? `Posts in ${category}` : 'All Posts'}</div>
}

• What it demonstrates: An optional path parameter matching both /posts and /posts/tech.

Key Takeaways

1. Dynamic segments ($param) work independently at every path segment; splat routes ($ alone) grab everything remaining into _splat.
2. Use pathless layout routes (_prefix) to share layout/loader/context logic without adding a URL segment, and non-nested routes (parent_.child) to break out of a parent's component tree when needed.
3. File organization tools (excluded files with -, grouping directories with ()) let you colocate code and organize routes without affecting the generated route tree.

Connects To

• Ch 16: Route Trees, which composes these concepts into a full tree.
• Ch 17: Route Matching, which explains the precedence order these route types are matched in (index > static > dynamic > splat).
• Ch 21: File Naming Conventions, for the full syntax reference of prefixes/suffixes described here.