React Router File Routes

Complete reference for React Router v7 file-based routing conventions and file naming patterns.

Core Concepts

React Router v7 uses file-based routing where file names in app/routes/ directory automatically become routes. Special characters in file names create specific routing behaviors.

File Naming Conventions

Basic Routes

File Name	URL Path	Description
_index.tsx	/	Index route at the root or parent path
about.tsx	/about	Simple static route
contact.tsx	/contact	Another static route

Nested Routes with Dots

Dots (.) create nested URL paths and establish parent-child relationships.

File Name	URL Path	Parent Layout
concerts.tsx	/concerts	root.tsx
concerts._index.tsx	/concerts	concerts.tsx
concerts.trending.tsx	/concerts/trending	concerts.tsx
concerts.$city.tsx	/concerts/:city	concerts.tsx
settings.profile.tsx	/settings/profile	root.tsx
settings.profile.edit.tsx	/settings/profile/edit	root.tsx

Example structure:

app/
├── routes/
│   ├── _index.tsx
│   ├── concerts.tsx              # Layout for /concerts/*
│   ├── concerts._index.tsx       # Renders at /concerts
│   ├── concerts.trending.tsx     # Renders at /concerts/trending
│   └── concerts.$city.tsx        # Renders at /concerts/:city
└── root.tsx

Dynamic Segments

Prefix with $ to create URL parameters.

File Name	URL Path	Params
blog.$slug.tsx	/blog/:slug	{ slug: string }
users.$userId.tsx	/users/:userId	{ userId: string }
teams.$teamId.projects.$projectId.tsx	/teams/:teamId/projects/:projectId	{ teamId: string, projectId: string }

Access params in component:

import type { Route } from "./+types/blog.$slug";

export async function loader({ params }: Route.LoaderArgs) {
  // params.slug is available here
}

export default function Component({ params }: Route.ComponentProps) {
  return <div>Post: {params.slug}</div>;
}

Optional Segments

Append ? to make a segment optional (works with both static and dynamic segments).

File Name	URL Path	Matches
$lang.categories.tsx	/:lang?/categories	/categories and /en/categories
users.$userId.edit.tsx	/users/:userId/edit?	/users/123 and /users/123/edit

Pathless Layout Routes

Prefix with _ (underscore) to create layouts that don't affect the URL structure.

File Name	URL Path	Layout Parent
_auth.tsx	N/A (pathless)	root.tsx
_auth.login.tsx	/login	_auth.tsx
_auth.register.tsx	/register	_auth.tsx

Example structure:

app/
├── routes/
│   ├── _auth.tsx                 # Pathless layout
│   ├── _auth.login.tsx          # URL: /login (wrapped in _auth layout)
│   ├── _auth.register.tsx       # URL: /register (wrapped in _auth layout)
│   └── dashboard.tsx            # URL: /dashboard (not wrapped in _auth)
└── root.tsx

Escaping Layouts with Trailing Underscore

Suffix with _ to create a nested URL without inheriting parent layout.

File Name	URL Path	Layout Parent
concerts.tsx	/concerts	root.tsx
concerts.trending.tsx	/concerts/trending	concerts.tsx
concerts_.mine.tsx	/concerts/mine	root.tsx (skips concerts.tsx)

Splat Routes (Catch-All)

Use $ to create catch-all routes that match remaining URL segments.

File Name	URL Path	Params
files.$.tsx	/files/*	{ "*": string }
$.tsx	/*	{ "*": string } (404 catch-all)

Access splat params:

export async function loader({ params }: Route.LoaderArgs) {
  const filePath = params["*"]; // Everything after /files/
  return getFileInfo(filePath);
}

Escaping Special Characters

Use [] brackets to escape special characters and include them literally in URLs.

File Name	URL Path	Purpose
sitemap[.]xml.tsx	/sitemap.xml	Resource route with extension
blog[$slug].tsx	/blog/$slug	Literal $slug in URL (not a param)
about[.].tsx	/about.	Literal dot in URL

Complete File Structure Examples

Standard Nested Routes

app/
├── routes/
│   ├── _index.tsx           # /
│   ├── about.tsx            # /about
│   ├── concerts.tsx         # /concerts layout
│   ├── concerts._index.tsx  # /concerts
│   ├── concerts.$city.tsx   # /concerts/:city
│   └── concerts.trending.tsx # /concerts/trending
└── root.tsx

Pathless Layout Routes

app/
├── routes/
│   ├── _auth.tsx            # Pathless layout
│   ├── _auth.login.tsx      # /login
│   ├── _auth.register.tsx   # /register
│   └── dashboard.tsx        # /dashboard
└── root.tsx

Mixed Layouts

app/
├── routes/
│   ├── _index.tsx              # /
│   ├── concerts.tsx            # /concerts layout
│   ├── concerts._index.tsx     # /concerts
│   ├── concerts.trending.tsx   # /concerts/trending
│   └── concerts_.mine.tsx      # /concerts/mine (skips layout)
└── root.tsx

Quick Reference

Pattern	File Example	URL Result	Notes
Simple route	about.tsx	/about	Static route
Nested path	a.b.c.tsx	/a/b/c	Dots create slashes
Index route	concerts._index.tsx	/concerts	Default child route
Dynamic segment	blog.$slug.tsx	/blog/:slug	Creates param
Multiple params	$a.$b.tsx	/:a/:b	Multiple dynamic segments
Optional segment	$lang?.about.tsx	/about or /:lang/about	Optional param
Pathless layout	_auth.login.tsx	/login	Uses _auth.tsx layout
Escape layout	parent_.child.tsx	/parent/child	Skips parent.tsx layout
Splat route	files.$.tsx	/files/*	Catches all after /files/
Escape chars	api[.]json.tsx	/api.json	Literal . in URL

Common Patterns

Authentication Routes

_auth.tsx              # Shared auth layout
_auth.login.tsx       # /login
_auth.register.tsx    # /register
_auth.forgot.tsx      # /forgot

Admin Dashboard

_admin.tsx                    # Admin layout
_admin._index.tsx            # /admin
_admin.users.tsx             # /admin/users
_admin.users.$userId.tsx     # /admin/users/:userId

Blog with Categories

blog.tsx                     # Blog layout
blog._index.tsx             # /blog
blog.$slug.tsx              # /blog/:slug
blog.category.$cat.tsx      # /blog/category/:cat

Resource Routes

api.json.tsx                # /api/json
sitemap[.]xml.tsx          # /sitemap.xml
robots[.]txt.tsx           # /robots.txt

scripts/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Examples from other skills:

• PDF skill: fill_fillable_fields.py, extract_form_field_info.py - utilities for PDF manipulation
• DOCX skill: document.py, utilities.py - Python modules for document processing

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

Note: Scripts may be executed without loading into context, but can still be read by Codex for patching or environment adjustments.

references/

Documentation and reference material intended to be loaded into context to inform Codex's process and thinking.

Examples from other skills:

• Product management: communication.md, context_building.md - detailed workflow guides
• BigQuery: API reference documentation and query examples
• Finance: Schema documentation, company policies

Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Codex should reference while working.

assets/

Files not intended to be loaded into context, but rather used within the output Codex produces.

Examples from other skills:

• Brand styling: PowerPoint template files (.pptx), logo files
• Frontend builder: HTML/React boilerplate project directories
• Typography: Font files (.ttf, .woff2)

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

---

Not every skill requires all three types of resources.