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.$queryRaw`SELECT 1`, // 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 (
        <div>
            <input
                value={query}
                onChange={(e) => setSearchParams({ q: e.target.value })}
            />
            {/* Results */}
        </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