epic-routing

Epic Stack: Routing

When to use this skill

Use this skill when you need to:

Create new routes or pages in an Epic Stack application
Implement nested layouts
Configure resource routes (routes without UI)
Work with route parameters and search params
Understand Epic Stack's file-based routing conventions
Implement loaders and actions in routes

Patterns and conventions

Routing Philosophy

Following Epic Web principles:

Do as little as possible - Keep your route structure simple. Don't create complex nested routes unless you actually need them. Start simple and add complexity only when there's a clear benefit.

Avoid over-engineering - Don't create abstractions or complex route structures "just in case". Use the simplest structure that works for your current needs.

Example - Simple route structure:

// ✅ Good - Simple, straightforward route // app/routes/users/$username.tsx export async function loader({ params }: Route.LoaderArgs) { const user = await prisma.user.findUnique({ where: { username: params.username }, select: { id: true, username: true, name: true }, }) return { user } }

export default function UserRoute({ loaderData }: Route.ComponentProps) { return <div>{loaderData.user.name}</div> }

// ❌ Avoid - Over-engineered route structure // app/routes/users/$username/_layout.tsx // app/routes/users/$username/index.tsx // app/routes/users/$username/_components/UserHeader.tsx // app/routes/users/$username/_components/UserDetails.tsx // Unnecessary complexity for a simple user page

Example - Add complexity only when needed:

// ✅ Good - Add nested routes only when you actually need them // If you have user notes, then nested routes make sense: // app/routes/users/$username/notes/_layout.tsx // app/routes/users/$username/notes/index.tsx // app/routes/users/$username/notes/$noteId.tsx

// ❌ Avoid - Creating nested routes "just in case" // Don't create complex structures before you need them

File-based routing with react-router-auto-routes

Epic Stack uses react-router-auto-routes instead of React Router's standard convention. This enables better organization and code co-location.

Basic structure:

app/routes/ ├── _layout.tsx # Layout for child routes ├── index.tsx # Root route (/) ├── about.tsx # Route /about └── users/ ├── _layout.tsx # Layout for user routes ├── index.tsx # Route /users └── $username/ └── index.tsx # Route /users/:username

Configuration in app/routes.ts :

import { type RouteConfig } from '@react-router/dev/routes' import { autoRoutes } from 'react-router-auto-routes'

export default autoRoutes({ ignoredRouteFiles: [ '.', '**/.css', '/*.test.{js,jsx,ts,tsx}', '/__.', '/.server.', // Co-located server utilities '/.client.', // Co-located client utilities ], }) satisfies RouteConfig

Route Groups

Route groups are folders that start with _ and don't affect the URL but help organize related code.

Common examples:

_auth/
Authentication routes (login, signup, etc.)
_marketing/
Marketing pages (home, about, etc.)
_seo/
SEO routes (sitemap, robots.txt)

Example:

app/routes/ ├── _auth/ │ ├── login.tsx # URL: /login │ ├── signup.tsx # URL: /signup │ └── forgot-password.tsx # URL: /forgot-password └── _marketing/ ├── index.tsx # URL: / └── about.tsx # URL: /about

Route Parameters

Use $ to indicate route parameters:

Syntax:

$param.tsx → :param in URL
$username.tsx → :username in URL

Example route with parameter:

// app/routes/users/$username/index.tsx export async function loader({ params }: Route.LoaderArgs) { const username = params.username // Type-safe!

const user = await prisma.user.findUnique({
	where: { username },
})

return { user }

}

Nested Layouts with _layout.tsx

Use _layout.tsx to create shared layouts for child routes.

Example:

// app/routes/users/$username/notes/_layout.tsx export async function loader({ params }: Route.LoaderArgs) { const owner = await prisma.user.findFirst({ where: { username: params.username }, }) return { owner } }

export default function NotesLayout({ loaderData }: Route.ComponentProps) { return ( <main className="container"> <h1>{loaderData.owner.name}'s Notes</h1> <Outlet /> {/* Child routes render here */} </main> ) }

Child routes ($noteId.tsx , index.tsx , etc.) will render where <Outlet />

is.

Resource Routes (Routes without UI)

Resource routes don't render UI; they only return data or perform actions.

Characteristics:

Don't export a default component
Export loader or action or both
Useful for APIs, downloads, webhooks, etc.

Example:

// app/routes/resources/healthcheck.tsx export async function loader({ request }: Route.LoaderArgs) { // Check application health const host = request.headers.get('X-Forwarded-Host') ?? request.headers.get('host')

try {
	await Promise.all([
		prisma.user.count(), // Check DB
		fetch(`${new URL(request.url).protocol}${host}`, {
			method: 'HEAD',
			headers: { 'X-Healthcheck': 'true' },
		}),
	])
	return new Response('OK')
} catch (error) {
	return new Response('ERROR', { status: 500 })
}

}

Loaders and Actions

Loaders - Load data before rendering (GET requests) Actions - Handle data mutations (POST, PUT, DELETE)

Loader pattern:

export async function loader({ request, params }: Route.LoaderArgs) { const userId = await requireUserId(request)

const data = await prisma.something.findMany({
	where: { userId },
})

return { data }

}

export default function RouteComponent({ loaderData }: Route.ComponentProps) { return <div>{/* Use loaderData.data */}</div> }

Action pattern:

export async function action({ request }: Route.ActionArgs) { const userId = await requireUserId(request) const formData = await request.formData()

// Validate and process data
await prisma.something.create({
	data: { /* ... */ },
})

return redirect('/success')

}

export default function RouteComponent() { return ( <Form method="POST"> {/* Form fields */} </Form> ) }

Search Params

Access query parameters using useSearchParams :

import { useSearchParams } from 'react-router'

export default function SearchPage() { const [searchParams, setSearchParams] = useSearchParams() const query = searchParams.get('q') || '' const page = Number(searchParams.get('page') || '1')

return (
	&#x3C;div>
		&#x3C;input
			value={query}
			onChange={(e) => setSearchParams({ q: e.target.value })}
		/>
		{/* Results */}
	&#x3C;/div>
)

}

Code Co-location

Epic Stack encourages placing related code close to where it's used.

Typical structure:

app/routes/users/$username/notes/ ├── layout.tsx # Layout with loader ├── index.tsx # Notes list ├── $noteId.tsx # Note view ├── $noteId.edit.tsx # Edit note ├── +shared/ # Code shared between routes │ └── note-editor.tsx # Shared editor └── $noteId.server.ts # Server-side utilities

The + prefix indicates co-located modules that are not routes.

Naming Conventions

_layout.tsx
Layout for child routes
index.tsx
Root route of the segment
$param.tsx
Route parameter
$param_.action.tsx
Route with parameter + action (using _ )
[.]ext.tsx
Resource route (e.g., robots[.]txt.ts )

Common examples

Example 1: Create a basic route with layout

// app/routes/products/_layout.tsx export async function loader({ request }: Route.LoaderArgs) { const categories = await prisma.category.findMany() return { categories } }

export default function ProductsLayout({ loaderData }: Route.ComponentProps) { return ( <div> <nav> {loaderData.categories.map(cat => ( <Link key={cat.id} to={/products/${cat.slug}}> {cat.name} </Link> ))} </nav> <Outlet /> </div> ) }

// app/routes/products/index.tsx export default function ProductsIndex() { return <div>Products list</div> }

Example 2: Route with dynamic parameter

// app/routes/products/$slug.tsx export async function loader({ params }: Route.LoaderArgs) { const product = await prisma.product.findUnique({ where: { slug: params.slug }, })

if (!product) {
	throw new Response('Not Found', { status: 404 })
}

return { product }

}

export default function ProductPage({ loaderData }: Route.ComponentProps) { return ( <div> <h1>{loaderData.product.name}</h1> <p>{loaderData.product.description}</p> </div> ) }

export function ErrorBoundary() { return ( <GeneralErrorBoundary statusHandlers={{ 404: ({ params }) => ( <p>Product "{params.slug}" not found</p> ), }} /> ) }

Example 3: Resource route for download

// app/routes/resources/download-report.tsx export async function loader({ request }: Route.LoaderArgs) { const userId = await requireUserId(request)

const report = await generateReport(userId)

return new Response(report, {
	headers: {
		'Content-Type': 'application/pdf',
		'Content-Disposition': 'attachment; filename="report.pdf"',
	},
})

}

Example 4: Route with multiple nested parameters

// app/routes/users/$username/posts/$postId/comments/$commentId.tsx export async function loader({ params }: Route.LoaderArgs) { // params contains: { username, postId, commentId } const comment = await prisma.comment.findUnique({ where: { id: params.commentId }, include: { post: { include: { author: true }, }, }, })

return { comment }

}

Common mistakes to avoid

❌ Over-engineering route structure: Keep routes simple - don't create complex nested structures unless you actually need them
❌ Creating abstractions prematurely: Start with simple routes, add complexity only when there's a clear benefit
❌ Using React Router's standard convention: Epic Stack uses react-router-auto-routes , not the standard convention
❌ Exporting default component in resource routes: Resource routes should not export components
❌ Not using nested layouts when needed: Use _layout.tsx when you have shared UI, but don't create layouts unnecessarily
❌ Forgetting <Outlet /> in layouts: Without <Outlet /> , child routes won't render
❌ Using incorrect names for parameters: Should be $param.tsx , not :param.tsx or [param].tsx
❌ Mixing route groups with URLs: Groups (_auth/ ) don't appear in the URL
❌ Not validating params: Always validate that parameters exist before using them
❌ Duplicating route logic: Use layouts and shared components, but only when it reduces duplication

References

Epic Stack Routing Docs
Epic Web Principles
React Router Auto Routes
app/routes.ts
Auto-routes configuration
app/routes/users/$username/notes/_layout.tsx
Example of nested layout
app/routes/resources/healthcheck.tsx
Example of resource route
app/routes/_auth/login.tsx
Example of route in route group

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

epic-react-patterns

epic-ui-guidelines

epic-forms