tanstack-router
/tanstack-router
Type-safe, file-based routing for React with TanStack Router. Use when defining routes with createFileRoute, validating search params with Zod, writing route loaders, setting up auth guards with beforeLoad, integrating TanStack Query into loaders, or configuring router context and preloading.
- Author
- Mindrally ↗
- Repository
- skills ↗
- Licence
- Apache-2.0
- Last repository change
- 08.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Type-safe, file-based routing for React with TanStack Router. Use when defining routes with createFileRoute, validating search params with Zod, writing route loaders, setting up auth guards with beforeLoad, integrating TanStack Query into loaders, or configuring router context and preloading.
Original author description
Type-safe, file-based routing for React with TanStack Router. Use when defining routes with createFileRoute, validating search params with Zod, writing route loaders, setting up auth guards with beforeLoad, integrating TanStack Query into loaders, or configuring router context and preloading.
How it works
- Workflow for Adding a New Route
- Core Principles
- File-Based Route Conventions
- Route Definition
- Type-Safe Search Params
- Navigation
- Loaders + TanStack Query Integration
- Router Context for Dependency Injection
- Auth Guards
- Performance
SKILL.md preview
---
name: tanstack-router
description: "Type-safe, file-based routing for React with TanStack Router. Use when defining routes with createFileRoute, validating search params with Zod, writing route loaders, setting up auth guards with beforeLoad, integrating TanStack Query into loaders, or configuring router context and preloading."
metadata:
maintainer: Mindrally
source: https://github.com/Mindrally/skills
---
# TanStack Router
TanStack Router is a fully type-safe router for React that treats routes, loaders, params, and search params as first-class typed data rather than untyped strings.
## Workflow for Adding a New Route
1. **Create the route file** — Add a file under `src/routes/` following the file-based routing convention (see below).
2. **Define the route** — Export `Route` from `createFileRoute('/path')({...})` with `component`, and optionally `loader`, `validateSearch`, `beforeLoad`, `errorComponent`, and `pendingComponent`.
3. **Validate search params** — If the route reads query params, define a Zod schema and pass it as `validateSearch`.
4. **Load data** — Fetch data in `loader`, not in a component `useEffect`; integrate with TanStack Query via `queryClient.ensureQueryData` when caching is needed.
5. **Guard access** — Add `beforeLoad` checks (e.g. auth) that `throw redirect({ to: '/login' })` when a precondition fails.
6. **Link to the route** — Navigate with `<Link to="/path" params={...} search={...}>` so the compiler validates params and search at every call site.
7. **Regenerate the route tree** — Ensure `routeTree.gen.ts` is regenerated (automatic under the Vite plugin's dev server / build) before running or building the app.
## Core Principles
- TanStack Router is 100% type-safe — lean on TypeScript generics for params, search params, and loader data instead of manual casting.
- Prefer file-based routing with `@tanstack/router-vite-plugin` (or `@tanstack/router-plugin/vite`) for scalability over manually constructed route trees.
- Always define routes with `createFileRoute` (leaf/nested routes) or `createRootRoute` / `createRootRouteWithContext` (root).
- Route data loading belongs in `loader` functions, not in component `useEffect` — this enables preloading, parallel loading, and pending/error states.
- Search params are first-class state — always define their schema with Zod (or another standard-schema validator) so they are typed and validated on every read.
## File-Based Route Conventions
```
src/routes/
__root.tsx ← Root layout
index.tsx ← / route
posts/
index.tsx ← /posts
$postId.tsx ← /posts/:postId (dynamic segment)
_layout.tsx ← Layout route (no path segment)
_auth/ ← Pathless auth layout group
dashboard.tsx
```
- A leading underscore on a segment (`_layout`, `_auth`) creates a pathless layout route used purely for grouping/shared UI.
- A `$` prefix (`$postId`) marks a dynamic path segment, matching `Route.useParams()`.
- `index.tsx` inside a folder matches the folder's own path with no additional segment.
## Route Definition
```tsx
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => fetchPost(params.postId),
component: PostComponent,
errorComponent: ({ error }) => <ErrorBanner message={error.message} />,
pendingComponent: () => <PostSkeleton />,
})
function PostComponent() {
const post = Route.useLoaderData() // type-safe
const { postId } = Route.useParams() // type-safe
return <div>{post.title}</div>
}
```
- `errorComponent` renders when the loader throws; `pendingComponent` renders while the loader is in flight (subject to `defaultPendingMs`).
- Loader return values and thrown errors are both fully typed and flow into `useLoaderData()` and `errorComponent` respectively.
## Type-Safe Search Params
- Always define search params with Zod and `validateSearch`.
- Access them with `Route.useSearch()` — never read `window.location.search` or `URLSearchParams` directly, which bypasses type safety and validation.
```tsx
const searchSchema = z.object({
page: z.number().int().min(1).default(1),
q: z.string().optional(),
})
export const Route = createFileRoute('/search')({
validateSearch: searchSchema,
component: SearchPage,
})
function SearchPage() {
const { page, q } = Route.useSearch()
const navigate = Route.useNavigate()
return (
<button onClick={() => navigate({ search: (prev) => ({ ...prev, page: page + 1 }) })}>
Next page
</button>
)
}
```
## Navigation
- Use `<Link>` for internal navigation — never a raw `<a href>`, which triggers a full page reload and loses client-side routing state.
- Always pass typed `params` and `search`; the TypeScript compiler catches missing or mistyped route params at build time.
```tsx
<Link to="/posts/$postId" params={{ postId: '123' }}>View Post</Link>
<Link to="/search" search={{ page: 1, q: 'react' }}>Search</Link>
```
## Loaders + TanStack Query Integration
- Put the `QueryClient` in router context so loaders can prefetch and cache through TanStack Query rather than duplicating fetch logic.
- Use `ensureQueryData` (not `fetchQuery`) in loaders so an already-cached query is reused instead of refetched.
```tsx
export const Route = createFileRoute('/posts')({
loader: ({ context: { queryClient } }) =>
queryClient.ensureQueryData(postsQueryOptions()),
component: PostsPage,
})
function PostsPage() {
const { data: posts } = useSuspenseQuery(postsQueryOptions())
return <PostList posts={posts} />
}
```
## Router Context for Dependency Injection
```tsx
// __root.tsx
interface RouterContext {
queryClient: QueryClient
auth: AuthState
}
export const Route = createRootRouteWithContext<RouterContext>()({
component: RootLayout,
})
// main.tsx
const router = createRouter({ routeTree, context: { queryClient, auth } })
```
- Router context flows down to every route's `loader` and `beforeLoad` via the `context` argument, giving each route typed access to shared dependencies without prop drilling or global singletons.
## Auth Guards
```tsx
export const Route = createFileRoute('/_auth/dashboard')({
beforeLoad: ({ context }) => {
if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
},
component: Dashboard,
})
```
- `beforeLoad` runs before the loader and before the component renders, making it the right place for auth checks, feature flag gates, and redirects.
- Prefer `throw redirect(...)` over imperative navigation inside components — it works during SSR, preloading, and client navigation alike.
## Performance
- Set `defaultPreload: 'intent'` on the router so links prefetch their route's data on hover/focus, making navigation feel instant.
- Use `React.lazy` (or the router's built-in code-splitting via `.lazy()` route files) for route component code splitting on large apps.
- Install `@tanstack/router-devtools` and render `<TanStackRouterDevtools />` in development to inspect route matches, pending states, and cache.
## Common Mistakes
- Fetching data with `useEffect` inside a route component instead of a `loader`, which loses preloading and creates render-then-fetch waterfalls.
- Reading raw `window.location.search` instead of `Route.useSearch()`, bypassing the search param schema and type safety.
- Performing auth checks only inside components (`useEffect` redirect) instead of `beforeLoad`, allowing a flash of protected content before redirecting.
- Forgetting to add new route params/search fields to `<Link>` call sites — let the compiler catch it rather than testing manually.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Mindrally/skills | 100 | Apache-2.0 |
| TerminalSkills/skills | 100 | Apache-2.0 |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| secondsky/claude-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 0f7432c9dc3d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100react-tanstack-router
Use when implementing routing in a React app (NOT Next.js) with TanStack Router — file-based routes, loaders, search params. - 100tanstack
Type-safe React with TanStack Query (fetching, caching, mutations), Router (file-based routing, search params, loaders), and Start (SSR, server functions). Use for react-query, server state, typed search params, route loaders, or SSR. - 90TanStack Router
Expert guidance for TanStack Router including file-based routing, type-safe navigation, route loaders, search params, nested routes, and lazy loading. Use this when building type-safe React applications with client-side routing. - 100use-tanstack
Answer questions and write code for TanStack libraries using version-accurate, officially shipped Agent Skills instead of training data. Use when working with any @tanstack/* package or TanStack library: Query (react-query, solid-query, vue-query — useQuery, useMutation,… - 100tanstack-vue-router-skilld
Use when writing, debugging, or refactoring code that imports @tanstack/vue-router (TanStack Router for Vue). Covers setup, file-based and code-based routes, composables returning Ref, Link, loaders, search params, SSR, and v1.170.x deprecations. - 100clerk-tanstack-patterns
TanStack React Start auth patterns with @clerk/tanstack-react-start - createServerFn, beforeLoad guards, loaders, Vite plugin, server middleware. Triggers on: TanStack auth, createServerFn clerk, beforeLoad protection, TanStack Start middleware.