菜单
Create and manage routes in TanStack Start using file-based routing. Use when adding new pages, configuring layouts, setting up nested routes, or working with route parameters.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use content-collections for type-safe content management with markdown files. Use when building blogs, documentation sites, or any content-driven pages with frontmatter and markdown.
Handle Netlify Forms in TanStack Start. Use when implementing contact forms, signup forms, or any form submission handling on Netlify-hosted TanStack Start sites.
Create API routes (server routes) in TanStack Start for handling HTTP requests. Use when building REST APIs, webhooks, or any HTTP endpoint that returns data rather than rendering a page.
Upgrade a stock TanStack Start project to use Netlify Identity for authentication via the @netlify/identity package. Use this skill whenever the user wants to add Netlify Identity auth to a TanStack Start app, integrate login/signup into TanStack Start, protect routes or server functions with Netlify Identity, add role-based access control, or wire up Netlify Identity webhooks. Also use when the user mentions '@netlify/identity', 'nf_jwt', or asks about auth for TanStack Start on Netlify. Covers SSR pages, SPA pages, API routes, server functions, middleware, route guards, role-based access, identity webhooks, and client-side auth state.
Load data for TanStack Start routes using beforeLoad and loader functions. Use when fetching data for pages, implementing route guards, or setting up route context. IMPORTANT - Loaders should call server functions for data access.
Set up and configure TanStack Start projects. Use when creating new projects, configuring the router, setting up TanStack Query integration, or configuring build settings.
基于 SOC 职业分类
| name | tanstack-start-routes |
| description | Create and manage routes in TanStack Start using file-based routing. Use when adding new pages, configuring layouts, setting up nested routes, or working with route parameters. |
| license | Apache-2.0 |
| metadata | {"author":"tanstack","version":"1.0"} |
TanStack Start uses file-based routing with TanStack Router. Routes are defined as files in the src/routes directory.
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
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>
);
}
// 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 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 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>
);
}
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>
);
}
// 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>;
}
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>;
}
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>;
}
// 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>
);
}
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 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) |
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
// 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>;
}
}
// 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,
});
Use parentheses for grouping without affecting URLs:
routes/
├── (marketing)/
│ ├── about.tsx # /about
│ └── pricing.tsx # /pricing
└── (app)/
├── dashboard.tsx # /dashboard
└── settings.tsx # /settings