# domain_map.yaml # Generated by skill-domain-discovery # Library: TanStack Router # Version: 1.166.2 # Date: 2026-03-07 # Status: reviewed library: name: '@tanstack/react-router' version: '1.166.2' repository: 'https://github.com/TanStack/router' description: >- Type-safe router for React and Solid with built-in SWR caching, JSON-first search params, file-based route generation, and end-to-end type inference. primary_framework: 'React' domains: - name: 'Defining Routes' slug: 'defining-routes' description: >- Setting up route trees via file-based, code-based, or virtual file routes, configuring the router instance, and registering types for end-to-end inference. - name: 'Navigating' slug: 'navigating' description: >- Moving between routes using Links, imperative navigation, redirects, preloading, active states, and navigation blocking. - name: 'Managing URL State' slug: 'managing-url-state' description: >- Reading and writing search params and path params with validation, serialization, middlewares, and type-safe adapters. - name: 'Loading Data' slug: 'loading-data' description: >- Fetching data via route loaders, coordinating external caches, managing SWR caching, deferred loading, and error/pending states. - name: 'Protecting Routes' slug: 'protecting-routes' description: >- Authentication guards, authorization checks, RBAC patterns, and redirect-based access control via beforeLoad. - name: 'Rendering and Layout' slug: 'rendering-and-layout' description: >- Outlets, nested layouts, pathless layouts, code splitting, error boundaries, not-found handling, route masking, scroll restoration, and document head management. - name: 'Type Safety' slug: 'type-safety' description: >- Router type registration, inference patterns, narrowing with from, TypeScript performance, and avoiding unnecessary type annotations. - name: 'Server-Side Rendering' slug: 'server-side-rendering' description: >- Non-streaming and streaming SSR setup, hydration, data serialization, and isomorphic router creation. skills: # ── Defining Routes ────────────────────────────────────────────── - name: 'Route Setup' slug: 'route-setup' domain: 'defining-routes' description: >- Set up a TanStack Router project with file-based, code-based, or virtual file routes, configure the router instance, and register types. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' - '@tanstack/router-plugin' - '@tanstack/router-generator' - '@tanstack/router-cli' - '@tanstack/virtual-file-routes' - '@tanstack/eslint-plugin-router' covers: - createRouter - createRootRoute - createRootRouteWithContext - createRoute - createFileRoute - createLazyFileRoute - addChildren - routeTree.gen.ts - declare module Register - TanStackRouter bundler plugin - tsr.config.json - virtual file routes API - file naming conventions - route matching and sorting tasks: - 'Scaffold a new TanStack Router project' - 'Configure file-based routing with Vite plugin' - 'Set up code-based route tree manually' - 'Configure virtual file routes for custom conventions' - 'Register router types via module declaration' - 'Set up ESLint plugin for route property ordering' reference_candidates: - topic: 'file naming conventions' reason: '>10 distinct conventions (dot separator, $ token, _ prefix/suffix, () groups, [] escaping, index, route.tsx, __root)' failure_modes: - mistake: 'Missing router type registration' mechanism: >- Without declare module Register, top-level exports like Link, useNavigate, useParams have no type safety. Code compiles but all route paths are untyped strings. wrong_pattern: | const router = createRouter({ routeTree }) // no declare module — Link to="" has no autocomplete correct_pattern: | const router = createRouter({ routeTree }) declare module '@tanstack/react-router' { interface Register { router: typeof router } } source: 'docs/router/guide/creating-a-router.md' priority: CRITICAL status: active skills: ['route-setup', 'type-safety'] - mistake: 'Not committing routeTree.gen.ts' mechanism: >- routeTree.gen.ts is runtime code, not a build artifact. Without it in version control, other developers cannot build or run the project. source: 'docs/router/faq.md' priority: HIGH status: active - mistake: 'Wrong route property order breaks type inference' mechanism: >- Properties like beforeLoad must come before loader in createRoute/createFileRoute calls. Incorrect order causes context types to not flow into loader. wrong_pattern: | createFileRoute('/posts')({ loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery), beforeLoad: ({ context }) => ({ queryClient: context.queryClient }), }) correct_pattern: | createFileRoute('/posts')({ beforeLoad: ({ context }) => ({ queryClient: context.queryClient }), loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery), }) source: 'docs/router/eslint/create-route-property-order.md' priority: HIGH status: active - mistake: 'Placing TanStackRouter plugin after framework plugin' mechanism: >- The TanStackRouter Vite plugin must be listed before the React/Solid plugin in the Vite config. Wrong order causes route generation to fail silently. wrong_pattern: | plugins: [react(), TanStackRouterVite()] correct_pattern: | plugins: [TanStackRouterVite(), react()] source: 'docs/router/installation/with-vite.md' priority: HIGH status: active - mistake: 'Using getParentRoute incorrectly in code-based routing' mechanism: >- Every non-root route must reference its correct parent via getParentRoute. Wrong parent breaks type inference for context, search params, and path params from ancestors. source: 'docs/router/decisions-on-dx.md' priority: HIGH status: active compositions: - library: '@tanstack/eslint-plugin-router' skill: null # ── Navigating ─────────────────────────────────────────────────── - name: 'Navigation' slug: 'navigation' domain: 'navigating' description: >- Navigate between routes using Link, useNavigate, Navigate component, and router.navigate. Configure preloading, active link states, and navigation blocking. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - Link component - useNavigate hook - Navigate component - router.navigate - ToOptions / NavigateOptions / LinkOptions - from / to relative navigation - activeOptions / activeProps / inactiveProps - preload (intent / viewport / render) - preloadDelay / defaultPreloadDelay - useBlocker hook - Block component - createLink (custom link components) - linkOptions helper - MatchRoute component - scroll restoration tasks: - 'Create type-safe links between routes' - 'Navigate programmatically after an action' - 'Set up link preloading on hover intent' - 'Style active and inactive links' - 'Block navigation for unsaved changes' - 'Create custom link components with createLink' - 'Build reusable navigation options with linkOptions' - 'Configure scroll restoration' failure_modes: - mistake: 'Interpolating params into the to string' mechanism: >- Agents build paths like to={`/posts/${id}`} instead of using the params option. Breaks type safety and param encoding. wrong_pattern: | Post correct_pattern: | Post source: 'docs/router/guide/navigation.md' priority: CRITICAL status: active skills: ['navigation', 'type-safety'] - mistake: 'Using useNavigate instead of Link for user-clickable elements' mechanism: >- Link renders a real with href, supports cmd/ctrl+click and preloading. useNavigate produces no accessible element. source: 'docs/router/guide/navigation.md' priority: MEDIUM status: active - mistake: 'Not providing from for relative navigation' mechanism: >- Without from, the router assumes navigation from root. Only absolute paths are autocompleted. Relative paths like ".." resolve from root instead of current route. wrong_pattern: | Back correct_pattern: | Back source: 'docs/router/guide/navigation.md' priority: HIGH status: active - mistake: 'Using search as object instead of function loses existing params' mechanism: >- search={{ page: 2 }} replaces all search params. Must use function form to preserve existing params. wrong_pattern: | Page 2 correct_pattern: | ({ ...prev, page: 2 })}>Page 2 source: 'docs/router/how-to/navigate-with-search-params.md' priority: HIGH status: active skills: ['navigation', 'search-params'] # ── Managing URL State ─────────────────────────────────────────── - name: 'Search Params' slug: 'search-params' domain: 'managing-url-state' description: >- Validate, read, write, and transform search params with schema validation, adapters, middlewares, and custom serialization. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' - '@tanstack/zod-adapter' - '@tanstack/valibot-adapter' - '@tanstack/arktype-adapter' covers: - validateSearch - useSearch hook - Route.useSearch - getRouteApi().useSearch - search middlewares - retainSearchParams - stripSearchParams - custom serialization (parseSearch / stringifySearch) - zod adapter / valibot adapter / arktype adapter - search param inheritance from parent routes - structural sharing for search params tasks: - 'Add validated search params to a route' - 'Read search params in components' - 'Update search params while preserving others' - 'Share search params across parent and child routes' - 'Set up search param middlewares for retention/stripping' - 'Configure custom search param serialization' - 'Handle arrays, objects, and dates in search params' subsystems: - name: 'Zod adapter' package: '@tanstack/zod-adapter' config_surface: 'zodValidator, fallback() wrapper for .catch/.default type correctness' - name: 'Valibot adapter' package: '@tanstack/valibot-adapter' config_surface: 'Standard Schema compliant, requires valibot 1.0' - name: 'ArkType adapter' package: '@tanstack/arktype-adapter' config_surface: 'Standard Schema compliant, requires arktype 2.0-rc, pass directly to validateSearch' reference_candidates: - topic: 'search param validation patterns' reason: '>10 distinct patterns (basic, optional, arrays, objects, dates, discriminated unions, transforms, conditional, cross-route inheritance, middleware chaining)' failure_modes: - mistake: 'Using zod .catch() instead of adapter fallback()' mechanism: >- Zod .catch() makes the output type unknown, losing type safety. The @tanstack/zod-adapter fallback() preserves the correct inferred type. wrong_pattern: | z.object({ page: z.number().catch(1) }) correct_pattern: | import { fallback } from '@tanstack/zod-adapter' z.object({ page: fallback(z.number(), 1) }) source: 'docs/router/guide/search-params.md' priority: HIGH status: active - mistake: 'Returning entire search object from loaderDeps' mechanism: >- loaderDeps: ({ search }) => search causes loader to re-run on ANY search param change, not just relevant ones. Deep equality comparison fires on every unrelated change. wrong_pattern: | loaderDeps: ({ search }) => search correct_pattern: | loaderDeps: ({ search }) => ({ page: search.page }) source: 'docs/router/guide/data-loading.md' priority: HIGH status: active skills: ['search-params', 'data-loading'] - mistake: 'Passing Date objects in search params' mechanism: >- Date objects serialize to [object Object] in URLs. Must convert to ISO strings for correct serialization. wrong_pattern: | correct_pattern: | source: 'docs/router/how-to/arrays-objects-dates-search-params.md' priority: HIGH status: active - mistake: 'Parent route missing validateSearch blocks inheritance' mechanism: >- Child routes cannot access shared search params unless the parent route defines validateSearch. Without it, the types and runtime values are not available. source: 'docs/router/how-to/share-search-params-across-routes.md' priority: MEDIUM status: active - name: 'Path Params' slug: 'path-params' domain: 'managing-url-state' description: >- Define and consume dynamic path segments, splat routes, optional params, and prefix/suffix patterns. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - '$paramName dynamic segments' - '$ splat / _splat' - '{-$paramName} optional params' - '{$paramName} prefix/suffix patterns' - useParams hook - params.parse / params.stringify - pathParamsAllowedCharacters tasks: - 'Define routes with dynamic path parameters' - 'Use splat routes for catch-all matching' - 'Set up optional path parameters for i18n' - 'Navigate with type-safe path params' failure_modes: - mistake: 'Interpolating path params into to string' mechanism: >- Same as navigation failure mode — agents build template literal paths instead of using params option. source: 'docs/router/guide/navigation.md' priority: CRITICAL status: active skills: ['path-params', 'navigation'] - mistake: 'Using * for splat routes instead of $' mechanism: >- TanStack Router uses $ for splat routes, not * like some other routers. The captured value is under _splat key, not * (though * works in v1 for backwards compat, removed in v2). source: 'docs/router/routing/routing-concepts.md' priority: MEDIUM status: 'fixed-but-legacy-risk' version_context: '* works in v1 for compat but will be removed in v2' - mistake: 'Using curly braces for basic dynamic segments' mechanism: >- Basic dynamic segments use $postId (no braces). Curly braces are only for prefix/suffix patterns like {$postId}.txt or optional params {-$locale}. source: 'docs/router/guide/path-params.md' priority: MEDIUM status: active # ── Loading Data ───────────────────────────────────────────────── - name: 'Data Loading' slug: 'data-loading' domain: 'loading-data' description: >- Load data via route loaders with built-in SWR caching, configure staleTime/gcTime, use loaderDeps for cache keys, handle pending and error states, and inject dependencies via router context. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - loader option - loaderDeps - staleTime / gcTime / defaultPreloadStaleTime - pendingComponent / pendingMs / pendingMinMs - errorComponent / onError / onCatch - beforeLoad - router context / createRootRouteWithContext - router.invalidate - Await component - deferred data loading tasks: - 'Add a data loader to a route' - 'Configure cache timing (staleTime, gcTime)' - 'Set up loader dependencies for search-param-driven data' - 'Show pending UI during slow loads' - 'Handle loader errors with error boundaries' - 'Inject dependencies via router context' - 'Defer non-critical data with unawaited promises' - 'Invalidate cached data after mutations' failure_modes: - mistake: 'Assuming loaders only run on the server' mechanism: >- TanStack Router is client-first. Loaders run on the client by default (and also on the server if using TanStack Start). Agents trained on Remix/Next assume loaders are server-only and put server-only code (DB queries, fs access) in them. source: 'maintainer interview' priority: CRITICAL status: active skills: ['data-loading', 'ssr'] - mistake: 'Not understanding staleTime default is 0' mechanism: >- Default staleTime is 0, meaning data is always considered stale and reloads in background on every route re-match. Agents may not set staleTime, causing excessive refetching. source: 'docs/router/guide/data-loading.md' priority: MEDIUM status: active - mistake: 'Using reset() instead of router.invalidate() in error components' mechanism: >- For loader errors, reset() only resets the error boundary but does not re-run the loader. Must use router.invalidate() to coordinate both reload and boundary reset. wrong_pattern: | function PostErrorComponent({ error, reset }) { return } correct_pattern: | function PostErrorComponent({ error, reset }) { const router = useRouter() return } source: 'docs/router/guide/data-loading.md' priority: HIGH status: active - mistake: 'Double parentheses missing on createRootRouteWithContext' mechanism: >- createRootRouteWithContext() is a factory — it returns a function. Must call it twice: createRootRouteWithContext()(routeOptions). Missing second call is a common error. wrong_pattern: | const rootRoute = createRootRouteWithContext<{ auth: AuthState }>({ component: RootComponent, }) correct_pattern: | const rootRoute = createRootRouteWithContext<{ auth: AuthState }>()({ component: RootComponent, }) source: 'docs/router/guide/data-loading.md' priority: HIGH status: active - mistake: 'Using React hooks in beforeLoad or loader' mechanism: >- beforeLoad and loader are not React components — hooks cannot be called in them. Must extract hook state in a wrapper component and pass via router context. source: 'docs/router/guide/router-context.md' priority: HIGH status: active compositions: - library: '@tanstack/react-query' skill: 'external-data-loading' - name: 'External Data Loading' slug: 'external-data-loading' domain: 'loading-data' description: >- Integrate TanStack Query (or other external caches) with Router for coordinated data loading, SSR dehydration/hydration, and streaming. type: composition packages: - '@tanstack/react-router' - '@tanstack/react-router-ssr-query' covers: - External cache coordination pattern - queryClient.ensureQueryData in loader - useSuspenseQuery in components - setupRouterSsrQueryIntegration - defaultPreloadStaleTime - dehydrate / hydrate router options - QueryClient per-request isolation - Wrap router option for providers tasks: - 'Set up TanStack Query with Router' - 'Preload query data in route loaders' - 'Configure SSR dehydration/hydration with Query' - 'Stream query data during SSR' failure_modes: - mistake: 'Not setting defaultPreloadStaleTime to 0 with external caches' mechanism: >- Router's built-in preload cache (30s default) prevents external library from controlling freshness. Set defaultPreloadStaleTime: 0 to let Query manage caching. wrong_pattern: | createRouter({ routeTree }) correct_pattern: | createRouter({ routeTree, defaultPreloadStaleTime: 0 }) source: 'docs/router/guide/external-data-loading.md' priority: HIGH status: active - mistake: 'Creating QueryClient outside createRouter for SSR' mechanism: >- For SSR, QueryClient must be created inside createRouter to ensure per-request isolation. A shared singleton leaks data between requests. wrong_pattern: | const queryClient = new QueryClient() const router = createRouter({ routeTree, context: { queryClient } }) correct_pattern: | function createAppRouter() { const queryClient = new QueryClient() return createRouter({ routeTree, context: { queryClient } }) } source: 'docs/router/guide/external-data-loading.md' priority: HIGH status: active - mistake: 'Awaiting prefetchQuery in loader blocks rendering' mechanism: >- For streaming/deferred patterns, prefetchQuery should NOT be awaited in the loader — it starts fetching on server and streams without blocking. Awaiting defeats the purpose. source: 'docs/router/integrations/query.md' priority: MEDIUM status: active # ── Protecting Routes ──────────────────────────────────────────── - name: 'Auth and Guards' slug: 'auth-and-guards' domain: 'protecting-routes' description: >- Protect routes with authentication checks, authorization guards, and RBAC patterns using beforeLoad redirects and layout routes. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - beforeLoad for auth checks - redirect() / throw redirect() - isRedirect helper - Authenticated layout routes (_authenticated) - Non-redirect auth (inline login) - RBAC with roles and permissions - Auth provider integration (Auth0, Clerk, Supabase) - Router context for auth state tasks: - 'Protect routes with authentication checks' - 'Redirect unauthenticated users to login' - 'Implement role-based access control' - 'Integrate third-party auth providers' - 'Pass auth state through router context' failure_modes: - mistake: 'Auth check in component instead of beforeLoad' mechanism: >- Component-level auth checks cause protected content to flash before redirect. beforeLoad runs before any component rendering and prevents the flash entirely. wrong_pattern: | component: () => { const auth = useAuth() if (!auth.isAuthenticated) return return } correct_pattern: | beforeLoad: ({ context }) => { if (!context.auth.isAuthenticated) { throw redirect({ to: '/login' }) } } source: 'docs/router/how-to/setup-authentication.md' priority: HIGH status: active - mistake: 'Not re-throwing redirects in try/catch' mechanism: >- redirect() works by throwing. If beforeLoad has a try/catch for error handling, the redirect gets swallowed unless re-thrown via isRedirect() check. wrong_pattern: | beforeLoad: async ({ context }) => { try { await validateSession(context.auth) } catch (e) { // swallows redirect! console.error(e) } } correct_pattern: | beforeLoad: async ({ context }) => { try { await validateSession(context.auth) } catch (e) { if (isRedirect(e)) throw e console.error(e) } } source: 'docs/router/guide/authenticated-routes.md' priority: HIGH status: active - mistake: 'Trying to conditionally render root route component' mechanism: >- Root route is always rendered regardless of auth state. Use a pathless layout route (_authenticated) with beforeLoad for conditional rendering. source: 'docs/router/faq.md' priority: MEDIUM status: active # ── Rendering and Layout ───────────────────────────────────────── - name: 'Code Splitting' slug: 'code-splitting' domain: 'rendering-and-layout' description: >- Split route code into lazy-loaded chunks using automatic code splitting, .lazy.tsx files, or code-based lazy loading. type: core packages: - '@tanstack/react-router' - '@tanstack/router-plugin' covers: - autoCodeSplitting plugin option - .lazy.tsx file convention - createLazyFileRoute - createLazyRoute - lazyRouteComponent - getRouteApi for code-split components - codeSplitGroupings per-route override - splitBehavior programmatic config - Critical vs non-critical route properties tasks: - 'Enable automatic code splitting' - 'Manually split a route with .lazy.tsx' - 'Access typed hooks from code-split components' - 'Customize which properties are split per route' failure_modes: - mistake: 'Exporting route property functions prevents code splitting' mechanism: >- Exported functions from route files are included in the main bundle even with auto code splitting. Component functions must NOT be exported. wrong_pattern: | export function PostsComponent() { return
Posts
} correct_pattern: | function PostsComponent() { return
Posts
} source: 'docs/router/guide/automatic-code-splitting.md' priority: HIGH status: active - mistake: 'Trying to code-split the root route' mechanism: >- __root.tsx does not support code splitting — it is always rendered regardless of current route. source: 'docs/router/guide/code-splitting.md' priority: MEDIUM status: active - mistake: 'Splitting the loader adds double async cost' mechanism: >- Loader is already async. Splitting it requires fetching the chunk AND then executing the loader, adding latency. Loaders should stay in the main bundle unless there is a specific reason to split them. source: 'docs/router/guide/code-splitting.md' priority: MEDIUM status: active - mistake: 'Importing Route in code-split files for typed hooks' mechanism: >- Importing the Route object in a lazy-loaded file pulls the route config into the lazy chunk, defeating code splitting. Use getRouteApi('/path') instead. wrong_pattern: | import { Route } from './posts.tsx' const data = Route.useLoaderData() correct_pattern: | import { getRouteApi } from '@tanstack/react-router' const route = getRouteApi('/posts') const data = route.useLoaderData() source: 'docs/router/guide/code-splitting.md' priority: HIGH status: active - name: 'Not Found and Errors' slug: 'not-found-and-errors' domain: 'rendering-and-layout' description: >- Handle not-found routes, missing resources, and route-level errors with notFound(), notFoundComponent, errorComponent, and CatchBoundary. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - notFound() function - notFoundComponent - defaultNotFoundComponent - notFoundMode (fuzzy / root) - errorComponent - onError / onCatch - CatchBoundary component - NotFoundRoute (deprecated) tasks: - 'Add a 404 page for unmatched routes' - 'Throw not-found for missing resources in loaders' - 'Configure error boundaries per route' - 'Target specific routes with notFound()' failure_modes: - mistake: 'Using deprecated NotFoundRoute' mechanism: >- NotFoundRoute is deprecated. When present, notFound() and notFoundComponent will NOT work. Must remove NotFoundRoute and use notFoundComponent instead. source: 'docs/router/guide/not-found-errors.md' priority: HIGH status: 'fixed-but-legacy-risk' version_context: 'NotFoundRoute deprecated, will be removed in next major' - mistake: 'Expecting useLoaderData to work in notFoundComponent' mechanism: >- When notFoundComponent renders, the route's loader may not have completed. useLoaderData() may return undefined. Use useParams, useSearch, or useRouteContext instead. source: 'docs/router/guide/not-found-errors.md' priority: MEDIUM status: active - mistake: 'Leaf route cannot handle not-found errors' mechanism: >- Routes without children never render Outlet and therefore cannot catch not-found errors. Only routes with children (or the root route) can have notFoundComponent. source: 'docs/router/guide/not-found-errors.md' priority: MEDIUM status: active - name: 'Route Masking' slug: 'route-masking' domain: 'rendering-and-layout' description: >- Mask the browser URL while navigating to a different internal route, with configurable unmask behavior. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - mask option on Link / navigate - createRouteMask - routeMasks router option - unmaskOnReload - location.maskedLocation - location.state.__tempLocation tasks: - 'Show a modal route with a clean URL' - 'Configure declarative route masks' - 'Control unmask behavior on page reload' failure_modes: - mistake: 'Expecting masked URLs to survive sharing' mechanism: >- Masking data is stored in browser history state. When a URL is shared or opened in a new tab, masking data is lost and the visible URL is used directly. source: 'docs/router/guide/route-masking.md' priority: MEDIUM status: active # ── Type Safety ────────────────────────────────────────────────── - name: 'Type Safety' slug: 'type-safety' domain: 'type-safety' description: >- Leverage TanStack Router's fully inferred type system. Avoid unnecessary type annotations, narrow routes with from, and optimize TypeScript performance. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - Full type inference philosophy - Register module declaration - from narrowing on hooks and Link - strict false for shared components - getRouteApi for code-split typed access - addChildren with object syntax for TS perf - LinkProps / ValidateLinkOptions type utilities - as const satisfies pattern tasks: - 'Register router types for global type safety' - 'Narrow route types with from parameter' - 'Use getRouteApi in code-split components' - 'Optimize TypeScript performance in large route trees' - 'Build type-safe link option utilities' failure_modes: - mistake: 'Adding type annotations or casts to inferred values' mechanism: >- TanStack Router is fully type-safe with full inference. Adding as Type, generic type parameters, satisfies, or explicit type annotations is unnecessary and can mask real type errors or break the inference chain. wrong_pattern: | const search = useSearch({ from: '/posts' }) as { page: number } correct_pattern: | const search = useSearch({ from: '/posts' }) // search.page is already typed as number source: 'maintainer interview' priority: CRITICAL status: active - mistake: 'Using un-narrowed LinkProps type' mechanism: >- LinkProps without generics is an extremely large union type. Using it as a variable type causes severe TS performance degradation. Use as const satisfies or narrow with generics. wrong_pattern: | const props: LinkProps = { to: '/posts' } correct_pattern: | const props = { to: '/posts' } as const satisfies LinkProps source: 'docs/router/guide/type-safety.md' priority: HIGH status: active - mistake: 'Not narrowing Link/useNavigate with from' mechanism: >- Without from, search resolves to a union of ALL routes search params. TypeScript check time grows linearly with route count. Always provide from to narrow. wrong_pattern: | correct_pattern: | source: 'docs/router/guide/type-safety.md' priority: HIGH status: active # ── Server-Side Rendering ──────────────────────────────────────── - name: 'SSR' slug: 'ssr' domain: 'server-side-rendering' description: >- Set up server-side rendering with non-streaming or streaming approaches, manage hydration, and handle document head. type: core packages: - '@tanstack/react-router' - '@tanstack/router-core' covers: - RouterClient / RouterServer - renderRouterToString / renderRouterToStream - createRequestHandler - defaultRenderHandler / defaultStreamHandler - HeadContent / Scripts components - head route option (meta, links, styles, scripts) - ScriptOnce component - Automatic loader dehydration/hydration - Memory history on server - Data serialization (Date, Error, FormData, undefined) tasks: - 'Set up non-streaming SSR with Express' - 'Set up streaming SSR' - 'Configure document head management' - 'Handle hydration mismatches' failure_modes: - mistake: 'Using browser APIs in loaders without environment check' mechanism: >- Loaders run on both client and server when using SSR. Browser-only APIs (window, document, localStorage) will throw on the server. source: 'docs/router/guide/ssr.md' priority: HIGH status: active skills: ['ssr', 'data-loading'] - mistake: 'Using hash fragments for server-rendered content' mechanism: >- Hash fragments are client-only — browsers never send them to the server. Using hash for conditional rendering causes hydration mismatches during SSR. source: 'docs/router/guide/navigation.md' priority: MEDIUM status: active - mistake: 'Generating Next.js or Remix SSR patterns' mechanism: >- Agents trained on Next.js generate getServerSideProps, App Router patterns, or server components. Agents trained on Remix generate server-only loader exports. TanStack Router has its own SSR API (RouterClient/RouterServer). source: 'maintainer interview' priority: CRITICAL status: active skills: ['ssr', 'route-setup', 'data-loading'] # ── Migration ──────────────────────────────────────────────────── - name: 'Migrate from React Router' slug: 'migrate-from-react-router' domain: 'defining-routes' description: >- Step-by-step migration from React Router v7 to TanStack Router, covering route definitions, navigation, search params, and data loading. type: lifecycle packages: - '@tanstack/react-router' - '@tanstack/router-plugin' covers: - Migration checklist - Route definition conversion - Link / useNavigate API differences - useSearchParams to validateSearch + useSearch - useParams with from - Outlet replacement - Loader conversion - Code splitting differences tasks: - 'Migrate routes from React Router to TanStack Router' - 'Convert React Router Links and navigation' - 'Replace useSearchParams with validated search params' - 'Convert React Router loaders' failure_modes: - mistake: 'Leaving React Router imports alongside TanStack Router' mechanism: >- React Router and TanStack Router share similar API names (Link, useNavigate, Outlet). Leftover React Router imports cause context errors ("cannot use useNavigate outside of context"). Uninstall react-router-dom to surface these. source: 'docs/router/how-to/migrate-from-react-router.md' priority: HIGH status: active - mistake: 'Using React Router useSearchParams pattern' mechanism: >- React Router uses useSearchParams() returning URLSearchParams. TanStack Router uses validateSearch schema + useSearch() returning typed objects. Agents may generate the RR pattern. wrong_pattern: | const [searchParams, setSearchParams] = useSearchParams() const page = Number(searchParams.get('page')) correct_pattern: | // In route definition: validateSearch: z.object({ page: fallback(z.number(), 1) }) // In component: const { page } = Route.useSearch() source: 'docs/router/installation/migrate-from-react-router.md' priority: HIGH status: active tensions: - name: 'Type safety strictness vs rapid prototyping' skills: ['type-safety', 'route-setup'] description: >- Full type inference requires proper setup (Register, correct property order, getParentRoute). This upfront cost conflicts with quick prototyping where developers want to skip setup. implication: >- Agents skip Register declaration or use type casts to silence errors, producing code that compiles but has no type safety. - name: 'Client-first loaders vs SSR expectations' skills: ['data-loading', 'ssr'] description: >- Loaders are client-first by design but agents assume they are server-only (Remix/Next mental model). This tension means browser APIs work in loaders by default but break under SSR. implication: >- Agents either put server-only code in client loaders or avoid browser APIs unnecessarily, depending on which framework mental model they default to. - name: 'Built-in SWR cache vs external cache coordination' skills: ['data-loading', 'external-data-loading'] description: >- Router has built-in caching with staleTime/gcTime defaults. When using an external cache like React Query, the built-in cache must be bypassed (defaultPreloadStaleTime: 0) or it conflicts with the external library's freshness management. implication: >- Agents use both caches simultaneously without disabling the built-in one, causing stale data or double-fetching. - name: 'Code splitting granularity vs loader performance' skills: ['code-splitting', 'data-loading'] description: >- Splitting more aggressively reduces initial bundle but splitting the loader adds a network round-trip before data can be fetched. The optimal split point differs per route. implication: >- Agents split everything including loaders, adding latency to data loading without understanding the tradeoff. cross_references: - from: 'route-setup' to: 'type-safety' reason: 'Register declaration and property order are prerequisites for type inference' - from: 'navigation' to: 'search-params' reason: 'Link search prop and navigate search option directly interact with search param validation' - from: 'data-loading' to: 'search-params' reason: 'loaderDeps consumes validated search params as cache keys' - from: 'data-loading' to: 'external-data-loading' reason: 'Understanding built-in caching is prerequisite for coordinating with external caches' - from: 'auth-and-guards' to: 'data-loading' reason: 'beforeLoad runs before loader — auth context flows into loader via route context' - from: 'code-splitting' to: 'data-loading' reason: 'Loader splitting decisions affect data loading performance' - from: 'ssr' to: 'data-loading' reason: 'SSR changes where loaders execute — must handle both environments' - from: 'ssr' to: 'external-data-loading' reason: 'SSR dehydration/hydration requires special setup for Query integration' - from: 'not-found-and-errors' to: 'data-loading' reason: 'notFound() thrown in loaders interacts with error boundaries and loader data availability' - from: 'migrate-from-react-router' to: 'route-setup' reason: 'Migration requires understanding TanStack Router route setup to replace RR patterns' gaps: []