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

Nested Routes with Dots

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

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.

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).

Pathless Layout Routes

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

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.

Splat Routes (Catch-All)

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

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.

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

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.