Skill v1.0.1

currentAutomated scan100/100

epicweb-dev/epic-stack/epic-routing

2 files

──Details

PublishedJune 10, 2026 at 11:09 PM

Content Hashsha256:e1bede2b22c0170b...

Git SHAfaaa21779c66

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 11.6 KB)

SKILL.md11.6 KBactive

SKILL.md · 461 lines · 11.6 KB

version: "1.0.1" name: epic-routing description: Guide on routing with React Router and react-router-auto-routes for Epic Stack categories:

routing
react-router
file-based-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:

typescript

// ✅ 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:

typescript

// ✅ 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`:

typescript

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:

typescript

// 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:

typescript

// 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:

typescript

// 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:

typescript

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:

typescript

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:

typescript

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

typescript

// 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

typescript

// 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

typescript

// 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

typescript

// 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

← v1.0.0 All versions

Skill v1.0.1

Epic Stack: Routing

When to use this skill

Patterns and conventions

Routing Philosophy

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

Route Groups

Route Parameters

Nested Layouts with _layout.tsx

Resource Routes (Routes without UI)

Loaders and Actions

Search Params

Code Co-location

Naming Conventions

Common examples

Example 1: Create a basic route with layout

Example 2: Route with dynamic parameter

Example 3: Resource route for download

Example 4: Route with multiple nested parameters

Common mistakes to avoid

References

Nested Layouts with `_layout.tsx`