tanstack-router

Original：🇺🇸 English

Translated

Type-safe, file-based React routing with route loaders, search params validation, code splitting, preloading, navigation, route context, and TanStack Query integration. Use when setting up file-based routing, adding search params validation, implementing route loaders, code splitting routes, configuring virtual file routes, protecting routes with auth guards, or fixing type registration errors. Use for router setup, navigation patterns, URL state management, data loading.

2installs

Sourceoakoss/agent-skills

Added on2026-02-21

NPX Install

npx skill4agent add oakoss/agent-skills tanstack-router

SKILL.md Content

View Translation Comparison →

TanStack Router

Type-safe, file-based routing for React with route-level data loading, search params validation, code splitting, and TanStack Query integration.

Package:

@tanstack/react-router

| Plugin:

@tanstack/router-plugin

Quick Reference

Pattern	Usage
`createFileRoute('/path')`	Define file-based route
`createRootRouteWithContext<T>()`	Root route with typed context
`createLazyFileRoute('/path')`	Code-split route component
`zodValidator(schema)`	Search params validation
`Route.useLoaderData()`	Access loader data in component
`Route.useParams()`	Type-safe route params
`Route.useSearch()`	Type-safe search params
`useNavigate()`	Programmatic navigation
`useBlocker()`	Block navigation (dirty forms)
`notFound()`	Throw 404 from loader
`getRouteApi('/path')`	Type-safe hooks in split files
`stripSearchParams(defaults)`	Clean default values from URLs
`retainSearchParams(['key'])`	Preserve params across navs

Data Loading

Method	Returns	Throws	Use Case
`ensureQueryData`	Data	Yes	Route loaders (recommended)
`prefetchQuery`	void	No	Background prefetching
`fetchQuery`	Data	Yes	Immediate data need
`defer()`	Promise	No	Stream non-critical data

Preloading

Strategy	Behavior	Use Case
`'intent'`	Preload on hover/focus	Default for most links
`'render'`	Preload when Link mounts	Critical next pages
`'viewport'`	Preload when Link in view	Below-fold content
`false`	No preloading	Heavy, rarely-visited pages

File Organization

File	Purpose
`__root.tsx`	Root route with `<Outlet />`
`index.tsx`	Index route for `/`
`posts.$postId.tsx`	Dynamic param route
`_authenticated.tsx`	Pathless layout (auth guard)
`dashboard.lazy.tsx`	Code-split component

Common Mistakes

Mistake	Fix
Missing router type registration	Add `declare module` with `Register` interface
`useParams()` without `from`	Always pass `from: '/route/path'` for exact types
`useNavigate()` for regular links	Use `<Link>` for `<a>` tags, a11y, preloading
`prefetchQuery` in loaders	Use `ensureQueryData` (returns data, throws errors)
Fetching in `useEffect`	Use route loaders (prevents waterfalls)
Sequential fetches in loader	Use `Promise.all` for parallel requests
Missing leading slash	Always `'/about'` not `'about'`
TanStackRouterVite after react()	Plugin MUST come before `react()` in Vite config
`strict: false` params unparsed	Use strict mode or manually parse after navigation
Pathless route notFoundComponent	Define `notFoundComponent` on child routes instead
Aborted loader undefined error	Guard `errorComponent` with `if (!error) return null`
No `loaderDeps` declared	Declare deps so loader only re-runs when they change

Delegation

TanStack Query patterns — data fetching, caching, mutations: use
```
tanstack-query
```
skill
TanStack Start — server functions, SSR, server-side auth: use
```
tanstack-start
```
skill
TanStack Table — table rendering with router search params: use
```
tanstack-table
```
skill
Router + Query integration — coordinated patterns: use
```
tanstack-integration
```
skill

References

Setup — installation, Vite config, file structure, app setup, router default options
Type Safety — register router,
```
from
```
param,
```
strict: false
```
, type utilities, getRouteApi
Data Loading — route loaders, Query integration, parallel loading, streaming, deferred data, abort signal, loaderDeps
Search Params — validation, strip/retain middleware, fine-grained subscriptions, debounce, custom serializers
Navigation — Link, active styling, relative navigation, hash, route masks, blocker, scroll restoration
Auth and Context — beforeLoad, context inheritance, pathless layouts, dependency injection, error handling
Code Splitting — lazy routes, auto splitting, preloading strategies, programmatic preloading
Virtual File Routes — rootRoute, route, index, layout, physical builders, mixing file-based and code-based routing
Known Issues — 20 documented issues with fixes, anti-patterns
Loader+Query Patterns — ensureQueryData in loaders, parallel loading, critical vs non-critical data, search-param-dependent loaders