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