server-components

1---2name: server-components3description: >-4  Implement, review, debug, and refactor TanStack Start React Server5  Components in React 19 apps. Use when tasks mention6  @tanstack/react-start/rsc, renderServerComponent,7  createCompositeComponent, CompositeComponent,8  renderToReadableStream, createFromReadableStream, createFromFetch,9  Composite Components, React Flight streams, loader or query owned10  RSC caching, router.invalidate, structuralSharing: false,11  selective SSR, stale names like renderRsc or .validator, or12  migration from Next App Router RSC patterns. Do not use for13  generic SSR or non-TanStack RSC frameworks except brief14  comparison.15metadata:16  type: sub-skill17  library: tanstack-start18  library_version: '1.168.32'19requires:20  - react-start21  - start-core/server-functions22  - start-core/execution-model23sources:24  - TanStack/router:docs/start/framework/react/guide/server-components.md25  - TanStack/router:docs/start/framework/react/guide/server-functions.md26  - TanStack/router:docs/start/framework/react/guide/execution-model.md27  - TanStack/router:docs/router/guide/data-loading.md28---29 30# TanStack Start React Server Components31 32Treat 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.33 34## When this skill is active35 361. Inspect `vite.config.*` for `tanstackStart({ rsc: { enabled: true } })`, `rsc()`, and `viteReact()`.372. Inspect route files for `loader`, `loaderDeps`, `staleTime`, `ssr`, and `errorComponent`.383. Inspect server boundaries: `createServerFn`, `createServerOnlyFn`, `.server.*`, and imports from `@tanstack/react-start/server`.394. Identify the cache owner: Router loader cache, TanStack Query, or HTTP/server cache.405. Identify the refresh path: `router.invalidate()`, `invalidateQueries`, `refetchQueries`, or GET cache headers.41 42## Hard invariants43 44- 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`.45- `renderServerComponent(...)` returns a renderable fragment. It does not support slots.46- `createCompositeComponent(...)` is for server-rendered UI that must accept client-provided `children`, render props, or component props.47- Query-cached RSC values require `structuralSharing: false`.48- Slot payloads are opaque on the server. Do not inspect, map, or clone `props.children`.49- Render-prop and component-slot arguments must stay Flight-serializable.50- Current server function validation API is `.validator(...)`. Older snippets may still show `.validator(...)`; normalize them.51- TanStack custom serialization does not apply inside RSCs yet. Stay inside native Flight-supported values.52 53## Decide three things immediately54 55### 1) Transport / composition primitive56 57- No client slots needed -> `renderServerComponent`58- Client interactivity must be inserted inside server-rendered markup -> `createCompositeComponent` + `<CompositeComponent src={...} />`59- Need custom Flight streaming, API routes, or non-standard transport -> `renderToReadableStream`, `createFromReadableStream`, `createFromFetch`60 61### 2) Cache owner62 63- Route-shaped data keyed by pathname, params, or search -> Router cache64- Independent key space, background refetch, or non-route ownership -> TanStack Query65- Cross-request reuse on server or CDN -> GET `createServerFn` + response cache headers and/or external server cache66 67### 3) Refresh owner68 69- Router-owned RSC -> `router.invalidate()`70- Query-owned RSC -> `queryClient.invalidateQueries(...)` or `refetchQueries(...)`71- Mixed Router + Query -> invalidate both deliberately; do not assume one refreshes the other72 73## Pattern chooser74 75- Simple server fragment in a route loader -> `renderServerComponent`76- Interactive slot inside server markup -> `createCompositeComponent`77- Route component needs browser APIs but loader can still prefetch on the server -> `ssr: 'data-only'`78- Loader itself needs browser APIs -> `ssr: false`79- Route cache key must include search params -> `loaderDeps`80- Query-managed RSC -> `useSuspenseQuery` + SSR `ensureQueryData`81- Multiple independent RSCs -> separate server functions + `Promise.all`82- Multiple RSCs sharing data or invalidating together -> one server function returning many renderables or sources83- Need isolated widget failures or staggered reveal -> return promises from the loader and resolve with `use()` inside Suspense84 85## Slot choice86 87- `children`: free-form composition, no server-to-client data flow88- render props: the server must pass serializable data into client-rendered UI89- component props: reusable client slot with a stable typed prop surface90- If you are about to use `Children.map`, `cloneElement`, or inspect `children` on the server, stop and convert it to a render prop91 92## Review / refactor checklist93 94- Is the chosen primitive the smallest one that fits?95- Does the loader own the RSC, or should Query own it?96- Are route cache keys complete (`params` + minimal `loaderDeps`)?97- Is invalidation hitting the real cache owner?98- Are query options using `structuralSharing: false` for any RSC value?99- Are mutations explicit `createServerFn({ method: 'POST' })` calls instead of hidden server actions?100- Are server-only imports kept inside server functions or server-only boundaries?101- Are examples using current names (`renderServerComponent`, `.validator`) instead of stale ones?102 103## Debug fast104 105- Setup, exports, or stale docs mismatch -> `docs/current-api-notes.md`106- Composite Component design or slot bug -> `docs/composite-components.md`107- Stale data, refetching, loader keys, Query vs Router ownership, or SSR mode -> `docs/caching-refresh-ssr.md`108- Review, refactor, import leaks, error boundaries, or serialization bugs -> `docs/debugging-review.md`109- Architecture and Next/App Router translation -> `docs/architecture.md`110 111## Copy-paste patterns112 113- `examples/01-renderable-route-loader.tsx`114- `examples/02-composite-slots.tsx`115- `examples/03-query-owned-rsc.tsx`116- `examples/04-selective-ssr-data-only.tsx`117- `examples/05-ssr-false-browser-loader.tsx`118- `examples/06-low-level-flight-api-route.tsx`119 120## Default implementation sequence121 1221. Keep server-only work inside `createServerFn` or `createServerOnlyFn`1232. Return an RSC from the server function1243. Consume it through the route loader unless Query has a clear ownership advantage1254. Add the smallest cache policy that satisfies freshness requirements1265. Wire invalidation exactly once at the real cache owner1276. Escalate to Composite Components only when the client must fill slots1287. Escalate to low-level Flight APIs only when high-level helpers cannot express the transport129