Skip to content

Commit 289dd2d

Browse files
committed
docs: improve Router and Start agent skills
1 parent edf5575 commit 289dd2d

40 files changed

Lines changed: 506 additions & 92 deletions

File tree

‎_artifacts/skill_tree.yaml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,6 @@ skills:
135135
for auth state.
136136
requires:
137137
- 'router-core'
138-
- 'router-core/data-loading'
139138
sources:
140139
- 'TanStack/router:docs/router/guide/authenticated-routes.md'
141140
- 'TanStack/router:docs/router/how-to/setup-authentication.md'

‎packages/react-start/skills/_artifacts/domain_map.yaml‎

Lines changed: 67 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# domain_map.yaml
22
# Generated by skill-domain-discovery
33
# Library: TanStack Start
4-
# Version: 1.166.2
4+
# Version: 1.168.32
55
# Date: 2026-03-07
66
# Status: reviewed
77

88
library:
99
name: '@tanstack/react-start'
10-
version: '1.166.2'
10+
version: '1.168.32'
1111
repository: 'https://github.com/TanStack/router'
1212
description: >-
1313
Full-stack React framework built on TanStack Router and Vite. Adds
@@ -204,6 +204,39 @@ skills:
204204
priority: CRITICAL
205205
status: active
206206

207+
- mistake: 'Relying on a route guard to protect a server function'
208+
mechanism: >-
209+
beforeLoad protects route UX, but createServerFn exposes an
210+
independently callable endpoint. Private handlers must enforce
211+
authentication and authorization themselves or through middleware.
212+
source: 'protocol-v4 evaluation'
213+
priority: CRITICAL
214+
status: active
215+
216+
- mistake: 'Self-fetching a relative API URL from an SSR loader'
217+
mechanism: >-
218+
Loaders also run on the server, where relative URLs may not have a
219+
base. App-internal loaders should call a server function directly.
220+
source: 'protocol-v4 evaluation'
221+
priority: CRITICAL
222+
status: active
223+
224+
- mistake: 'Mutating without invalidating cached loader data'
225+
mechanism: >-
226+
Local state can show a write that was not persisted or leave route
227+
cache stale. Await the write, invalidate, and verify a fresh reload.
228+
source: 'protocol-v4 evaluation'
229+
priority: HIGH
230+
status: active
231+
232+
- mistake: 'Treating typecheck as proof of output schema propagation'
233+
mechanism: >-
234+
A typed model can still be projected or serialized without the new
235+
field. Assert the actual handler or HTTP payload at runtime.
236+
source: 'protocol-v4 evaluation'
237+
priority: CRITICAL
238+
status: active
239+
207240
# ── Middleware and Context ───────────────────────────────────────
208241
- name: 'Middleware'
209242
slug: 'middleware'
@@ -354,6 +387,14 @@ skills:
354387
priority: CRITICAL
355388
status: active
356389

390+
- mistake: 'Using a relative URL in an isomorphic loader'
391+
mechanism: >-
392+
Browser fetch resolves relative URLs against the document, while an
393+
SSR runtime may have no base URL. Use a server function boundary.
394+
source: 'protocol-v4 evaluation'
395+
priority: CRITICAL
396+
status: active
397+
357398
# ── Server Routes ────────────────────────────────────────────────
358399
- name: 'Server Routes'
359400
slug: 'server-routes'
@@ -387,6 +428,30 @@ skills:
387428
priority: MEDIUM
388429
status: active
389430

431+
- mistake: 'Relying on page auth to protect a server route'
432+
mechanism: >-
433+
API handlers are directly callable and must authenticate and
434+
authorize private reads and writes at the handler boundary.
435+
source: 'protocol-v4 evaluation'
436+
priority: CRITICAL
437+
status: active
438+
439+
- mistake: 'Self-fetching a server route from an SSR loader'
440+
mechanism: >-
441+
A relative API URL can fail during SSR. Share one server-side service
442+
between a server function and server route instead.
443+
source: 'protocol-v4 evaluation'
444+
priority: CRITICAL
445+
status: active
446+
447+
- mistake: 'Omitting a field from serialized response output'
448+
mechanism: >-
449+
Typechecking does not inspect the runtime Response payload. Test the
450+
serialized output when a schema changes.
451+
source: 'protocol-v4 evaluation'
452+
priority: CRITICAL
453+
status: active
454+
390455
# ── Deployment and Rendering ─────────────────────────────────────
391456
- name: 'Deployment'
392457
slug: 'deployment'

‎packages/react-start/skills/_artifacts/skill_spec.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
1818
| Skill | Type | Domain | What it covers | Failure modes |
1919
| ------------------- | --------- | ------------------------ | ------------------------------------------------------- | ------------- |
2020
| start-setup | core | project-setup | tanstackStart(), getRouter(), root route, entries | 3 |
21-
| server-functions | core | server-functions | createServerFn, validation, useServerFn, streaming | 4 |
21+
| server-functions | core | server-functions | createServerFn, validation, useServerFn, streaming | 8 |
2222
| middleware | core | middleware-and-context | createMiddleware, context, global middleware, factories | 3 |
23-
| execution-model | core | execution-model | Isomorphic defaults, environment functions, env vars | 4 |
24-
| server-routes | core | server-routes | server property, HTTP handlers, createHandlers | 2 |
23+
| execution-model | core | execution-model | Isomorphic defaults, environment functions, env vars | 5 |
24+
| server-routes | core | server-routes | server property, HTTP handlers, createHandlers | 5 |
2525
| deployment | core | deployment-and-rendering | Hosting, SSR modes, prerendering, SEO | 3 |
2626
| server-components | sub-skill | deployment-and-rendering | React Server Components, cache ownership, selective SSR | 3 |
2727
| react-start | framework | project-setup | React bindings, useServerFn, full setup | 3 |
@@ -37,14 +37,18 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
3737
| 2 | Enabling verbatimModuleSyntax in tsconfig | HIGH | docs/build-from-scratch |
3838
| 3 | Missing Scripts component in root route | HIGH | docs/guide/routing |
3939

40-
### server-functions (4 failure modes)
40+
### server-functions (8 failure modes)
4141

4242
| # | Mistake | Priority | Source |
4343
| --- | --------------------------------------------------------------------------- | -------- | --------------------------- |
4444
| 1 | Putting server-only code in loaders instead of server functions | CRITICAL | maintainer interview |
4545
| 2 | Generating Next.js/Remix server patterns ("use server", getServerSideProps) | CRITICAL | maintainer interview |
4646
| 3 | Using dynamic imports for server functions | HIGH | docs/guide/server-functions |
4747
| 4 | Not using useServerFn for component calls | MEDIUM | docs/guide/server-functions |
48+
| 5 | Relying on a route guard to protect a server function | CRITICAL | protocol-v4 evaluation |
49+
| 6 | Self-fetching a relative API URL from an SSR loader | CRITICAL | protocol-v4 evaluation |
50+
| 7 | Mutating without invalidating the loader or query cache | HIGH | protocol-v4 evaluation |
51+
| 8 | Treating typecheck as proof of output schema propagation | CRITICAL | protocol-v4 evaluation |
4852

4953
### middleware (3 failure modes)
5054

@@ -54,21 +58,25 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
5458
| 2 | Confusing request vs server function middleware | MEDIUM | docs/guide/middleware |
5559
| 3 | Wrong middleware method order | MEDIUM | docs/guide/middleware |
5660

57-
### execution-model (4 failure modes)
61+
### execution-model (5 failure modes)
5862

5963
| # | Mistake | Priority | Source |
6064
| --- | ------------------------------------------------- | -------- | -------------------------------- |
6165
| 1 | Assuming loaders are server-only | CRITICAL | docs/guide/execution-model |
6266
| 2 | Exposing secrets via module-level process.env | CRITICAL | docs/guide/execution-model |
6367
| 3 | Using VITE\_ prefix for server secrets | CRITICAL | docs/guide/environment-variables |
6468
| 4 | Hydration mismatches from env-dependent rendering | HIGH | docs/guide/execution-model |
69+
| 5 | Using relative fetch in an isomorphic loader | CRITICAL | protocol-v4 evaluation |
6570

66-
### server-routes (2 failure modes)
71+
### server-routes (5 failure modes)
6772

6873
| # | Mistake | Priority | Source |
6974
| --- | ---------------------------------------- | -------- | ------------------------ |
7075
| 1 | Duplicate route path resolution | MEDIUM | docs/guide/server-routes |
7176
| 2 | Forgetting to await request body methods | MEDIUM | docs/guide/server-routes |
77+
| 3 | Relying on page auth to protect the API | CRITICAL | protocol-v4 evaluation |
78+
| 4 | Self-fetching the API from an SSR loader | CRITICAL | protocol-v4 evaluation |
79+
| 5 | Omitting a field from serialized output | CRITICAL | protocol-v4 evaluation |
7280

7381
### deployment (3 failure modes)
7482

‎packages/react-start/skills/_artifacts/skill_tree.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# skills/_artifacts/start_skill_tree.yaml
22
library:
33
name: '@tanstack/react-start'
4-
version: '1.166.2'
4+
version: '1.168.32'
55
repository: 'https://github.com/TanStack/router'
66
description: >-
77
Full-stack React framework built on TanStack Router and Vite.

‎packages/react-start/skills/lifecycle/migrate-from-nextjs/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: >-
77
fetching pattern changes.
88
type: lifecycle
99
library: tanstack-start
10-
library_version: '1.166.2'
10+
library_version: '1.168.32'
1111
requires:
1212
- start-core
1313
- react-start

‎packages/react-start/skills/react-start/SKILL.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: >-
77
hook.
88
type: framework
99
library: tanstack-start
10-
library_version: '1.166.2'
10+
library_version: '1.168.32'
1111
framework: react
1212
requires:
1313
- start-core
@@ -18,9 +18,7 @@ sources:
1818

1919
# React Start (`@tanstack/react-start`)
2020

21-
This skill builds on start-core. Read [start-core](../../../start-client-core/skills/start-core/SKILL.md) first for foundational concepts.
22-
23-
This skill covers the React-specific bindings, setup, and patterns for TanStack Start.
21+
This is the React Start entry skill. Use the workflow below, then load only the package skill that owns the boundary you are changing. Do not read `start-core`, Router Core, and React Router manuals in full before starting.
2422

2523
For React Server Components patterns, see [react-start/server-components](./server-components/SKILL.md).
2624

@@ -30,6 +28,16 @@ For React Server Components patterns, see [react-start/server-components](./serv
3028
3129
> **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values.
3230
31+
## Full-Stack Workflow
32+
33+
1. Define the route and component with `createFileRoute`.
34+
2. Put private or server-only reads and writes in `createServerFn`; call reads directly from loaders.
35+
3. Use `useServerFn` for component mutations, then invalidate the router or query cache after the write resolves.
36+
4. Enforce auth in every private server function or server route. Add `beforeLoad` separately for navigation UX.
37+
5. Run the initial SSR path, client navigation, mutation plus reload, direct anonymous endpoint request, runtime response assertion, type tests, and production build.
38+
39+
Load `start-core/server-routes` instead of `server-functions` only when a raw HTTP endpoint is required. Load `router-core/*` only for the specific routing concern involved, such as params or search validation.
40+
3341
## Package API Surface
3442

3543
`@tanstack/react-start` re-exports everything from `@tanstack/start-client-core` plus:

‎packages/react-start/skills/react-start/server-components/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ description: >-
1414
comparison.
1515
type: sub-skill
1616
library: tanstack-start
17-
library_version: '1.166.2'
17+
library_version: '1.168.32'
1818
requires:
1919
- react-start
2020
- start-core/server-functions

‎packages/router-core/skills/router-core/SKILL.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: >-
77
file naming conventions. Entry point for all router skills.
88
type: core
99
library: tanstack-router
10-
library_version: '1.166.2'
10+
library_version: '1.171.15'
1111
---
1212

1313
# TanStack Router Core
@@ -18,6 +18,8 @@ TanStack Router is a type-safe router for React and Solid with built-in SWR cach
1818
1919
> **CRITICAL**: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, NOT server-only like Remix/Next.js. Do not confuse TanStack Router APIs with Next.js or React Router.
2020
21+
Use this entry skill to choose one primary sub-skill. Do not load the full catalog. Load a second sub-skill only when the task crosses a real boundary, such as an authenticated loader that needs both `auth-and-guards` and `data-loading`.
22+
2123
## Sub-Skills
2224

2325
| Task | Sub-Skill |
@@ -66,6 +68,22 @@ Need server-side rendering?
6668
→ router-core/ssr
6769
```
6870

71+
## Cross-Cutting Completion Checks
72+
73+
For route refactors:
74+
75+
1. Rename or move the route file; do not hand-edit the generated `createFileRoute` path.
76+
2. Regenerate `routeTree.gen.ts` with the configured Router plugin or CLI.
77+
3. Update links, redirects, `from` narrowing, params, and tests that reference the old route.
78+
4. Run type tests and a production build. A typecheck alone does not prove route generation or bundling works.
79+
80+
For response schema changes:
81+
82+
1. Update the source model and shared validation schema.
83+
2. Update the server function or API serializer so the field exists at runtime.
84+
3. Update loader and component consumers without casts.
85+
4. Assert the actual response payload in a unit or integration test. Typechecking cannot catch a serializer that omits the new field.
86+
6987
## Minimal Working Example
7088

7189
```tsx
@@ -136,4 +154,4 @@ The plugin auto-generates this string. If you rename a route file, the plugin up
136154

137155
## Version Note
138156

139-
This skill targets `@tanstack/router-core` v1.166.2 and `@tanstack/react-router` v1.166.2. APIs are stable. Splat routes use `$` (not `*`); the `*` compat alias will be removed in v2.
157+
This skill targets `@tanstack/router-core` v1.171.15. Splat routes use `$` (not `*`); the `*` compat alias will be removed in v2.

‎packages/router-core/skills/router-core/auth-and-guards/SKILL.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,9 @@ description: >-
88
for auth state.
99
type: sub-skill
1010
library: tanstack-router
11-
library_version: '1.166.2'
11+
library_version: '1.171.15'
1212
requires:
1313
- router-core
14-
- router-core/data-loading
1514
sources:
1615
- TanStack/router:docs/router/guide/authenticated-routes.md
1716
- TanStack/router:docs/router/how-to/setup-authentication.md
@@ -410,6 +409,9 @@ const getMyOrders = createServerFn({ method: 'GET' })
410409

411410
Rule of thumb: every `createServerFn`, server route, or API endpoint that touches user data needs `authMiddleware` (or an equivalent in-handler check). The route guard is for the page experience; the endpoint guard is for the data. See [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md) for the full session/middleware pattern.
412411

412+
### CRITICAL: The anonymous destination can still disclose protected data
413+
Protect the entire anonymous response, not only the API call. A public login or unauthorized page still leaks data if its title, copy, search params, or serialized loader state names the protected user, tenant, record, or resource. Test a direct anonymous request and follow redirects. Assert that the handler rejects before reading private data, no protected loader runs, the final HTML and serialized state contain no protected identity, and the redirect contains only a sanitized relative return URL.
414+
413415
### HIGH: Auth check in component instead of beforeLoad
414416

415417
Component-level auth checks cause a **flash of protected content** before the redirect:
@@ -490,8 +492,6 @@ export const Route = createFileRoute('/_authenticated')({
490492

491493
Place protected routes as children of the `_authenticated` layout route. Public routes (login, home, etc.) live outside it.
492494

493-
---
494-
495495
## Cross-References
496496

497497
- See also: **router-core/data-loading/SKILL.md** — `beforeLoad` runs before `loader`; auth context flows into loader via route context

‎packages/router-core/skills/router-core/code-splitting/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: >-
77
splitBehavior programmatic config, critical vs non-critical properties.
88
type: sub-skill
99
library: tanstack-router
10-
library_version: '1.166.2'
10+
library_version: '1.171.15'
1111
requires:
1212
- router-core
1313
sources:

0 commit comments

Comments
 (0)