Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

skill_spec.md

193 lines18.2 KB

1# TanStack Router β€” Skill Spec
2​
3TanStack Router is a type-safe router for React and Solid applications with built-in SWR caching, JSON-first search params, file-based route generation, and end-to-end type inference. It is client-first/isomorphic β€” loaders run on the client by default and additionally on the server when used with TanStack Start.
4​
5## Domains
6​
7| Domain | Description | Skills |
8| --------------------- | ------------------------------------------------------------------- | --------------------------------------------------- |
9| Defining Routes | Setting up route trees, configuring the router, registering types | route-setup, migrate-from-react-router |
10| Navigating | Links, imperative navigation, preloading, blocking | navigation |
11| Managing URL State | Search params and path params with validation and serialization | search-params, path-params |
12| Loading Data | Route loaders, SWR caching, external cache coordination, context/DI | data-loading, external-data-loading |
13| Protecting Routes | Auth guards, RBAC, beforeLoad redirects | auth-and-guards |
14| Rendering and Layout | Code splitting, error/not-found handling, route masking | code-splitting, not-found-and-errors, route-masking |
15| Type Safety | Inference patterns, narrowing, TS performance | type-safety |
16| Server-Side Rendering | SSR setup, hydration, head management | ssr |
17​
18## Skill Inventory
19​
20| Skill | Type | Domain | What it covers | Failure modes |
21| ------------------------- | ----------- | --------------------- | ------------------------------------------------------------------------------------ | ------------- |
22| route-setup | core | defining-routes | createRouter, file/code/virtual routing, Register, plugin config, ESLint | 5 |
23| navigation | core | navigating | Link, useNavigate, Navigate, preloading, blocking, active states, scroll restoration | 4 |
24| search-params | core | managing-url-state | validateSearch, useSearch, middlewares, serialization, adapters | 4 |
25| path-params | core | managing-url-state | $params, splats, optional params, prefix/suffix patterns | 3 |
26| data-loading | core | loading-data | loader, loaderDeps, staleTime/gcTime, pending/error, context/DI, deferred | 5 |
27| external-data-loading | composition | loading-data | TanStack Query integration, SSR dehydration/hydration, streaming | 3 |
28| auth-and-guards | core | protecting-routes | beforeLoad redirects, layout auth, RBAC, provider integration | 3 |
29| code-splitting | core | rendering-and-layout | autoCodeSplitting, .lazy.tsx, getRouteApi, split groupings | 4 |
30| not-found-and-errors | core | rendering-and-layout | notFound(), notFoundComponent, errorComponent, CatchBoundary | 3 |
31| route-masking | core | rendering-and-layout | mask option, createRouteMask, unmaskOnReload | 1 |
32| type-safety | core | type-safety | Register, from narrowing, TS perf, type utilities | 3 |
33| ssr | core | server-side-rendering | RouterClient/Server, streaming, hydration, head management | 3 |
34| migrate-from-react-router | lifecycle | defining-routes | Migration checklist, API mapping, search params conversion | 2 |
35​
36## Failure Mode Inventory
37​
38### route-setup (5 failure modes)
39​
40| # | Mistake | Priority | Source | Cross-skill? |
41| --- | ------------------------------------------------------ | -------- | --------------------------------------- | ------------ |
42| 1 | Missing router type registration | CRITICAL | docs/guide/creating-a-router | type-safety |
43| 2 | Not committing routeTree.gen.ts | HIGH | docs/faq | β€” |
44| 3 | Wrong route property order breaks type inference | HIGH | docs/eslint/create-route-property-order | β€” |
45| 4 | Placing TanStackRouter plugin after framework plugin | HIGH | docs/installation/with-vite | β€” |
46| 5 | Using getParentRoute incorrectly in code-based routing | HIGH | docs/decisions-on-dx | β€” |
47​
48### navigation (4 failure modes)
49​
50| # | Mistake | Priority | Source | Cross-skill? |
51| --- | -------------------------------------------------------- | -------- | --------------------------------------- | ------------- |
52| 1 | Interpolating params into the to string | CRITICAL | docs/guide/navigation | type-safety |
53| 2 | Using useNavigate instead of Link for clickable elements | MEDIUM | docs/guide/navigation | β€” |
54| 3 | Not providing from for relative navigation | HIGH | docs/guide/navigation | β€” |
55| 4 | Using search as object instead of function loses params | HIGH | docs/how-to/navigate-with-search-params | search-params |
56​
57### search-params (4 failure modes)
58​
59| # | Mistake | Priority | Source | Cross-skill? |
60| --- | ------------------------------------------------------ | -------- | -------------------------------- | ------------ |
61| 1 | Using zod .catch() instead of adapter fallback() | HIGH | docs/guide/search-params | β€” |
62| 2 | Returning entire search object from loaderDeps | HIGH | docs/guide/data-loading | data-loading |
63| 3 | Passing Date objects in search params | HIGH | docs/how-to/arrays-objects-dates | β€” |
64| 4 | Parent route missing validateSearch blocks inheritance | MEDIUM | docs/how-to/share-search-params | β€” |
65​
66### path-params (3 failure modes)
67​
68| # | Mistake | Priority | Source | Cross-skill? |
69| --- | --------------------------------------------- | -------- | ----------------------------- | ------------ |
70| 1 | Interpolating path params into `to` string | CRITICAL | docs/guide/navigation | navigation |
71| 2 | Using \* for splat routes instead of $ | MEDIUM | docs/routing/routing-concepts | β€” |
72| 3 | Using curly braces for basic dynamic segments | MEDIUM | docs/guide/path-params | β€” |
73​
74### data-loading (5 failure modes)
75​
76| # | Mistake | Priority | Source | Cross-skill? |
77| --- | ---------------------------------------------------------------- | -------- | ------------------------- | ------------ |
78| 1 | Assuming loaders only run on the server | CRITICAL | maintainer interview | ssr |
79| 2 | Not understanding staleTime default is 0 | MEDIUM | docs/guide/data-loading | β€” |
80| 3 | Using reset() instead of router.invalidate() in error components | HIGH | docs/guide/data-loading | β€” |
81| 4 | Double parentheses missing on createRootRouteWithContext | HIGH | docs/guide/data-loading | β€” |
82| 5 | Using React hooks in beforeLoad or loader | HIGH | docs/guide/router-context | β€” |
83​
84### external-data-loading (3 failure modes)
85​
86| # | Mistake | Priority | Source | Cross-skill? |
87| --- | ----------------------------------------------------------- | -------- | -------------------------------- | ------------ |
88| 1 | Not setting defaultPreloadStaleTime to 0 | HIGH | docs/guide/external-data-loading | β€” |
89| 2 | Creating QueryClient outside createRouter for SSR | HIGH | docs/guide/external-data-loading | β€” |
90| 3 | Awaiting a fire-and-forget query in loader blocks rendering | MEDIUM | docs/integrations/query | β€” |
91​
92### auth-and-guards (3 failure modes)
93​
94| # | Mistake | Priority | Source | Cross-skill? |
95| --- | --------------------------------------------------- | -------- | -------------------------------- | ------------ |
96| 1 | Auth check in component instead of beforeLoad | HIGH | docs/how-to/setup-authentication | β€” |
97| 2 | Not re-throwing redirects in try/catch | HIGH | docs/guide/authenticated-routes | β€” |
98| 3 | Trying to conditionally render root route component | MEDIUM | docs/faq | β€” |
99​
100### code-splitting (4 failure modes)
101​
102| # | Mistake | Priority | Source | Cross-skill? |
103| --- | ---------------------------------------------------------- | -------- | ----------------------------------- | ------------ |
104| 1 | Exporting route property functions prevents code splitting | HIGH | docs/guide/automatic-code-splitting | β€” |
105| 2 | Trying to code-split the root route | MEDIUM | docs/guide/code-splitting | β€” |
106| 3 | Splitting the loader adds double async cost | MEDIUM | docs/guide/code-splitting | β€” |
107| 4 | Importing Route in code-split files for typed hooks | HIGH | docs/guide/code-splitting | β€” |
108​
109### not-found-and-errors (3 failure modes)
110​
111| # | Mistake | Priority | Source | Cross-skill? |
112| --- | ---------------------------------------------------- | -------- | --------------------------- | ------------ |
113| 1 | Using deprecated NotFoundRoute | HIGH | docs/guide/not-found-errors | β€” |
114| 2 | Expecting useLoaderData to work in notFoundComponent | MEDIUM | docs/guide/not-found-errors | β€” |
115| 3 | Leaf route cannot handle not-found errors | MEDIUM | docs/guide/not-found-errors | β€” |
116​
117### route-masking (1 failure mode)
118​
119| # | Mistake | Priority | Source | Cross-skill? |
120| --- | ---------------------------------------- | -------- | ------------------------ | ------------ |
121| 1 | Expecting masked URLs to survive sharing | MEDIUM | docs/guide/route-masking | β€” |
122​
123### type-safety (3 failure modes)
124​
125| # | Mistake | Priority | Source | Cross-skill? |
126| --- | --------------------------------------------------- | -------- | ---------------------- | ------------ |
127| 1 | Adding type annotations or casts to inferred values | CRITICAL | maintainer interview | β€” |
128| 2 | Using un-narrowed LinkProps type | HIGH | docs/guide/type-safety | β€” |
129| 3 | Not narrowing Link/useNavigate with from | HIGH | docs/guide/type-safety | β€” |
130​
131### ssr (3 failure modes)
132​
133| # | Mistake | Priority | Source | Cross-skill? |
134| --- | ------------------------------------------------------- | -------- | --------------------- | ------------------------- |
135| 1 | Using browser APIs in loaders without environment check | HIGH | docs/guide/ssr | data-loading |
136| 2 | Using hash fragments for server-rendered content | MEDIUM | docs/guide/navigation | β€” |
137| 3 | Generating Next.js or Remix SSR patterns | CRITICAL | maintainer interview | route-setup, data-loading |
138​
139### migrate-from-react-router (2 failure modes)
140​
141| # | Mistake | Priority | Source | Cross-skill? |
142| --- | ------------------------------------------------------ | -------- | ------------------------------------------- | ------------ |
143| 1 | Leaving React Router imports alongside TanStack Router | HIGH | docs/how-to/migrate-from-react-router | β€” |
144| 2 | Using React Router useSearchParams pattern | HIGH | docs/installation/migrate-from-react-router | β€” |
145​
146## Tensions
147​
148| Tension | Skills | Agent implication |
149| ------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
150| Type safety strictness vs rapid prototyping | type-safety ↔ route-setup | Agents skip Register declaration or use type casts to silence errors |
151| Client-first loaders vs SSR expectations | data-loading ↔ ssr | Agents put server-only code in client loaders or avoid browser APIs unnecessarily |
152| Built-in SWR cache vs external cache coordination | data-loading ↔ external-data-loading | Agents use both caches simultaneously causing stale data or double-fetching |
153| Code splitting granularity vs loader performance | code-splitting ↔ data-loading | Agents split everything including loaders, adding latency |
154​
155## Cross-References
156​
157| From | To | Reason |
158| ------------------------- | --------------------- | ---------------------------------------------------------------------------------- |
159| route-setup | type-safety | Register declaration and property order are prerequisites for type inference |
160| navigation | search-params | Link search prop directly interacts with search param validation |
161| data-loading | search-params | loaderDeps consumes validated search params as cache keys |
162| data-loading | external-data-loading | Understanding built-in caching is prerequisite for external cache coordination |
163| auth-and-guards | data-loading | beforeLoad runs before loader β€” auth context flows into loader via route context |
164| code-splitting | data-loading | Loader splitting decisions affect data loading performance |
165| ssr | data-loading | SSR changes where loaders execute β€” must handle both environments |
166| ssr | external-data-loading | SSR dehydration/hydration requires special Query setup |
167| not-found-and-errors | data-loading | notFound() in loaders interacts with error boundaries and loader data availability |
168| migrate-from-react-router | route-setup | Migration requires understanding TanStack Router route setup |
169​
170## Subsystems & Reference Candidates
171​
172| Skill | Subsystems | Reference candidates |
173| ------------- | --------------------------------------------- | -------------------------------------------------------- |
174| route-setup | β€” | file naming conventions (>10 distinct conventions) |
175| search-params | Zod adapter, Valibot adapter, ArkType adapter | search param validation patterns (>10 distinct patterns) |
176| All others | β€” | β€” |
177​
178## Recommended Skill File Structure
179​
180- **Core skills:** route-setup, navigation, search-params, path-params, data-loading, code-splitting, not-found-and-errors, route-masking, type-safety, ssr, auth-and-guards
181- **Framework skills:** None needed separately β€” React and Solid share the same core API surface. Framework-specific notes belong inline.
182- **Lifecycle skills:** migrate-from-react-router
183- **Composition skills:** external-data-loading (TanStack Query)
184- **Reference files:** search-params (validation patterns), route-setup (file naming conventions)
185​
186## Composition Opportunities
187​
188| Library | Integration points | Composition skill needed? |
189| --------------------- | --------------------------------------------------------- | ------------------------------------------ |
190| @tanstack/react-query | Loader coordination, SSR dehydration/hydration, streaming | Yes β€” external-data-loading |
191| Zod | Search param validation | No β€” covered as subsystem in search-params |
192| Valibot | Search param validation | No β€” covered as subsystem in search-params |
193| ArkType | Search param validation | No β€” covered as subsystem in search-params |