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
`useAwaited({ promise })`	Suspend until deferred promise resolves
`useCanGoBack()`	Check if router can go back safely

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

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

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 — loader data flow, preloading: see Loader Data Flow Patterns

If the tanstack-devtools skill is available, delegate router state debugging and route tree inspection to it.

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