Skip to content

Commit 8caa202

Browse files
Add a React Start server-components skill (#7181)
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
1 parent 26680c9 commit 8caa202

17 files changed

Lines changed: 1215 additions & 8 deletions

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -444,6 +444,65 @@ skills:
444444
priority: MEDIUM
445445
status: active
446446

447+
- name: 'Server Components'
448+
slug: 'server-components'
449+
domain: 'deployment-and-rendering'
450+
description: >-
451+
Implement and debug TanStack Start React Server Components with
452+
renderServerComponent, createCompositeComponent, low-level
453+
Flight streaming APIs, Router vs Query cache ownership, refresh
454+
paths, and selective SSR modes.
455+
type: sub-skill
456+
packages:
457+
- '@tanstack/react-start'
458+
- '@tanstack/react-start-rsc'
459+
covers:
460+
- renderServerComponent
461+
- createCompositeComponent
462+
- CompositeComponent
463+
- renderToReadableStream
464+
- createFromReadableStream
465+
- createFromFetch
466+
- Router-owned RSC caching
467+
- Query-owned RSC caching
468+
- Refresh ownership (router.invalidate, invalidateQueries, refetchQueries)
469+
- "Selective SSR modes (ssr: 'data-only', ssr: false)"
470+
- 'structuralSharing: false for Query-cached RSC values'
471+
tasks:
472+
- 'Implement route-owned React Server Components'
473+
- 'Choose between renderServerComponent and createCompositeComponent'
474+
- 'Debug stale RSC data and invalidation'
475+
- 'Migrate Next App Router RSC patterns to TanStack Start'
476+
failure_modes:
477+
- mistake: 'Using renderServerComponent when the UI needs slots'
478+
mechanism: >-
479+
renderServerComponent returns a renderable value and does
480+
not support client-provided children, render props, or
481+
component props. Use createCompositeComponent and render it
482+
with CompositeComponent when the server output must accept
483+
slots.
484+
source: 'docs/start/framework/react/guide/server-components.md'
485+
priority: HIGH
486+
status: active
487+
488+
- mistake: 'Omitting structuralSharing: false for Query-cached RSC values'
489+
mechanism: >-
490+
Query-cached RSC values must disable structural sharing.
491+
Otherwise the cache may try to merge Flight payloads across
492+
fetches, which can cause errors.
493+
source: 'docs/start/framework/react/guide/server-components.md'
494+
priority: HIGH
495+
status: active
496+
497+
- mistake: 'Copying stale renderRsc or .validator examples into current code'
498+
mechanism: >-
499+
Older snippets may use renderRsc or .validator(...).
500+
Normalize them to renderServerComponent and
501+
.inputValidator(...) before using them in current code.
502+
source: 'docs/start/framework/react/guide/server-functions.md'
503+
priority: MEDIUM
504+
status: active
505+
447506
tensions:
448507
- name: 'Isomorphic defaults vs server-only expectations'
449508
skills: ['execution-model', 'server-functions']

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

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
44

55
## Domains
66

7-
| Domain | Description | Skills |
8-
| ------------------------ | ------------------------------------------------------------- | ---------------- |
9-
| Project Setup | Scaffolding, Vite plugin, router factory, root route, entries | start-setup |
10-
| Server Functions | Type-safe RPCs with createServerFn, validation, streaming | server-functions |
11-
| Middleware and Context | Request/function middleware, context, global middleware | middleware |
12-
| Execution Model | Isomorphic defaults, environment boundaries, env vars | execution-model |
13-
| Server Routes | API endpoints, HTTP handlers, handler middleware | server-routes |
14-
| Deployment and Rendering | Hosting, selective SSR, prerendering, SEO | deployment |
7+
| Domain | Description | Skills |
8+
| ------------------------ | ------------------------------------------------------------- | ----------------------------- |
9+
| Project Setup | Scaffolding, Vite plugin, router factory, root route, entries | start-setup |
10+
| Server Functions | Type-safe RPCs with createServerFn, validation, streaming | server-functions |
11+
| Middleware and Context | Request/function middleware, context, global middleware | middleware |
12+
| Execution Model | Isomorphic defaults, environment boundaries, env vars | execution-model |
13+
| Server Routes | API endpoints, HTTP handlers, handler middleware | server-routes |
14+
| Deployment and Rendering | Hosting, selective SSR, prerendering, SEO | deployment, server-components |
1515

1616
## Skill Inventory
1717

@@ -23,6 +23,7 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
2323
| execution-model | core | execution-model | Isomorphic defaults, environment functions, env vars | 4 |
2424
| server-routes | core | server-routes | server property, HTTP handlers, createHandlers | 2 |
2525
| deployment | core | deployment-and-rendering | Hosting, SSR modes, prerendering, SEO | 3 |
26+
| server-components | sub-skill | deployment-and-rendering | React Server Components, cache ownership, selective SSR | 3 |
2627
| react-start | framework | project-setup | React bindings, useServerFn, full setup | 3 |
2728
| migrate-from-nextjs | lifecycle | project-setup | Next.js App Router migration checklist | 3 |
2829

@@ -77,6 +78,14 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
7778
| 2 | Bun deployment with React 18 | MEDIUM | docs/guide/hosting |
7879
| 3 | Child route loosening parent SSR config | MEDIUM | docs/guide/selective-ssr |
7980

81+
### server-components (3 failure modes)
82+
83+
| # | Mistake | Priority | Source |
84+
| --- | ------------------------------------------------------------- | -------- | ---------------------------- |
85+
| 1 | Using renderServerComponent when the UI needs slots | HIGH | docs/guide/server-components |
86+
| 2 | Omitting structuralSharing: false for Query-cached RSC values | HIGH | docs/guide/server-components |
87+
| 3 | Copying stale renderRsc or .validator examples | MEDIUM | docs/guide/server-functions |
88+
8089
## Tensions
8190

8291
| Tension | Skills | Agent implication |

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,25 @@ skills:
137137
- 'TanStack/router:packages/react-start/src'
138138
- 'TanStack/router:docs/start/framework/react/build-from-scratch.md'
139139

140+
- name: 'Server Components'
141+
slug: 'react-start/server-components'
142+
type: 'sub-skill'
143+
domain: 'deployment-and-rendering'
144+
path: 'skills/react-start/server-components/SKILL.md'
145+
package: 'packages/react-start'
146+
description: >-
147+
Implement, review, debug, and refactor TanStack Start React
148+
Server Components in React 19 apps.
149+
requires:
150+
- 'react-start'
151+
- 'start-core/server-functions'
152+
- 'start-core/execution-model'
153+
sources:
154+
- 'TanStack/router:docs/start/framework/react/guide/server-components.md'
155+
- 'TanStack/router:docs/start/framework/react/guide/server-functions.md'
156+
- 'TanStack/router:docs/start/framework/react/guide/execution-model.md'
157+
- 'TanStack/router:docs/router/guide/data-loading.md'
158+
140159
# ── Lifecycle Skills ────────────────────────────────────────────
141160
- name: 'Migrate from Next.js'
142161
slug: 'lifecycle/migrate-from-nextjs'

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ This skill builds on start-core. Read [start-core](../../../start-client-core/sk
2222

2323
This skill covers the React-specific bindings, setup, and patterns for TanStack Start.
2424

25+
For React Server Components patterns, see [react-start/server-components](./server-components/SKILL.md).
26+
2527
> **CRITICAL**: All code is ISOMORPHIC by default. Loaders run on BOTH server and client. Use `createServerFn` for server-only logic.
2628
2729
> **CRITICAL**: Do not confuse `@tanstack/react-start` with Next.js or Remix. They are completely different frameworks with different APIs.
Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
name: react-start/server-components
3+
description: >-
4+
Implement, review, debug, and refactor TanStack Start React Server
5+
Components in React 19 apps. Use when tasks mention
6+
@tanstack/react-start/rsc, renderServerComponent,
7+
createCompositeComponent, CompositeComponent,
8+
renderToReadableStream, createFromReadableStream, createFromFetch,
9+
Composite Components, React Flight streams, loader or query owned
10+
RSC caching, router.invalidate, structuralSharing: false,
11+
selective SSR, stale names like renderRsc or .validator, or
12+
migration from Next App Router RSC patterns. Do not use for
13+
generic SSR or non-TanStack RSC frameworks except brief
14+
comparison.
15+
type: sub-skill
16+
library: tanstack-start
17+
library_version: '1.166.2'
18+
requires:
19+
- react-start
20+
- start-core/server-functions
21+
- start-core/execution-model
22+
sources:
23+
- TanStack/router:docs/start/framework/react/guide/server-components.md
24+
- TanStack/router:docs/start/framework/react/guide/server-functions.md
25+
- TanStack/router:docs/start/framework/react/guide/execution-model.md
26+
- TanStack/router:docs/router/guide/data-loading.md
27+
---
28+
29+
# TanStack Start React Server Components
30+
31+
Treat TanStack Start RSCs as fetchable React Flight payloads, not as a framework-owned server tree. Start from data ownership and cache ownership, then choose the smallest RSC primitive that fits.
32+
33+
## When this skill is active
34+
35+
1. Inspect `vite.config.*` for `tanstackStart({ rsc: { enabled: true } })`, `rsc()`, and `viteReact()`.
36+
2. Inspect route files for `loader`, `loaderDeps`, `staleTime`, `ssr`, and `errorComponent`.
37+
3. Inspect server boundaries: `createServerFn`, `createServerOnlyFn`, `.server.*`, and imports from `@tanstack/react-start/server`.
38+
4. Identify the cache owner: Router loader cache, TanStack Query, or HTTP/server cache.
39+
5. Identify the refresh path: `router.invalidate()`, `invalidateQueries`, `refetchQueries`, or GET cache headers.
40+
41+
## Hard invariants
42+
43+
- Route loaders are isomorphic. Do not put DB access, secrets, or Node-only APIs directly in a loader. If the loader itself must use browser APIs, make that route `ssr: false`.
44+
- `renderServerComponent(...)` returns a renderable fragment. It does not support slots.
45+
- `createCompositeComponent(...)` is for server-rendered UI that must accept client-provided `children`, render props, or component props.
46+
- Query-cached RSC values require `structuralSharing: false`.
47+
- Slot payloads are opaque on the server. Do not inspect, map, or clone `props.children`.
48+
- Render-prop and component-slot arguments must stay Flight-serializable.
49+
- Current server function validation API is `.inputValidator(...)`. Older snippets may still show `.validator(...)`; normalize them.
50+
- TanStack custom serialization does not apply inside RSCs yet. Stay inside native Flight-supported values.
51+
52+
## Decide three things immediately
53+
54+
### 1) Transport / composition primitive
55+
56+
- No client slots needed -> `renderServerComponent`
57+
- Client interactivity must be inserted inside server-rendered markup -> `createCompositeComponent` + `<CompositeComponent src={...} />`
58+
- Need custom Flight streaming, API routes, or non-standard transport -> `renderToReadableStream`, `createFromReadableStream`, `createFromFetch`
59+
60+
### 2) Cache owner
61+
62+
- Route-shaped data keyed by pathname, params, or search -> Router cache
63+
- Independent key space, background refetch, or non-route ownership -> TanStack Query
64+
- Cross-request reuse on server or CDN -> GET `createServerFn` + response cache headers and/or external server cache
65+
66+
### 3) Refresh owner
67+
68+
- Router-owned RSC -> `router.invalidate()`
69+
- Query-owned RSC -> `queryClient.invalidateQueries(...)` or `refetchQueries(...)`
70+
- Mixed Router + Query -> invalidate both deliberately; do not assume one refreshes the other
71+
72+
## Pattern chooser
73+
74+
- Simple server fragment in a route loader -> `renderServerComponent`
75+
- Interactive slot inside server markup -> `createCompositeComponent`
76+
- Route component needs browser APIs but loader can still prefetch on the server -> `ssr: 'data-only'`
77+
- Loader itself needs browser APIs -> `ssr: false`
78+
- Route cache key must include search params -> `loaderDeps`
79+
- Query-managed RSC -> `useSuspenseQuery` + SSR `ensureQueryData`
80+
- Multiple independent RSCs -> separate server functions + `Promise.all`
81+
- Multiple RSCs sharing data or invalidating together -> one server function returning many renderables or sources
82+
- Need isolated widget failures or staggered reveal -> return promises from the loader and resolve with `use()` inside Suspense
83+
84+
## Slot choice
85+
86+
- `children`: free-form composition, no server-to-client data flow
87+
- render props: the server must pass serializable data into client-rendered UI
88+
- component props: reusable client slot with a stable typed prop surface
89+
- If you are about to use `Children.map`, `cloneElement`, or inspect `children` on the server, stop and convert it to a render prop
90+
91+
## Review / refactor checklist
92+
93+
- Is the chosen primitive the smallest one that fits?
94+
- Does the loader own the RSC, or should Query own it?
95+
- Are route cache keys complete (`params` + minimal `loaderDeps`)?
96+
- Is invalidation hitting the real cache owner?
97+
- Are query options using `structuralSharing: false` for any RSC value?
98+
- Are mutations explicit `createServerFn({ method: 'POST' })` calls instead of hidden server actions?
99+
- Are server-only imports kept inside server functions or server-only boundaries?
100+
- Are examples using current names (`renderServerComponent`, `.inputValidator`) instead of stale ones?
101+
102+
## Debug fast
103+
104+
- Setup, exports, or stale docs mismatch -> `docs/current-api-notes.md`
105+
- Composite Component design or slot bug -> `docs/composite-components.md`
106+
- Stale data, refetching, loader keys, Query vs Router ownership, or SSR mode -> `docs/caching-refresh-ssr.md`
107+
- Review, refactor, import leaks, error boundaries, or serialization bugs -> `docs/debugging-review.md`
108+
- Architecture and Next/App Router translation -> `docs/architecture.md`
109+
110+
## Copy-paste patterns
111+
112+
- `examples/01-renderable-route-loader.tsx`
113+
- `examples/02-composite-slots.tsx`
114+
- `examples/03-query-owned-rsc.tsx`
115+
- `examples/04-selective-ssr-data-only.tsx`
116+
- `examples/05-ssr-false-browser-loader.tsx`
117+
- `examples/06-low-level-flight-api-route.tsx`
118+
119+
## Default implementation sequence
120+
121+
1. Keep server-only work inside `createServerFn` or `createServerOnlyFn`
122+
2. Return an RSC from the server function
123+
3. Consume it through the route loader unless Query has a clear ownership advantage
124+
4. Add the smallest cache policy that satisfies freshness requirements
125+
5. Wire invalidation exactly once at the real cache owner
126+
6. Escalate to Composite Components only when the client must fill slots
127+
7. Escalate to low-level Flight APIs only when high-level helpers cannot express the transport
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Architecture and mental model
2+
3+
## Core model
4+
5+
TanStack Start treats React Server Components as plain React Flight data:
6+
7+
- create them on the server
8+
- return them from a server function or API route
9+
- decode and render them during SSR or on the client
10+
- cache them with whatever already owns the data flow
11+
12+
That matters because the framework is not asking you to move the whole UI tree to the server. RSCs are opt-in fragments that fit into existing Router and Query workflows.
13+
14+
## Boundary model
15+
16+
The fastest way to get TanStack Start RSC wrong is to think “loader = server”.
17+
18+
Use these boundaries instead:
19+
20+
- `createServerFn`: explicit RPC boundary; safe to call from client code because the client gets an RPC stub
21+
- `createServerOnlyFn`: utility that must never run on the client
22+
- route `loader`: orchestration layer that runs on the server for the initial SSR request and in the browser on client navigation unless the route is `ssr: false`
23+
24+
Practical rule: loaders decide _when_ to fetch. Server functions decide _what_ must stay on the server.
25+
26+
## What still works inside RSCs
27+
28+
Do not over-correct and assume RSCs are a stripped-down universe.
29+
30+
- TanStack Router `Link` works inside server components
31+
- CSS Modules and global CSS imports work inside server components
32+
- `React.cache` works for request-scoped memoization inside server components
33+
34+
Use those directly when they simplify the tree.
35+
36+
## When RSCs actually pay off
37+
38+
Use TanStack Start RSCs when one or more of these are true:
39+
40+
- a region is heavy to render but mostly static once delivered
41+
- a server-only dependency should never enter the client bundle
42+
- data fetching and render logic want to live together
43+
- you want progressively streamed HTML for part of the route
44+
- the result can be cached better as a fragment than as an entire page
45+
46+
Do not force RSCs into highly interactive, state-dense client surfaces unless they materially reduce bundle size or remove awkward client/server sync.
47+
48+
## Choosing tree ownership
49+
50+
Think in terms of ownership:
51+
52+
- client-owned UI: plain client components, Query, SPA patterns
53+
- route-owned RSC: route loader fetches a fragment and Router cache owns freshness
54+
- query-owned RSC: Query owns the fragment because its lifecycle is not route-shaped
55+
- mixed ownership: the route owns coarse navigation state, Query owns sub-fragments
56+
57+
The wrong smell is accidental double ownership: one RSC is fetched in a loader, then also separately cached in Query, then only one side is invalidated.
58+
59+
## Composite Components in one sentence
60+
61+
A Composite Component is a server-rendered fragment with placeholders the client fills later.
62+
63+
That makes it the replacement for “I need server-rendered markup here, but I still need client interactivity in the middle of it.”
64+
65+
The client can wrap, nest, reorder, and interleave those fragments instead of accepting a single framework-owned server tree.
66+
67+
## Next App Router translation
68+
69+
Use this mapping when someone is thinking in Next terms:
70+
71+
- Next “server-first tree” -> Start “isomorphic-first app with opt-in RSC fragments”
72+
- Next `'use client'` boundary -> Start Composite Component slot boundary
73+
- Next server actions -> Start explicit `createServerFn({ method: 'POST' })`
74+
- Next framework cache semantics -> Start Router cache, Query cache, and HTTP cache you control directly
75+
76+
The useful mental shift is this: in TanStack Start, RSC is a transport and composition primitive, not the center of gravity for the whole app.
77+
78+
## High-value heuristics
79+
80+
- If the fragment never accepts client content, demote it to `renderServerComponent`.
81+
- If a route-scoped RSC never needs independent refetching, keep it in the loader cache.
82+
- If a fragment is reused across routes or refreshed independently, consider Query ownership.
83+
- If several fragments always share data and invalidate together, bundle them in one server function.
84+
- If one slow fragment blocks everything, stop awaiting it in the loader and defer it.

0 commit comments

Comments
 (0)