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 |
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() (optional) | Promise | No | Stream non-critical data (promises auto-handled) |
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 — 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.
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
