Open History to see the last commit
1# domain_map.yaml
2# Generated by skill-domain-discovery
3# Library: TanStack Router
4# Version: 1.166.2
5# Date: 2026-03-07
6# Status: reviewed
7β
8library:
9 name: '@tanstack/react-router'
10 version: '1.166.2'
11 repository: 'https://github.com/TanStack/router'
12 description: >-
13 Type-safe router for React and Solid with built-in SWR caching,
14 JSON-first search params, file-based route generation, and
15 end-to-end type inference.
16 primary_framework: 'React'
17β
18domains:
19 - name: 'Defining Routes'
20 slug: 'defining-routes'
21 description: >-
22 Setting up route trees via file-based, code-based, or virtual
23 file routes, configuring the router instance, and registering
24 types for end-to-end inference.
25β
26 - name: 'Navigating'
27 slug: 'navigating'
28 description: >-
29 Moving between routes using Links, imperative navigation,
30 redirects, preloading, active states, and navigation blocking.
31β
32 - name: 'Managing URL State'
33 slug: 'managing-url-state'
34 description: >-
35 Reading and writing search params and path params with
36 validation, serialization, middlewares, and type-safe adapters.
37β
38 - name: 'Loading Data'
39 slug: 'loading-data'
40 description: >-
41 Fetching data via route loaders, coordinating external caches,
42 managing SWR caching, deferred loading, and error/pending states.
43β
44 - name: 'Protecting Routes'
45 slug: 'protecting-routes'
46 description: >-
47 Authentication guards, authorization checks, RBAC patterns,
48 and redirect-based access control via beforeLoad.
49β
50 - name: 'Rendering and Layout'
51 slug: 'rendering-and-layout'
52 description: >-
53 Outlets, nested layouts, pathless layouts, code splitting,
54 error boundaries, not-found handling, route masking, scroll
55 restoration, and document head management.
56β
57 - name: 'Type Safety'
58 slug: 'type-safety'
59 description: >-
60 Router type registration, inference patterns, narrowing with
61 from, TypeScript performance, and avoiding unnecessary type
62 annotations.
63β
64 - name: 'Server-Side Rendering'
65 slug: 'server-side-rendering'
66 description: >-
67 Non-streaming and streaming SSR setup, hydration, data
68 serialization, and isomorphic router creation.
69β
70skills:
71 # ββ Defining Routes ββββββββββββββββββββββββββββββββββββββββββββββ
72 - name: 'Route Setup'
73 slug: 'route-setup'
74 domain: 'defining-routes'
75 description: >-
76 Set up a TanStack Router project with file-based, code-based,
77 or virtual file routes, configure the router instance, and
78 register types.
79 type: core
80 packages:
81 - '@tanstack/react-router'
82 - '@tanstack/router-core'
83 - '@tanstack/router-plugin'
84 - '@tanstack/router-generator'
85 - '@tanstack/router-cli'
86 - '@tanstack/virtual-file-routes'
87 - '@tanstack/eslint-plugin-router'
88 covers:
89 - createRouter
90 - createRootRoute
91 - createRootRouteWithContext
92 - createRoute
93 - createFileRoute
94 - createLazyFileRoute
95 - addChildren
96 - routeTree.gen.ts
97 - declare module Register
98 - TanStackRouter bundler plugin
99 - tsr.config.json
100 - virtual file routes API
101 - file naming conventions
102 - route matching and sorting
103 tasks:
104 - 'Scaffold a new TanStack Router project'
105 - 'Configure file-based routing with Vite plugin'
106 - 'Set up code-based route tree manually'
107 - 'Configure virtual file routes for custom conventions'
108 - 'Register router types via module declaration'
109 - 'Set up ESLint plugin for route property ordering'
110 reference_candidates:
111 - topic: 'file naming conventions'
112 reason: '>10 distinct conventions (dot separator, $ token, _ prefix/suffix, () groups, [] escaping, index, route.tsx, __root)'
113 failure_modes:
114 - mistake: 'Missing router type registration'
115 mechanism: >-
116 Without declare module Register, top-level exports like
117 Link, useNavigate, useParams have no type safety. Code
118 compiles but all route paths are untyped strings.
119 wrong_pattern: |
120 const router = createRouter({ routeTree })
121 // no declare module β Link to="" has no autocomplete
122 correct_pattern: |
123 const router = createRouter({ routeTree })
124 declare module '@tanstack/react-router' {
125 interface Register {
126 router: typeof router
127 }
128 }
129 source: 'docs/router/guide/creating-a-router.md'
130 priority: CRITICAL
131 status: active
132 skills: ['route-setup', 'type-safety']
133β
134 - mistake: 'Not committing routeTree.gen.ts'
135 mechanism: >-
136 routeTree.gen.ts is runtime code, not a build artifact.
137 Without it in version control, other developers cannot
138 build or run the project.
139 source: 'docs/router/faq.md'
140 priority: HIGH
141 status: active
142β
143 - mistake: 'Wrong route property order breaks type inference'
144 mechanism: >-
145 Properties like beforeLoad must come before loader in
146 createRoute/createFileRoute calls. Incorrect order causes
147 context types to not flow into loader.
148 wrong_pattern: |
149 createFileRoute('/posts')({
150 loader: ({ context }) =>
151 context.queryClient.query({ ...postsQuery, staleTime: 'static' }),
152 beforeLoad: ({ context }) => ({ queryClient: context.queryClient }),
153 })
154 correct_pattern: |
155 createFileRoute('/posts')({
156 beforeLoad: ({ context }) => ({ queryClient: context.queryClient }),
157 loader: ({ context }) =>
158 context.queryClient.query({ ...postsQuery, staleTime: 'static' }),
159 })
160 source: 'docs/router/eslint/create-route-property-order.md'
161 priority: HIGH
162 status: active
163β
164 - mistake: 'Placing TanStackRouter plugin after framework plugin'
165 mechanism: >-
166 The TanStackRouter Vite plugin must be listed before the
167 React/Solid plugin in the Vite config. Wrong order causes
168 route generation to fail silently.
169 wrong_pattern: |
170 plugins: [react(), TanStackRouterVite()]
171 correct_pattern: |
172 plugins: [TanStackRouterVite(), react()]
173 source: 'docs/router/installation/with-vite.md'
174 priority: HIGH
175 status: active
176β
177 - mistake: 'Using getParentRoute incorrectly in code-based routing'
178 mechanism: >-
179 Every non-root route must reference its correct parent via
180 getParentRoute. Wrong parent breaks type inference for
181 context, search params, and path params from ancestors.
182 source: 'docs/router/decisions-on-dx.md'
183 priority: HIGH
184 status: active
185β
186 compositions:
187 - library: '@tanstack/eslint-plugin-router'
188 skill: null
189β
190 # ββ Navigating βββββββββββββββββββββββββββββββββββββββββββββββββββ
191 - name: 'Navigation'
192 slug: 'navigation'
193 domain: 'navigating'
194 description: >-
195 Navigate between routes using Link, useNavigate, Navigate
196 component, and router.navigate. Configure preloading, active
197 link states, and navigation blocking.
198 type: core
199 packages:
200 - '@tanstack/react-router'
201 - '@tanstack/router-core'
202 covers:
203 - Link component
204 - useNavigate hook
205 - Navigate component
206 - router.navigate
207 - ToOptions / NavigateOptions / LinkOptions
208 - from / to relative navigation
209 - activeOptions / activeProps / inactiveProps
210 - preload (intent / viewport / render)
211 - preloadDelay / defaultPreloadDelay
212 - useBlocker hook
213 - Block component
214 - createLink (custom link components)
215 - linkOptions helper
216 - MatchRoute component
217 - scroll restoration
218 tasks:
219 - 'Create type-safe links between routes'
220 - 'Navigate programmatically after an action'
221 - 'Set up link preloading on hover intent'
222 - 'Style active and inactive links'
223 - 'Block navigation for unsaved changes'
224 - 'Create custom link components with createLink'
225 - 'Build reusable navigation options with linkOptions'
226 - 'Configure scroll restoration'
227 failure_modes:
228 - mistake: 'Interpolating params into the to string'
229 mechanism: >-
230 Agents build paths like to={`/posts/${id}`} instead of
231 using the params option. Breaks type safety and param
232 encoding.
233 wrong_pattern: |
234 <Link to={`/posts/${postId}`}>Post</Link>
235 correct_pattern: |
236 <Link to="/posts/$postId" params={{ postId }}>Post</Link>
237 source: 'docs/router/guide/navigation.md'
238 priority: CRITICAL
239 status: active
240 skills: ['navigation', 'type-safety']
241β
242 - mistake: 'Using useNavigate instead of Link for user-clickable elements'
243 mechanism: >-
244 Link renders a real <a> with href, supports cmd/ctrl+click
245 and preloading. useNavigate produces no accessible element.
246 source: 'docs/router/guide/navigation.md'
247 priority: MEDIUM
248 status: active
249β
250 - mistake: 'Not providing from for relative navigation'
251 mechanism: >-
252 Without from, the router assumes navigation from root.
253 Only absolute paths are autocompleted. Relative paths
254 like ".." resolve from root instead of current route.
255 wrong_pattern: |
256 <Link to="..">Back</Link>
257 correct_pattern: |
258 <Link from={Route.fullPath} to="..">Back</Link>
259 source: 'docs/router/guide/navigation.md'
260 priority: HIGH
261 status: active
262β
263 - mistake: 'Using search as object instead of function loses existing params'
264 mechanism: >-
265 search={{ page: 2 }} replaces all search params.
266 Must use function form to preserve existing params.
267 wrong_pattern: |
268 <Link to="." search={{ page: 2 }}>Page 2</Link>
269 correct_pattern: |
270 <Link to="." search={(prev) => ({ ...prev, page: 2 })}>Page 2</Link>
271 source: 'docs/router/how-to/navigate-with-search-params.md'
272 priority: HIGH
273 status: active
274 skills: ['navigation', 'search-params']
275β
276 # ββ Managing URL State βββββββββββββββββββββββββββββββββββββββββββ
277 - name: 'Search Params'
278 slug: 'search-params'
279 domain: 'managing-url-state'
280 description: >-
281 Validate, read, write, and transform search params with
282 schema validation, adapters, middlewares, and custom
283 serialization.
284 type: core
285 packages:
286 - '@tanstack/react-router'
287 - '@tanstack/router-core'
288 - '@tanstack/zod-adapter'
289 - '@tanstack/valibot-adapter'
290 - '@tanstack/arktype-adapter'
291 covers:
292 - validateSearch
293 - useSearch hook
294 - Route.useSearch
295 - getRouteApi().useSearch
296 - search middlewares
297 - retainSearchParams
298 - stripSearchParams
299 - custom serialization (parseSearch / stringifySearch)
300 - zod adapter / valibot adapter / arktype adapter
301 - search param inheritance from parent routes
302 - structural sharing for search params
303 tasks:
304 - 'Add validated search params to a route'
305 - 'Read search params in components'
306 - 'Update search params while preserving others'
307 - 'Share search params across parent and child routes'
308 - 'Set up search param middlewares for retention/stripping'
309 - 'Configure custom search param serialization'
310 - 'Handle arrays, objects, and dates in search params'
311 subsystems:
312 - name: 'Zod adapter'
313 package: '@tanstack/zod-adapter'
314 config_surface: 'zodValidator, fallback() wrapper for .catch/.default type correctness'
315 - name: 'Valibot adapter'
316 package: '@tanstack/valibot-adapter'
317 config_surface: 'Standard Schema compliant, requires valibot 1.0'
318 - name: 'ArkType adapter'
319 package: '@tanstack/arktype-adapter'
320 config_surface: 'Standard Schema compliant, requires arktype 2.0-rc, pass directly to validateSearch'
321 reference_candidates:
322 - topic: 'search param validation patterns'
323 reason: '>10 distinct patterns (basic, optional, arrays, objects, dates, discriminated unions, transforms, conditional, cross-route inheritance, middleware chaining)'
324 failure_modes:
325 - mistake: 'Using zod .catch() instead of adapter fallback()'
326 mechanism: >-
327 Zod .catch() makes the output type unknown, losing type
328 safety. The @tanstack/zod-adapter fallback() preserves
329 the correct inferred type.
330 wrong_pattern: |
331 z.object({ page: z.number().catch(1) })
332 correct_pattern: |
333 import { fallback } from '@tanstack/zod-adapter'
334 z.object({ page: fallback(z.number(), 1) })
335 source: 'docs/router/guide/search-params.md'
336 priority: HIGH
337 status: active
338β
339 - mistake: 'Returning entire search object from loaderDeps'
340 mechanism: >-
341 loaderDeps: ({ search }) => search causes loader to
342 re-run on ANY search param change, not just relevant ones.
343 Deep equality comparison fires on every unrelated change.
344 wrong_pattern: |
345 loaderDeps: ({ search }) => search
346 correct_pattern: |
347 loaderDeps: ({ search }) => ({ page: search.page })
348 source: 'docs/router/guide/data-loading.md'
349 priority: HIGH
350 status: active
351 skills: ['search-params', 'data-loading']
352β
353 - mistake: 'Passing Date objects in search params'
354 mechanism: >-
355 Date objects serialize to [object Object] in URLs.
356 Must convert to ISO strings for correct serialization.
357 wrong_pattern: |
358 <Link search={{ startDate: new Date() }}>
359 correct_pattern: |
360 <Link search={{ startDate: new Date().toISOString() }}>
361 source: 'docs/router/how-to/arrays-objects-dates-search-params.md'
362 priority: HIGH
363 status: active
364β
365 - mistake: 'Parent route missing validateSearch blocks inheritance'
366 mechanism: >-
367 Child routes cannot access shared search params unless
368 the parent route defines validateSearch. Without it,
369 the types and runtime values are not available.
370 source: 'docs/router/how-to/share-search-params-across-routes.md'
371 priority: MEDIUM
372 status: active
373β
374 - name: 'Path Params'
375 slug: 'path-params'
376 domain: 'managing-url-state'
377 description: >-
378 Define and consume dynamic path segments, splat routes,
379 optional params, and prefix/suffix patterns.
380 type: core
381 packages:
382 - '@tanstack/react-router'
383 - '@tanstack/router-core'
384 covers:
385 - '$paramName dynamic segments'
386 - '$ splat / _splat'
387 - '{-$paramName} optional params'
388 - '{$paramName} prefix/suffix patterns'
389 - useParams hook
390 - params.parse / params.stringify
391 - pathParamsAllowedCharacters
392 tasks:
393 - 'Define routes with dynamic path parameters'
394 - 'Use splat routes for catch-all matching'
395 - 'Set up optional path parameters for i18n'
396 - 'Navigate with type-safe path params'
397 failure_modes:
398 - mistake: 'Interpolating path params into to string'
399 mechanism: >-
400 Same as navigation failure mode β agents build template
401 literal paths instead of using params option.
402 source: 'docs/router/guide/navigation.md'
403 priority: CRITICAL
404 status: active
405 skills: ['path-params', 'navigation']
406β
407 - mistake: 'Using * for splat routes instead of $'
408 mechanism: >-
409 TanStack Router uses $ for splat routes, not * like some
410 other routers. The captured value is under _splat key,
411 not * (though * works in v1 for backwards compat, removed in v2).
412 source: 'docs/router/routing/routing-concepts.md'
413 priority: MEDIUM
414 status: 'fixed-but-legacy-risk'
415 version_context: '* works in v1 for compat but will be removed in v2'
416β
417 - mistake: 'Using curly braces for basic dynamic segments'
418 mechanism: >-
419 Basic dynamic segments use $postId (no braces). Curly
420 braces are only for prefix/suffix patterns like {$postId}.txt
421 or optional params {-$locale}.
422 source: 'docs/router/guide/path-params.md'
423 priority: MEDIUM
424 status: active
425β
426 # ββ Loading Data βββββββββββββββββββββββββββββββββββββββββββββββββ
427 - name: 'Data Loading'
428 slug: 'data-loading'
429 domain: 'loading-data'
430 description: >-
431 Load data via route loaders with built-in SWR caching,
432 configure staleTime/gcTime, use loaderDeps for cache keys,
433 handle pending and error states, and inject dependencies
434 via router context.
435 type: core
436 packages:
437 - '@tanstack/react-router'
438 - '@tanstack/router-core'
439 covers:
440 - loader option
441 - loaderDeps
442 - staleTime / gcTime / defaultPreloadStaleTime
443 - pendingComponent / pendingMs / pendingMinMs
444 - errorComponent / onError / onCatch
445 - beforeLoad
446 - router context / createRootRouteWithContext
447 - router.invalidate
448 - Await component
449 - deferred data loading
450 tasks:
451 - 'Add a data loader to a route'
452 - 'Configure cache timing (staleTime, gcTime)'
453 - 'Set up loader dependencies for search-param-driven data'
454 - 'Show pending UI during slow loads'
455 - 'Handle loader errors with error boundaries'
456 - 'Inject dependencies via router context'
457 - 'Defer non-critical data with unawaited promises'
458 - 'Invalidate cached data after mutations'
459 failure_modes:
460 - mistake: 'Assuming loaders only run on the server'
461 mechanism: >-
462 TanStack Router is client-first. Loaders run on the client
463 by default (and also on the server if using TanStack Start).
464 Agents trained on Remix/Next assume loaders are server-only
465 and put server-only code (DB queries, fs access) in them.
466 source: 'maintainer interview'
467 priority: CRITICAL
468 status: active
469 skills: ['data-loading', 'ssr']
470β
471 - mistake: 'Not understanding staleTime default is 0'
472 mechanism: >-
473 Default staleTime is 0, meaning data is always considered
474 stale and reloads in background on every route re-match.
475 Agents may not set staleTime, causing excessive refetching.
476 source: 'docs/router/guide/data-loading.md'
477 priority: MEDIUM
478 status: active
479β
480 - mistake: 'Using reset() instead of router.invalidate() in error components'
481 mechanism: >-
482 For loader errors, reset() only resets the error boundary
483 but does not re-run the loader. Must use router.invalidate()
484 to coordinate both reload and boundary reset.
485 wrong_pattern: |
486 function PostErrorComponent({ error, reset }) {
487 return <button onClick={reset}>Retry</button>
488 }
489 correct_pattern: |
490 function PostErrorComponent({ error, reset }) {
491 const router = useRouter()
492 return <button onClick={() => { router.invalidate(); reset() }}>Retry</button>
493 }
494 source: 'docs/router/guide/data-loading.md'
495 priority: HIGH
496 status: active
497β
498 - mistake: 'Double parentheses missing on createRootRouteWithContext'
499 mechanism: >-
500 createRootRouteWithContext<Type>() is a factory β it returns
501 a function. Must call it twice: createRootRouteWithContext<Type>()(routeOptions).
502 Missing second call is a common error.
503 wrong_pattern: |
504 const rootRoute = createRootRouteWithContext<{ auth: AuthState }>({
505 component: RootComponent,
506 })
507 correct_pattern: |
508 const rootRoute = createRootRouteWithContext<{ auth: AuthState }>()({
509 component: RootComponent,
510 })
511 source: 'docs/router/guide/data-loading.md'
512 priority: HIGH
513 status: active
514β
515 - mistake: 'Using React hooks in beforeLoad or loader'
516 mechanism: >-
517 beforeLoad and loader are not React components β hooks
518 cannot be called in them. Must extract hook state in a
519 wrapper component and pass via router context.
520 source: 'docs/router/guide/router-context.md'
521 priority: HIGH
522 status: active
523β
524 compositions:
525 - library: '@tanstack/react-query'
526 skill: 'external-data-loading'
527β
528 - name: 'External Data Loading'
529 slug: 'external-data-loading'
530 domain: 'loading-data'
531 description: >-
532 Integrate TanStack Query (or other external caches) with
533 Router for coordinated data loading, SSR dehydration/hydration,
534 and streaming.
535 type: composition
536 packages:
537 - '@tanstack/react-router'
538 - '@tanstack/react-router-ssr-query'
539 covers:
540 - External cache coordination pattern
541 - "queryClient.query with staleTime: 'static' in loader"
542 - useSuspenseQuery in components
543 - setupRouterSsrQueryIntegration
544 - defaultPreloadStaleTime
545 - dehydrate / hydrate router options
546 - QueryClient per-request isolation
547 - Wrap router option for providers
548 tasks:
549 - 'Set up TanStack Query with Router'
550 - 'Preload query data in route loaders'
551 - 'Configure SSR dehydration/hydration with Query'
552 - 'Stream query data during SSR'
553 failure_modes:
554 - mistake: 'Not setting defaultPreloadStaleTime to 0 with external caches'
555 mechanism: >-
556 Router's built-in preload cache (30s default) prevents
557 external library from controlling freshness. Set
558 defaultPreloadStaleTime: 0 to let Query manage caching.
559 wrong_pattern: |
560 createRouter({ routeTree })
561 correct_pattern: |
562 createRouter({ routeTree, defaultPreloadStaleTime: 0 })
563 source: 'docs/router/guide/external-data-loading.md'
564 priority: HIGH
565 status: active
566β
567 - mistake: 'Creating QueryClient outside createRouter for SSR'
568 mechanism: >-
569 For SSR, QueryClient must be created inside createRouter
570 to ensure per-request isolation. A shared singleton leaks
571 data between requests.
572 wrong_pattern: |
573 const queryClient = new QueryClient()
574 const router = createRouter({ routeTree, context: { queryClient } })
575 correct_pattern: |
576 function createAppRouter() {
577 const queryClient = new QueryClient()
578 return createRouter({ routeTree, context: { queryClient } })
579 }
580 source: 'docs/router/guide/external-data-loading.md'
581 priority: HIGH
582 status: active
583β
584 - mistake: 'Awaiting a fire-and-forget query in loader blocks rendering'
585 mechanism: >-
586 For streaming/deferred patterns, start a query without awaiting
587 it and handle failures with catch(noop) β it starts fetching on
588 the server and streams without blocking. Awaiting defeats the purpose.
589 source: 'docs/router/integrations/query.md'
590 priority: MEDIUM
591 status: active
592β
593 # ββ Protecting Routes ββββββββββββββββββββββββββββββββββββββββββββ
594 - name: 'Auth and Guards'
595 slug: 'auth-and-guards'
596 domain: 'protecting-routes'
597 description: >-
598 Protect routes with authentication checks, authorization
599 guards, and RBAC patterns using beforeLoad redirects and
600 layout routes.
601 type: core
602 packages:
603 - '@tanstack/react-router'
604 - '@tanstack/router-core'
605 covers:
606 - beforeLoad for auth checks
607 - redirect() / throw redirect()
608 - isRedirect helper
609 - Authenticated layout routes (_authenticated)
610 - Non-redirect auth (inline login)
611 - RBAC with roles and permissions
612 - Auth provider integration (Auth0, Clerk, Supabase)
613 - Router context for auth state
614 tasks:
615 - 'Protect routes with authentication checks'
616 - 'Redirect unauthenticated users to login'
617 - 'Implement role-based access control'
618 - 'Integrate third-party auth providers'
619 - 'Pass auth state through router context'
620 failure_modes:
621 - mistake: 'Auth check in component instead of beforeLoad'
622 mechanism: >-
623 Component-level auth checks cause protected content to
624 flash before redirect. beforeLoad runs before any
625 component rendering and prevents the flash entirely.
626 wrong_pattern: |
627 component: () => {
628 const auth = useAuth()
629 if (!auth.isAuthenticated) return <Navigate to="/login" />
630 return <Dashboard />
631 }
632 correct_pattern: |
633 beforeLoad: ({ context }) => {
634 if (!context.auth.isAuthenticated) {
635 throw redirect({ to: '/login' })
636 }
637 }
638 source: 'docs/router/how-to/setup-authentication.md'
639 priority: HIGH
640 status: active
641β
642 - mistake: 'Not re-throwing redirects in try/catch'
643 mechanism: >-
644 redirect() works by throwing. If beforeLoad has a try/catch
645 for error handling, the redirect gets swallowed unless
646 re-thrown via isRedirect() check.
647 wrong_pattern: |
648 beforeLoad: async ({ context }) => {
649 try {
650 await validateSession(context.auth)
651 } catch (e) {
652 // swallows redirect!
653 console.error(e)
654 }
655 }
656 correct_pattern: |
657 beforeLoad: async ({ context }) => {
658 try {
659 await validateSession(context.auth)
660 } catch (e) {
661 if (isRedirect(e)) throw e
662 console.error(e)
663 }
664 }
665 source: 'docs/router/guide/authenticated-routes.md'
666 priority: HIGH
667 status: active
668β
669 - mistake: 'Trying to conditionally render root route component'
670 mechanism: >-
671 Root route is always rendered regardless of auth state.
672 Use a pathless layout route (_authenticated) with
673 beforeLoad for conditional rendering.
674 source: 'docs/router/faq.md'
675 priority: MEDIUM
676 status: active
677β
678 # ββ Rendering and Layout βββββββββββββββββββββββββββββββββββββββββ
679 - name: 'Code Splitting'
680 slug: 'code-splitting'
681 domain: 'rendering-and-layout'
682 description: >-
683 Split route code into lazy-loaded chunks using automatic
684 code splitting, .lazy.tsx files, or code-based lazy loading.
685 type: core
686 packages:
687 - '@tanstack/react-router'
688 - '@tanstack/router-plugin'
689 covers:
690 - autoCodeSplitting plugin option
691 - .lazy.tsx file convention
692 - createLazyFileRoute
693 - createLazyRoute
694 - lazyRouteComponent
695 - getRouteApi for code-split components
696 - codeSplitGroupings per-route override
697 - splitBehavior programmatic config
698 - Critical vs non-critical route properties
699 tasks:
700 - 'Enable automatic code splitting'
701 - 'Manually split a route with .lazy.tsx'
702 - 'Access typed hooks from code-split components'
703 - 'Customize which properties are split per route'
704 failure_modes:
705 - mistake: 'Exporting route property functions prevents code splitting'
706 mechanism: >-
707 Exported functions from route files are included in the
708 main bundle even with auto code splitting. Component
709 functions must NOT be exported.
710 wrong_pattern: |
711 export function PostsComponent() { return <div>Posts</div> }
712 correct_pattern: |
713 function PostsComponent() { return <div>Posts</div> }
714 source: 'docs/router/guide/automatic-code-splitting.md'
715 priority: HIGH
716 status: active
717β
718 - mistake: 'Trying to code-split the root route'
719 mechanism: >-
720 __root.tsx does not support code splitting β it is always
721 rendered regardless of current route.
722 source: 'docs/router/guide/code-splitting.md'
723 priority: MEDIUM
724 status: active
725β
726 - mistake: 'Splitting the loader adds double async cost'
727 mechanism: >-
728 Loader is already async. Splitting it requires fetching
729 the chunk AND then executing the loader, adding latency.
730 Loaders should stay in the main bundle unless there is
731 a specific reason to split them.
732 source: 'docs/router/guide/code-splitting.md'
733 priority: MEDIUM
734 status: active
735β
736 - mistake: 'Importing Route in code-split files for typed hooks'
737 mechanism: >-
738 Importing the Route object in a lazy-loaded file pulls
739 the route config into the lazy chunk, defeating code
740 splitting. Use getRouteApi('/path') instead.
741 wrong_pattern: |
742 import { Route } from './posts.tsx'
743 const data = Route.useLoaderData()
744 correct_pattern: |
745 import { getRouteApi } from '@tanstack/react-router'
746 const route = getRouteApi('/posts')
747 const data = route.useLoaderData()
748 source: 'docs/router/guide/code-splitting.md'
749 priority: HIGH
750 status: active
751β
752 - name: 'Not Found and Errors'
753 slug: 'not-found-and-errors'
754 domain: 'rendering-and-layout'
755 description: >-
756 Handle not-found routes, missing resources, and route-level
757 errors with notFound(), notFoundComponent, errorComponent,
758 and CatchBoundary.
759 type: core
760 packages:
761 - '@tanstack/react-router'
762 - '@tanstack/router-core'
763 covers:
764 - notFound() function
765 - notFoundComponent
766 - defaultNotFoundComponent
767 - notFoundMode (fuzzy / root)
768 - errorComponent
769 - onError / onCatch
770 - CatchBoundary component
771 - NotFoundRoute (deprecated)
772 tasks:
773 - 'Add a 404 page for unmatched routes'
774 - 'Throw not-found for missing resources in loaders'
775 - 'Configure error boundaries per route'
776 - 'Target specific routes with notFound()'
777 failure_modes:
778 - mistake: 'Using deprecated NotFoundRoute'
779 mechanism: >-
780 NotFoundRoute is deprecated. When present, notFound() and
781 notFoundComponent will NOT work. Must remove NotFoundRoute
782 and use notFoundComponent instead.
783 source: 'docs/router/guide/not-found-errors.md'
784 priority: HIGH
785 status: 'fixed-but-legacy-risk'
786 version_context: 'NotFoundRoute deprecated, will be removed in next major'
787β
788 - mistake: 'Expecting useLoaderData to work in notFoundComponent'
789 mechanism: >-
790 When notFoundComponent renders, the route's loader may
791 not have completed. useLoaderData() may return undefined.
792 Use useParams, useSearch, or useRouteContext instead.
793 source: 'docs/router/guide/not-found-errors.md'
794 priority: MEDIUM
795 status: active
796β
797 - mistake: 'Leaf route cannot handle not-found errors'
798 mechanism: >-
799 Routes without children never render Outlet and therefore
800 cannot catch not-found errors. Only routes with children
801 (or the root route) can have notFoundComponent.
802 source: 'docs/router/guide/not-found-errors.md'
803 priority: MEDIUM
804 status: active
805β
806 - name: 'Route Masking'
807 slug: 'route-masking'
808 domain: 'rendering-and-layout'
809 description: >-
810 Mask the browser URL while navigating to a different internal
811 route, with configurable unmask behavior.
812 type: core
813 packages:
814 - '@tanstack/react-router'
815 - '@tanstack/router-core'
816 covers:
817 - mask option on Link / navigate
818 - createRouteMask
819 - routeMasks router option
820 - unmaskOnReload
821 - location.maskedLocation
822 - location.state.__tempLocation
823 tasks:
824 - 'Show a modal route with a clean URL'
825 - 'Configure declarative route masks'
826 - 'Control unmask behavior on page reload'
827 failure_modes:
828 - mistake: 'Expecting masked URLs to survive sharing'
829 mechanism: >-
830 Masking data is stored in browser history state. When a
831 URL is shared or opened in a new tab, masking data is
832 lost and the visible URL is used directly.
833 source: 'docs/router/guide/route-masking.md'
834 priority: MEDIUM
835 status: active
836β
837 # ββ Type Safety ββββββββββββββββββββββββββββββββββββββββββββββββββ
838 - name: 'Type Safety'
839 slug: 'type-safety'
840 domain: 'type-safety'
841 description: >-
842 Leverage TanStack Router's fully inferred type system.
843 Avoid unnecessary type annotations, narrow routes with from,
844 and optimize TypeScript performance.
845 type: core
846 packages:
847 - '@tanstack/react-router'
848 - '@tanstack/router-core'
849 covers:
850 - Full type inference philosophy
851 - Register module declaration
852 - from narrowing on hooks and Link
853 - strict false for shared components
854 - getRouteApi for code-split typed access
855 - addChildren with object syntax for TS perf
856 - LinkProps / ValidateLinkOptions type utilities
857 - as const satisfies pattern
858 tasks:
859 - 'Register router types for global type safety'
860 - 'Narrow route types with from parameter'
861 - 'Use getRouteApi in code-split components'
862 - 'Optimize TypeScript performance in large route trees'
863 - 'Build type-safe link option utilities'
864 failure_modes:
865 - mistake: 'Adding type annotations or casts to inferred values'
866 mechanism: >-
867 TanStack Router is fully type-safe with full inference.
868 Adding as Type, generic type parameters, satisfies, or
869 explicit type annotations is unnecessary and can mask
870 real type errors or break the inference chain.
871 wrong_pattern: |
872 const search = useSearch({ from: '/posts' }) as { page: number }
873 correct_pattern: |
874 const search = useSearch({ from: '/posts' })
875 // search.page is already typed as number
876 source: 'maintainer interview'
877 priority: CRITICAL
878 status: active
879β
880 - mistake: 'Using un-narrowed LinkProps type'
881 mechanism: >-
882 LinkProps without generics is an extremely large union type.
883 Using it as a variable type causes severe TS performance
884 degradation. Use as const satisfies or narrow with generics.
885 wrong_pattern: |
886 const props: LinkProps = { to: '/posts' }
887 correct_pattern: |
888 const props = { to: '/posts' } as const satisfies LinkProps
889 source: 'docs/router/guide/type-safety.md'
890 priority: HIGH
891 status: active
892β
893 - mistake: 'Not narrowing Link/useNavigate with from'
894 mechanism: >-
895 Without from, search resolves to a union of ALL routes
896 search params. TypeScript check time grows linearly with
897 route count. Always provide from to narrow.
898 wrong_pattern: |
899 <Link to=".." search={{ page: 0 }} />
900 correct_pattern: |
901 <Link from={Route.fullPath} to=".." search={{ page: 0 }} />
902 source: 'docs/router/guide/type-safety.md'
903 priority: HIGH
904 status: active
905β
906 # ββ Server-Side Rendering ββββββββββββββββββββββββββββββββββββββββ
907 - name: 'SSR'
908 slug: 'ssr'
909 domain: 'server-side-rendering'
910 description: >-
911 Set up server-side rendering with non-streaming or streaming
912 approaches, manage hydration, and handle document head.
913 type: core
914 packages:
915 - '@tanstack/react-router'
916 - '@tanstack/router-core'
917 covers:
918 - RouterClient / RouterServer
919 - renderRouterToString / renderRouterToStream
920 - createRequestHandler
921 - defaultRenderHandler / defaultStreamHandler
922 - HeadContent / Scripts components
923 - head route option (meta, links, styles, scripts)
924 - ScriptOnce component
925 - Automatic loader dehydration/hydration
926 - Memory history on server
927 - Data serialization (Date, Error, FormData, undefined)
928 tasks:
929 - 'Set up non-streaming SSR with Express'
930 - 'Set up streaming SSR'
931 - 'Configure document head management'
932 - 'Handle hydration mismatches'
933 failure_modes:
934 - mistake: 'Using browser APIs in loaders without environment check'
935 mechanism: >-
936 Loaders run on both client and server when using SSR.
937 Browser-only APIs (window, document, localStorage) will
938 throw on the server.
939 source: 'docs/router/guide/ssr.md'
940 priority: HIGH
941 status: active
942 skills: ['ssr', 'data-loading']
943β
944 - mistake: 'Using hash fragments for server-rendered content'
945 mechanism: >-
946 Hash fragments are client-only β browsers never send them
947 to the server. Using hash for conditional rendering causes
948 hydration mismatches during SSR.
949 source: 'docs/router/guide/navigation.md'
950 priority: MEDIUM
951 status: active
952β
953 - mistake: 'Generating Next.js or Remix SSR patterns'
954 mechanism: >-
955 Agents trained on Next.js generate getServerSideProps,
956 App Router patterns, or server components. Agents trained
957 on Remix generate server-only loader exports. TanStack
958 Router has its own SSR API (RouterClient/RouterServer).
959 source: 'maintainer interview'
960 priority: CRITICAL
961 status: active
962 skills: ['ssr', 'route-setup', 'data-loading']
963β
964 # ββ Migration ββββββββββββββββββββββββββββββββββββββββββββββββββββ
965 - name: 'Migrate from React Router'
966 slug: 'migrate-from-react-router'
967 domain: 'defining-routes'
968 description: >-
969 Step-by-step migration from React Router v7 to TanStack Router,
970 covering route definitions, navigation, search params, and
971 data loading.
972 type: lifecycle
973 packages:
974 - '@tanstack/react-router'
975 - '@tanstack/router-plugin'
976 covers:
977 - Migration checklist
978 - Route definition conversion
979 - Link / useNavigate API differences
980 - useSearchParams to validateSearch + useSearch
981 - useParams with from
982 - Outlet replacement
983 - Loader conversion
984 - Code splitting differences
985 tasks:
986 - 'Migrate routes from React Router to TanStack Router'
987 - 'Convert React Router Links and navigation'
988 - 'Replace useSearchParams with validated search params'
989 - 'Convert React Router loaders'
990 failure_modes:
991 - mistake: 'Leaving React Router imports alongside TanStack Router'
992 mechanism: >-
993 React Router and TanStack Router share similar API names
994 (Link, useNavigate, Outlet). Leftover React Router imports
995 cause context errors ("cannot use useNavigate outside of
996 context"). Uninstall react-router-dom to surface these.
997 source: 'docs/router/how-to/migrate-from-react-router.md'
998 priority: HIGH
999 status: active
1000β
1001 - mistake: 'Using React Router useSearchParams pattern'
1002 mechanism: >-
1003 React Router uses useSearchParams() returning URLSearchParams.
1004 TanStack Router uses validateSearch schema + useSearch()
1005 returning typed objects. Agents may generate the RR pattern.
1006 wrong_pattern: |
1007 const [searchParams, setSearchParams] = useSearchParams()
1008 const page = Number(searchParams.get('page'))
1009 correct_pattern: |
1010 // In route definition:
1011 validateSearch: z.object({ page: fallback(z.number(), 1) })
1012 // In component:
1013 const { page } = Route.useSearch()
1014 source: 'docs/router/installation/migrate-from-react-router.md'
1015 priority: HIGH
1016 status: active
1017β
1018tensions:
1019 - name: 'Type safety strictness vs rapid prototyping'
1020 skills: ['type-safety', 'route-setup']
1021 description: >-
1022 Full type inference requires proper setup (Register, correct
1023 property order, getParentRoute). This upfront cost conflicts
1024 with quick prototyping where developers want to skip setup.
1025 implication: >-
1026 Agents skip Register declaration or use type casts to silence
1027 errors, producing code that compiles but has no type safety.
1028β
1029 - name: 'Client-first loaders vs SSR expectations'
1030 skills: ['data-loading', 'ssr']
1031 description: >-
1032 Loaders are client-first by design but agents assume they are
1033 server-only (Remix/Next mental model). This tension means
1034 browser APIs work in loaders by default but break under SSR.
1035 implication: >-
1036 Agents either put server-only code in client loaders or avoid
1037 browser APIs unnecessarily, depending on which framework mental
1038 model they default to.
1039β
1040 - name: 'Built-in SWR cache vs external cache coordination'
1041 skills: ['data-loading', 'external-data-loading']
1042 description: >-
1043 Router has built-in caching with staleTime/gcTime defaults.
1044 When using an external cache like React Query, the built-in
1045 cache must be bypassed (defaultPreloadStaleTime: 0) or it
1046 conflicts with the external library's freshness management.
1047 implication: >-
1048 Agents use both caches simultaneously without disabling the
1049 built-in one, causing stale data or double-fetching.
1050β
1051 - name: 'Code splitting granularity vs loader performance'
1052 skills: ['code-splitting', 'data-loading']
1053 description: >-
1054 Splitting more aggressively reduces initial bundle but splitting
1055 the loader adds a network round-trip before data can be fetched.
1056 The optimal split point differs per route.
1057 implication: >-
1058 Agents split everything including loaders, adding latency to
1059 data loading without understanding the tradeoff.
1060β
1061cross_references:
1062 - from: 'route-setup'
1063 to: 'type-safety'
1064 reason: 'Register declaration and property order are prerequisites for type inference'
1065 - from: 'navigation'
1066 to: 'search-params'
1067 reason: 'Link search prop and navigate search option directly interact with search param validation'
1068 - from: 'data-loading'
1069 to: 'search-params'
1070 reason: 'loaderDeps consumes validated search params as cache keys'
1071 - from: 'data-loading'
1072 to: 'external-data-loading'
1073 reason: 'Understanding built-in caching is prerequisite for coordinating with external caches'
1074 - from: 'auth-and-guards'
1075 to: 'data-loading'
1076 reason: 'beforeLoad runs before loader β auth context flows into loader via route context'
1077 - from: 'code-splitting'
1078 to: 'data-loading'
1079 reason: 'Loader splitting decisions affect data loading performance'
1080 - from: 'ssr'
1081 to: 'data-loading'
1082 reason: 'SSR changes where loaders execute β must handle both environments'
1083 - from: 'ssr'
1084 to: 'external-data-loading'
1085 reason: 'SSR dehydration/hydration requires special setup for Query integration'
1086 - from: 'not-found-and-errors'
1087 to: 'data-loading'
1088 reason: 'notFound() thrown in loaders interacts with error boundaries and loader data availability'
1089 - from: 'migrate-from-react-router'
1090 to: 'route-setup'
1091 reason: 'Migration requires understanding TanStack Router route setup to replace RR patterns'
1092β
1093gaps: []