netlify TanStack Start Routes
TanStack Start uses file-based routing with TanStack Router. Routes are defined as files in the src/routes directory.
When to Use
- Adding new pages to your application
- Setting up nested layouts
- Configuring route parameters
- Creating pathless layout routes
- Organizing route structure
Directory Structure
src/
├── routes/
│ ├── __root.tsx # Root layout (required)
│ ├── index.tsx # Home page (/)
│ ├── about.tsx # About page (/about)
│ ├── posts.tsx # Posts layout (/posts)
│ ├── posts.index.tsx # Posts index (/posts)
│ ├── posts.$postId.tsx # Dynamic post (/posts/:postId)
│ ├── _auth.tsx # Pathless layout (no URL segment)
│ ├── _auth.login.tsx # Login under auth layout (/login)
│ └── _auth.register.tsx # Register under auth layout (/register)
├── router.tsx # Router configuration
└── routeTree.gen.ts # Auto-generated route tree
Root Route
The root route wraps all other routes and defines the document shell:
// src/routes/__root.tsx
import {
Outlet,
createRootRoute,
HeadContent,
Scripts
} from '@tanstack/react-router';
import type { ReactNode } from 'react';
export const Route = createRootRoute({
head: () => ({
meta: [
{ charSet: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
{ title: 'My App' },
],
}),
component: RootComponent,
});
function RootComponent() {
return (
<html>
<head>
<HeadContent />
</head>
<body>
<Header />
<main>
<Outlet />
</main>
<Scripts />
</body>
</html>
);
}
function Header() {
return (
<header>
<nav>
<Link to="/">Home</Link>
<Link to="/about">About</Link>
<Link to="/posts">Posts</Link>
</nav>
</header>
);
}
Basic Route
// src/routes/about.tsx
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/about')({
component: AboutComponent,
});
function AboutComponent() {
return (
<div>
<h1>About Us</h1>
<p>This is the about page.</p>
</div>
);
}
Index Route
Index routes render when the parent path is matched exactly:
// src/routes/index.tsx (renders at /)
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/')({
component: HomeComponent,
});
function HomeComponent() {
return <h1>Welcome Home</h1>;
}
// src/routes/posts.index.tsx (renders at /posts)
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/posts/')({
component: PostsIndexComponent,
});
function PostsIndexComponent() {
return <h2>Select a post from the list</h2>;
}
Layout Routes
Layout routes wrap child routes with shared UI:
// src/routes/posts.tsx
import { createFileRoute, Outlet, Link } from '@tanstack/react-router';
export const Route = createFileRoute('/posts')({
component: PostsLayoutComponent,
});
function PostsLayoutComponent() {
return (
<div className="posts-layout">
<aside>
<h2>Posts</h2>
<nav>
<Link to="/posts/1">Post 1</Link>
<Link to="/posts/2">Post 2</Link>
</nav>
</aside>
<div className="content">
<Outlet /> {/* Child routes render here */}
</div>
</div>
);
}
Dynamic Route Parameters
Use $paramName for dynamic segments:
// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/posts/$postId')({
component: PostComponent,
});
function PostComponent() {
const { postId } = Route.useParams();
return (
<article>
<h1>Post {postId}</h1>
</article>
);
}
Multiple Parameters
// src/routes/users.$userId.posts.$postId.tsx
// Matches: /users/123/posts/456
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/users/$userId/posts/$postId')({
component: UserPostComponent,
});
function UserPostComponent() {
const { userId, postId } = Route.useParams();
return <div>User {userId}'s Post {postId}</div>;
}
Pathless Layout Routes
Prefix with _ for layouts that don't add URL segments:
// src/routes/_auth.tsx
// This creates a layout but adds no URL segment
import { createFileRoute, Outlet, redirect } from '@tanstack/react-router';
export const Route = createFileRoute('/_auth')({
beforeLoad: async ({ context }) => {
// Redirect if already authenticated
if (context.user) {
throw redirect({ to: '/dashboard' });
}
},
component: AuthLayout,
});
function AuthLayout() {
return (
<div className="auth-container">
<div className="auth-card">
<Outlet />
</div>
</div>
);
}
// src/routes/_auth.login.tsx
// Renders at /login (not /_auth/login)
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/_auth/login')({
component: LoginComponent,
});
function LoginComponent() {
return <form>Login Form</form>;
}
Catch-All (Splat) Routes
Use $ for catch-all routes:
// src/routes/files.$.tsx
// Matches: /files/any/path/here
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/files/$')({
component: FilesComponent,
});
function FilesComponent() {
const { _splat } = Route.useParams();
// _splat = "any/path/here"
return <div>File path: {_splat}</div>;
}
404 Not Found Route
// src/routes/__root.tsx
import { createRootRoute } from '@tanstack/react-router';
export const Route = createRootRoute({
component: RootComponent,
notFoundComponent: NotFoundComponent,
});
function NotFoundComponent() {
return (
<div>
<h1>404 - Page Not Found</h1>
<Link to="/">Go Home</Link>
</div>
);
}
Route Configuration Options
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/posts/$postId')({
// Component to render
component: PostComponent,
// Error boundary component
errorComponent: ErrorComponent,
// Loading/pending component
pendingComponent: LoadingComponent,
// Not found component (for this route)
notFoundComponent: NotFoundComponent,
// Validate and parse params
parseParams: (params) => ({
postId: parseInt(params.postId, 10),
}),
// Serialize params back to strings
stringifyParams: (params) => ({
postId: String(params.postId),
}),
// Validate search params
validateSearch: (search) => ({
page: Number(search.page) || 1,
}),
});
File Naming Conventions
| File Name | Route Path |
|---|---|
index.tsx |
/ |
about.tsx |
/about |
posts.tsx |
/posts (layout) |
posts.index.tsx |
/posts (index) |
posts.$postId.tsx |
/posts/:postId |
posts.$postId.edit.tsx |
/posts/:postId/edit |
_layout.tsx |
Pathless layout |
_layout.page.tsx |
/page with layout |
files.$.tsx |
/files/* (catch-all) |
Directory vs Flat Routes
Both styles work and can be mixed:
Flat (dot notation):
routes/
├── posts.tsx
├── posts.index.tsx
└── posts.$postId.tsx
Directory style:
routes/
└── posts/
├── route.tsx # Layout
├── index.tsx # Index
└── $postId.tsx # Dynamic
Router Configuration
// src/router.tsx
import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';
export function getRouter() {
const router = createRouter({
routeTree,
scrollRestoration: true,
defaultPreload: 'intent',
defaultPreloadStaleTime: 0,
});
return router;
}
declare module '@tanstack/react-router' {
interface Register {
router: ReturnType<typeof getRouter>;
}
}
Common Patterns
Protected Routes
// src/routes/_protected.tsx
import { createFileRoute, redirect } from '@tanstack/react-router';
export const Route = createFileRoute('/_protected')({
beforeLoad: async ({ context }) => {
if (!context.user) {
throw redirect({
to: '/login',
search: { redirect: location.href },
});
}
},
component: ProtectedLayout,
});
Route Groups (Organization Only)
Use parentheses for grouping without affecting URLs:
routes/
├── (marketing)/
│ ├── about.tsx # /about
│ └── pricing.tsx # /pricing
└── (app)/
├── dashboard.tsx # /dashboard
└── settings.tsx # /settings