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'

tanstackRouter() 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