Chapter 21: File Naming Conventions

Core Idea

File-based routing depends on a small, precise set of filename tokens and prefixes/suffixes; getting these right is what makes route generation produce the intended route tree.

Key Concepts

• __root.tsx: The mandatory root route filename, must live at the root of the configured routesDirectory.
• . Separator: Denotes nesting in flat-file routes, e.g. blog.post.tsx is generated as a child of blog.
• $ Token: Marks a parameterized route segment, extracting that URL part into params (e.g. posts.$postId.tsx).
• _ Prefix: Marks a pathless layout route; excluded from URL matching for children but still wraps them.
• _ Suffix: Excludes a route from being nested under any parent route (non-nested route), e.g. posts_.$postId.edit.tsx.
• - Prefix: Excludes files/folders from the route tree entirely; useful to colocate non-route logic (components, helpers) inside route folders without it becoming a route.
• (folder) Route Group: A folder name wrapped in parentheses is purely organizational and does not appear in the URL path.
• [x] Escaping: Square brackets escape characters that would otherwise have routing meaning, e.g. script[.]js.tsx → /script.js, api[.]v1.tsx → /api.v1.
• index Token: A segment ending in index (before extensions) matches its parent route exactly; configurable via the indexToken option (string or regex).
• .route.tsx File Type: When using directories, a route suffix file (e.g. blog/post/route.tsx or blog.post.route.tsx) is used as the route file for that directory's path; configurable via the routeToken option.

Code Examples

Filename              Route Path        Component Output
posts.$postId.tsx     /posts/$postId    <Root><Posts><Post>

Filename          Route Path    Component Output
_app.tsx                        (wraps children, no path)
_app.a.tsx        /a            <Root><App><A>
_app.b.tsx        /b            <Root><App><B>

• What it demonstrates: The $ token producing a dynamic segment, and the _ prefix producing a pathless layout that wraps /a and /b without adding its own URL segment.

Key Takeaways

1. All naming conventions are configurable (e.g. indexToken, routeToken options), so a project can deviate from the defaults documented here if needed.
2. - prefix (exclude from routing) and (folder) route groups (exclude from URL only) solve two different problems: the former hides files from the route tree entirely, the latter only hides a directory from the URL while keeping its children as routes.
3. Square-bracket escaping ([x]) is the way to produce filenames containing literal dots or other routing-significant characters, e.g. for /script.js or /api.v1 style URLs.

Connects To

• Ch 15: Routing Concepts, explains the semantics behind these tokens (pathless layouts, non-nested routes, index routes, etc.).
• Ch 18: File-Based Routing, the broader system these conventions belong to.
• Ch 26: Path Params, dives deeper into dynamic segments introduced by the $ token.