@tanstack/react-start 1.167.39 → 1.167.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-start",
-  "version": "1.167.39",
+  "version": "1.167.41",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -131,12 +131,12 @@
   },
   "dependencies": {
     "pathe": "^2.0.3",
-    "@tanstack/react-start-client": "1.166.38",
-    "@tanstack/react-start-rsc": "0.0.18",
-    "@tanstack/react-start-server": "1.166.39",
+    "@tanstack/react-start-client": "1.166.39",
+    "@tanstack/react-start-rsc": "0.0.20",
+    "@tanstack/react-start-server": "1.166.40",
     "@tanstack/router-utils": "^1.161.6",
-    "@tanstack/start-plugin-core": "1.167.34",
-    "@tanstack/react-router": "1.168.21",
+    "@tanstack/start-plugin-core": "1.167.35",
+    "@tanstack/react-router": "1.168.22",
     "@tanstack/start-client-core": "1.167.17",
     "@tanstack/start-server-core": "1.167.19"
   },

package/skills/react-start/SKILL.md

@@ -22,6 +22,8 @@ This skill builds on start-core. Read [start-core](../../../start-client-core/sk
 
 This skill covers the React-specific bindings, setup, and patterns for TanStack Start.
 
+For React Server Components patterns, see [react-start/server-components](./server-components/SKILL.md).
+
 > **CRITICAL**: All code is ISOMORPHIC by default. Loaders run on BOTH server and client. Use `createServerFn` for server-only logic.
 
 > **CRITICAL**: Do not confuse `@tanstack/react-start` with Next.js or Remix. They are completely different frameworks with different APIs.

package/skills/react-start/server-components/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: react-start/server-components
+description: >-
+  Implement, review, debug, and refactor TanStack Start React Server
+  Components in React 19 apps. Use when tasks mention
+  @tanstack/react-start/rsc, renderServerComponent,
+  createCompositeComponent, CompositeComponent,
+  renderToReadableStream, createFromReadableStream, createFromFetch,
+  Composite Components, React Flight streams, loader or query owned
+  RSC caching, router.invalidate, structuralSharing: false,
+  selective SSR, stale names like renderRsc or .validator, or
+  migration from Next App Router RSC patterns. Do not use for
+  generic SSR or non-TanStack RSC frameworks except brief
+  comparison.
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - react-start
+  - start-core/server-functions
+  - start-core/execution-model
+sources:
+  - TanStack/router:docs/start/framework/react/guide/server-components.md
+  - TanStack/router:docs/start/framework/react/guide/server-functions.md
+  - TanStack/router:docs/start/framework/react/guide/execution-model.md
+  - TanStack/router:docs/router/guide/data-loading.md
+---
+
+# TanStack Start React Server Components
+
+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.
+
+## When this skill is active
+
+1. Inspect `vite.config.*` for `tanstackStart({ rsc: { enabled: true } })`, `rsc()`, and `viteReact()`.
+2. Inspect route files for `loader`, `loaderDeps`, `staleTime`, `ssr`, and `errorComponent`.
+3. Inspect server boundaries: `createServerFn`, `createServerOnlyFn`, `.server.*`, and imports from `@tanstack/react-start/server`.
+4. Identify the cache owner: Router loader cache, TanStack Query, or HTTP/server cache.
+5. Identify the refresh path: `router.invalidate()`, `invalidateQueries`, `refetchQueries`, or GET cache headers.
+
+## Hard invariants
+
+- 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`.
+- `renderServerComponent(...)` returns a renderable fragment. It does not support slots.
+- `createCompositeComponent(...)` is for server-rendered UI that must accept client-provided `children`, render props, or component props.
+- Query-cached RSC values require `structuralSharing: false`.
+- Slot payloads are opaque on the server. Do not inspect, map, or clone `props.children`.
+- Render-prop and component-slot arguments must stay Flight-serializable.
+- Current server function validation API is `.inputValidator(...)`. Older snippets may still show `.validator(...)`; normalize them.
+- TanStack custom serialization does not apply inside RSCs yet. Stay inside native Flight-supported values.
+
+## Decide three things immediately
+
+### 1) Transport / composition primitive
+
+- No client slots needed -> `renderServerComponent`
+- Client interactivity must be inserted inside server-rendered markup -> `createCompositeComponent` + `<CompositeComponent src={...} />`
+- Need custom Flight streaming, API routes, or non-standard transport -> `renderToReadableStream`, `createFromReadableStream`, `createFromFetch`
+
+### 2) Cache owner
+
+- Route-shaped data keyed by pathname, params, or search -> Router cache
+- Independent key space, background refetch, or non-route ownership -> TanStack Query
+- Cross-request reuse on server or CDN -> GET `createServerFn` + response cache headers and/or external server cache
+
+### 3) Refresh owner
+
+- Router-owned RSC -> `router.invalidate()`
+- Query-owned RSC -> `queryClient.invalidateQueries(...)` or `refetchQueries(...)`
+- Mixed Router + Query -> invalidate both deliberately; do not assume one refreshes the other
+
+## Pattern chooser
+
+- Simple server fragment in a route loader -> `renderServerComponent`
+- Interactive slot inside server markup -> `createCompositeComponent`
+- Route component needs browser APIs but loader can still prefetch on the server -> `ssr: 'data-only'`
+- Loader itself needs browser APIs -> `ssr: false`
+- Route cache key must include search params -> `loaderDeps`
+- Query-managed RSC -> `useSuspenseQuery` + SSR `ensureQueryData`
+- Multiple independent RSCs -> separate server functions + `Promise.all`
+- Multiple RSCs sharing data or invalidating together -> one server function returning many renderables or sources
+- Need isolated widget failures or staggered reveal -> return promises from the loader and resolve with `use()` inside Suspense
+
+## Slot choice
+
+- `children`: free-form composition, no server-to-client data flow
+- render props: the server must pass serializable data into client-rendered UI
+- component props: reusable client slot with a stable typed prop surface
+- If you are about to use `Children.map`, `cloneElement`, or inspect `children` on the server, stop and convert it to a render prop
+
+## Review / refactor checklist
+
+- Is the chosen primitive the smallest one that fits?
+- Does the loader own the RSC, or should Query own it?
+- Are route cache keys complete (`params` + minimal `loaderDeps`)?
+- Is invalidation hitting the real cache owner?
+- Are query options using `structuralSharing: false` for any RSC value?
+- Are mutations explicit `createServerFn({ method: 'POST' })` calls instead of hidden server actions?
+- Are server-only imports kept inside server functions or server-only boundaries?
+- Are examples using current names (`renderServerComponent`, `.inputValidator`) instead of stale ones?
+
+## Debug fast
+
+- Setup, exports, or stale docs mismatch -> `docs/current-api-notes.md`
+- Composite Component design or slot bug -> `docs/composite-components.md`
+- Stale data, refetching, loader keys, Query vs Router ownership, or SSR mode -> `docs/caching-refresh-ssr.md`
+- Review, refactor, import leaks, error boundaries, or serialization bugs -> `docs/debugging-review.md`
+- Architecture and Next/App Router translation -> `docs/architecture.md`
+
+## Copy-paste patterns
+
+- `examples/01-renderable-route-loader.tsx`
+- `examples/02-composite-slots.tsx`
+- `examples/03-query-owned-rsc.tsx`
+- `examples/04-selective-ssr-data-only.tsx`
+- `examples/05-ssr-false-browser-loader.tsx`
+- `examples/06-low-level-flight-api-route.tsx`
+
+## Default implementation sequence
+
+1. Keep server-only work inside `createServerFn` or `createServerOnlyFn`
+2. Return an RSC from the server function
+3. Consume it through the route loader unless Query has a clear ownership advantage
+4. Add the smallest cache policy that satisfies freshness requirements
+5. Wire invalidation exactly once at the real cache owner
+6. Escalate to Composite Components only when the client must fill slots
+7. Escalate to low-level Flight APIs only when high-level helpers cannot express the transport

package/skills/react-start/server-components/docs/architecture.md

@@ -0,0 +1,84 @@
+# Architecture and mental model
+
+## Core model
+
+TanStack Start treats React Server Components as plain React Flight data:
+
+- create them on the server
+- return them from a server function or API route
+- decode and render them during SSR or on the client
+- cache them with whatever already owns the data flow
+
+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.
+
+## Boundary model
+
+The fastest way to get TanStack Start RSC wrong is to think “loader = server”.
+
+Use these boundaries instead:
+
+- `createServerFn`: explicit RPC boundary; safe to call from client code because the client gets an RPC stub
+- `createServerOnlyFn`: utility that must never run on the client
+- 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`
+
+Practical rule: loaders decide _when_ to fetch. Server functions decide _what_ must stay on the server.
+
+## What still works inside RSCs
+
+Do not over-correct and assume RSCs are a stripped-down universe.
+
+- TanStack Router `Link` works inside server components
+- CSS Modules and global CSS imports work inside server components
+- `React.cache` works for request-scoped memoization inside server components
+
+Use those directly when they simplify the tree.
+
+## When RSCs actually pay off
+
+Use TanStack Start RSCs when one or more of these are true:
+
+- a region is heavy to render but mostly static once delivered
+- a server-only dependency should never enter the client bundle
+- data fetching and render logic want to live together
+- you want progressively streamed HTML for part of the route
+- the result can be cached better as a fragment than as an entire page
+
+Do not force RSCs into highly interactive, state-dense client surfaces unless they materially reduce bundle size or remove awkward client/server sync.
+
+## Choosing tree ownership
+
+Think in terms of ownership:
+
+- client-owned UI: plain client components, Query, SPA patterns
+- route-owned RSC: route loader fetches a fragment and Router cache owns freshness
+- query-owned RSC: Query owns the fragment because its lifecycle is not route-shaped
+- mixed ownership: the route owns coarse navigation state, Query owns sub-fragments
+
+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.
+
+## Composite Components in one sentence
+
+A Composite Component is a server-rendered fragment with placeholders the client fills later.
+
+That makes it the replacement for “I need server-rendered markup here, but I still need client interactivity in the middle of it.”
+
+The client can wrap, nest, reorder, and interleave those fragments instead of accepting a single framework-owned server tree.
+
+## Next App Router translation
+
+Use this mapping when someone is thinking in Next terms:
+
+- Next “server-first tree” -> Start “isomorphic-first app with opt-in RSC fragments”
+- Next `'use client'` boundary -> Start Composite Component slot boundary
+- Next server actions -> Start explicit `createServerFn({ method: 'POST' })`
+- Next framework cache semantics -> Start Router cache, Query cache, and HTTP cache you control directly
+
+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.
+
+## High-value heuristics
+
+- If the fragment never accepts client content, demote it to `renderServerComponent`.
+- If a route-scoped RSC never needs independent refetching, keep it in the loader cache.
+- If a fragment is reused across routes or refreshed independently, consider Query ownership.
+- If several fragments always share data and invalidate together, bundle them in one server function.
+- If one slow fragment blocks everything, stop awaiting it in the loader and defer it.

package/skills/react-start/server-components/docs/caching-refresh-ssr.md

@@ -0,0 +1,137 @@
+# Caching, refresh, SSR modes, and loading patterns
+
+## Pick one cache owner first
+
+### Router cache
+
+Use Router when the RSC is route-shaped and keyed by URL state.
+
+Relevant facts:
+
+- Router loader cache keys are based on pathname and params, plus anything you add through `loaderDeps`
+- default navigation `staleTime` is `0`
+- default preload freshness is `30s`
+- default stale reload mode is background stale-while-revalidate
+- `router.invalidate()` reloads active loaders immediately and marks cached routes stale
+
+Use Router ownership when the fragment naturally belongs to the route and should track navigation.
+
+### TanStack Query
+
+Use Query when the fragment has its own lifecycle.
+
+Typical reasons:
+
+- reuse across routes
+- background refetching independent of navigation
+- manual query invalidation
+- non-route ownership
+
+Hard rule:
+
+```tsx
+structuralSharing: false
+```
+
+Without that, Query may try to merge RSC values across fetches.
+
+### HTTP / server cache
+
+Use GET server functions and response headers when you want cross-request reuse:
+
+- CDN caching
+- edge caching
+- reverse proxies
+- shared server caches
+
+Set headers in a GET `createServerFn` via `setResponseHeaders(...)`.
+
+## Router-owned RSC pattern
+
+Use a server function to return the RSC, then fetch it in the route loader.
+
+Tune Router with:
+
+- `staleTime` when revisits should stay fresh for a window
+- `loaderDeps` when search params affect the fragment
+- `staleReloadMode: 'blocking'` when showing stale data during reload is unacceptable
+
+`loaderDeps` rule: include only values the loader actually uses. Returning the whole search object causes noisy invalidation.
+
+## Query-owned RSC pattern
+
+Use Query when you want explicit cache keys and background fetch behavior.
+
+Recommended shape:
+
+```tsx
+const postQueryOptions = (postId: string) => ({
+  queryKey: ['post-rsc', postId],
+  structuralSharing: false,
+  queryFn: () => getPostRsc({ data: { postId } }),
+  staleTime: 5 * 60 * 1000,
+})
+```
+
+For SSR reuse, prefetch in the route loader:
+
+```tsx
+await context.queryClient.ensureQueryData(postQueryOptions(params.postId))
+```
+
+Then read it with `useSuspenseQuery` in the component.
+
+## Refresh rules
+
+- loader-owned fragment changed -> `router.invalidate()`
+- query-owned fragment changed -> `queryClient.invalidateQueries(...)`
+- shared route and query state -> refresh both if both are authoritative
+- CDN or response-header cache involved -> make sure the mutation path also busts or bypasses server-side cache
+
+Do not “spray” invalidation everywhere. Decide who owns freshness, then target that owner.
+
+## Selective SSR modes
+
+### `ssr: 'data-only'`
+
+Use when:
+
+- the route component needs browser APIs
+- the loader can still fetch the RSC on the server for first paint
+- you want server-fetched fragment data ready before the client component mounts
+
+This is often the right shape for responsive charts, viewport-dependent layout wrappers, or widgets that need `window` but still benefit from server-rendered content.
+
+### `ssr: false`
+
+Use when the loader itself depends on browser APIs such as:
+
+- `localStorage`
+- `window`
+- browser-only client state
+
+In this mode, both the loader and component run in the browser. The loader can still call a server function that returns an RSC.
+
+## Loading patterns
+
+### Independent fragments -> parallel
+
+If the fragments do not share data, fetch them with separate server functions and `Promise.all`.
+
+### Shared data or shared invalidation -> bundle
+
+If several fragments always share a fetch or invalidate together, return them from one server function. This reduces round trips and keeps ownership aligned.
+
+### One slow fragment should not block everything -> defer
+
+Return promises from the loader instead of awaiting them. Resolve them with `use()` inside Suspense. This also lets you isolate failures with a local ErrorBoundary instead of the route error boundary.
+
+### Large or unbounded lists -> async generators
+
+Use async generators when items should arrive incrementally and total size or per-item latency is unpredictable.
+
+## Request-scoped memoization
+
+`React.cache` works inside server components. Use it when several async server components in one request need the same expensive fetch or computation.
+
+That is request-scoped deduplication, not a cross-request cache.

package/skills/react-start/server-components/docs/composite-components.md

@@ -0,0 +1,115 @@
+# Composite Components and slot composition
+
+## The real mechanism
+
+Inside `createCompositeComponent`, slot props are placeholders, not real client elements.
+
+Server-side behavior:
+
+- reading `props.children` records “there will be children here”
+- calling `props.renderSomething(args)` records “call this slot with these args later”
+- reading a component prop like `props.AddToCart` records “render this client component here with these props later”
+
+Client-side behavior:
+
+- `<CompositeComponent src={...} ... />` replaces those placeholders with the real props you passed at render time
+
+This is why slots are powerful and why some React habits stop working.
+
+## Choose the slot type by data flow
+
+### `children`
+
+Use when:
+
+- the server only needs a hole for client content
+- no server data needs to flow into the slotted content
+- free-form composition matters more than a rigid interface
+
+Do not use when the server must inject IDs, permissions, pricing, or derived data into the child content.
+
+### render props
+
+Use when:
+
+- the server must pass data into the client-rendered content
+- the data is serializable
+- you want the call site to stay flexible
+
+This is usually the best default when the server owns the data and the client owns the interactive control.
+
+### component props
+
+Use when:
+
+- you have a reusable client component
+- the prop contract is stable
+- you want the server to decide where it renders and which typed props it receives
+
+This is a good fit for buttons, menus, controls, widgets, and repeated productized patterns.
+
+## Rules that matter
+
+- `renderServerComponent` does not support slots
+- do not use `React.Children.map`, `cloneElement`, or child inspection on the server
+- render-prop arguments and component-slot props must be Flight-serializable
+- keep slot contracts narrow; pass IDs and plain data, not giant objects by default
+
+## The most common anti-pattern
+
+Bad instinct:
+
+```tsx
+createCompositeComponent((props: { children?: React.ReactNode }) => (
+  <div>
+    {React.Children.map(props.children, (child) =>
+      React.cloneElement(child, { extra: 'prop' }),
+    )}
+  </div>
+))
+```
+
+Correct rewrite:
+
+```tsx
+createCompositeComponent<{
+  renderItem?: (data: { extra: string }) => React.ReactNode
+}>((props) => <div>{props.renderItem?.({ extra: 'prop' })}</div>)
+```
+
+Server-side slot content is opaque. If the server needs to add data, make the data explicit.
+
+## Good slot contracts
+
+Prefer contracts like:
+
+- `renderActions?: ({ postId, authorId }) => ReactNode`
+- `AddToCart?: ComponentType<{ productId: string; price: number }>`
+- `children?: ReactNode`
+
+Avoid contracts like:
+
+- `renderAnything?: (data: EntirePostRecordFromDB) => ReactNode`
+- `children` plus child inspection and mutation
+- opaque callbacks that expect non-serializable classes or functions from the server
+
+## Composition patterns that age well
+
+### Shell + actions
+
+The server renders an article, card, or panel and exposes one `renderActions` slot for buttons, menus, or controls.
+
+### Shell + body children
+
+The server renders stable framing UI and accepts `children` for optional interactive regions like comments, drawers, or editors.
+
+### Stable control slot
+
+The server accepts a component prop such as `AddToCart`, `UserMenu`, or `RowActions` and supplies clean typed props to it.
+
+## Refactor heuristics
+
+- No slot use anywhere -> replace the Composite Component with `renderServerComponent`
+- Slot exists only to pass data -> prefer a render prop over `children`
+- Repeated render-prop call sites with the same component -> promote to a component prop
+- Giant slot arg object -> shrink it to the smallest serializable payload that the client really needs

package/skills/react-start/server-components/docs/current-api-notes.md

@@ -0,0 +1,74 @@
+# Current API notes and stale example corrections
+
+Validated against official TanStack Start, TanStack Router, TanStack blog, and Vite docs on 2026-04-13.
+
+## Current setup shape
+
+Use the current RSC setup:
+
+- React 19+
+- Vite 7+
+- `@vitejs/plugin-rsc`
+- `tanstackStart({ rsc: { enabled: true } })`
+- `rsc()`
+- `viteReact()`
+
+## Current high-level APIs
+
+Prefer:
+
+- `renderServerComponent`
+- `createCompositeComponent`
+- `CompositeComponent`
+
+Use low-level APIs only for custom transport:
+
+- `renderToReadableStream`
+- `createFromReadableStream`
+- `createFromFetch`
+
+## Current validation API
+
+Use `.inputValidator(...)` on `createServerFn`.
+
+Important because some current RSC docs snippets still show the older `.validator(...)` spelling. Normalize those examples before copying them into real code.
+
+## Current constraints
+
+- RSC support is still experimental
+- TanStack custom serialization is not available inside RSCs yet
+- slot args must stay Flight-serializable
+- `structuralSharing: false` is mandatory for Query-cached RSC values
+
+## Stale example traps to avoid
+
+### Old `renderRsc` examples
+
+You may still find older official repo examples using `renderRsc` and older config shapes. Do not cargo-cult them into new code. Normalize to the current docs and current `@tanstack/react-start/rsc` APIs.
+
+### Old validation snippets
+
+If you see `.validator(z.object(...))` in an RSC example, rewrite it to `.inputValidator(z.object(...))` to match the current server function API.
+
+### Old Vite config shapes
+
+If an example enables Start but does not also install and register `@vitejs/plugin-rsc`, treat it as stale for current TanStack Start RSC setup.
+
+## Maintenance rule
+
+When docs, examples, and repo snippets disagree:
+
+1. prefer the current TanStack Start docs
+2. prefer the current TanStack blog announcement over older repo samples
+3. cross-check with current Server Functions and Execution Model docs
+4. then normalize all local examples to one coherent modern API surface
+
+## Official source list
+
+- TanStack Start Server Components docs
+- TanStack Start Server Functions docs
+- TanStack Start Execution Model docs
+- TanStack Start Import Protection docs
+- TanStack Router Data Loading docs
+- TanStack blog: React Server Components Your Way
+- Vite docs for `@vitejs/plugin-rsc`

package/skills/react-start/server-components/docs/debugging-review.md

@@ -0,0 +1,141 @@
+# Debugging and review guide
+
+## Triage by failure stage
+
+### 1. Setup / build failure
+
+Likely causes:
+
+- `@vitejs/plugin-rsc` missing
+- RSC not enabled in `tanstackStart({ rsc: { enabled: true } })`
+- stale example using old exports
+- wrong React or Vite baseline
+
+Checks:
+
+- inspect `vite.config.*`
+- inspect imports from `@tanstack/react-start/rsc`
+- normalize to `renderServerComponent`, `createCompositeComponent`, `CompositeComponent`, `.inputValidator(...)`
+
+### 2. Wrong environment failure
+
+Symptoms:
+
+- DB or secret access explodes on client navigation
+- `window` or `localStorage` explodes during SSR
+- import protection complaints about server-only code
+
+Likely causes:
+
+- server-only logic placed directly in an isomorphic loader
+- browser-only logic used in SSR route/component
+- helper referencing `.server` imports outside a recognized server boundary
+
+Fixes:
+
+- move server-only work into `createServerFn` or `createServerOnlyFn`
+- use `ssr: 'data-only'` when only the component needs browser APIs
+- use `ssr: false` when the loader itself needs browser APIs
+- keep server-only imports inside server-only callbacks or files
+
+## Composition / slot bugs
+
+Symptoms:
+
+- child content disappears or cannot be modified
+- `Children.map` or `cloneElement` does nothing useful
+- component prop slot receives unusable data
+- Composite Component seems heavier than necessary
+
+Likely causes:
+
+- trying to inspect server-side slot placeholders
+- non-serializable slot args
+- using a Composite Component for a fragment that has no slots
+
+Fixes:
+
+- replace child inspection with a render prop
+- narrow slot args to serializable values
+- demote slotless composites to `renderServerComponent`
+
+## Cache / staleness bugs
+
+Symptoms:
+
+- stale UI after mutation
+- route revisits do not refresh when expected
+- route refreshes too often
+- Query errors or weird object merging on RSC values
+
+Likely causes:
+
+- invalidating the wrong cache owner
+- missing or oversized `loaderDeps`
+- missing `structuralSharing: false`
+- `staleTime` / `staleReloadMode` mismatch with desired UX
+
+Checks:
+
+- decide whether Router or Query owns the fragment
+- inspect `loaderDeps` for only the params actually used
+- verify Query key includes all real inputs
+- verify `structuralSharing: false`
+- use `router.invalidate()` only when the loader owns freshness
+
+## Error boundary surprises
+
+Rule:
+
+- awaited loader failure -> route `errorComponent`
+- deferred promise failure -> local ErrorBoundary around the deferred read
+
+If a single failing widget should not take down the route, stop awaiting it in the loader.
+
+## Serialization bugs
+
+Symptoms:
+
+- odd runtime decode failures
+- slot args rejected or malformed
+- custom serializer assumptions fail
+
+Likely causes:
+
+- passing classes, functions, Maps/Sets with custom serialization expectations, or other non-Flight-friendly values
+- relying on TanStack custom serialization inside RSCs
+
+Fixes:
+
+- reduce payloads to primitives, Dates, plain objects, arrays, and React elements where appropriate
+- pass IDs, not rich server objects, unless they are plain and intentionally serialized
+
+## Import protection and bundling gotchas
+
+- static imports of server functions are safe; the client build gets RPC stubs
+- dynamic imports of server functions can cause bundler issues
+- dev-mode import protection warnings can be informational because there is no tree-shaking; build output is the authoritative check
+
+## Code review checklist
+
+- correct primitive: renderable vs composite vs low-level stream
+- loader is orchestration, not secret storage
+- `loaderDeps` only covers actual inputs
+- Query-owned RSC uses `structuralSharing: false`
+- invalidation targets the real cache owner
+- mutations are explicit `POST` server functions
+- slot contracts are narrow and serializable
+- stale examples normalized to current APIs
+- route-level vs component-level error handling matches the UX requirement
+
+## Simplify-first recovery path
+
+When a bug is tangled across Query, Router, Composite Components, and SSR modes:
+
+1. collapse to one route-owned `renderServerComponent`
+2. verify the server function and loader path
+3. reintroduce Query only if you need independent ownership
+4. reintroduce Composite Components only if you need slots
+5. reintroduce deferred loading only if you need staggered reveal or isolated failures
+
+This sequence removes entire classes of bugs instead of trying to patch all of them at once.

package/skills/react-start/server-components/docs/sources.md

@@ -0,0 +1,39 @@
+# Official sources
+
+Validated on 2026-04-13.
+
+## TanStack Start
+
+- Server Components guide
+  https://tanstack.com/start/latest/docs/framework/react/guide/server-components
+
+- Server Functions guide
+  https://tanstack.com/start/latest/docs/framework/react/guide/server-functions
+
+- Execution Model guide
+  https://tanstack.com/start/latest/docs/framework/react/guide/execution-model
+
+- Import Protection guide
+  https://tanstack.com/start/latest/docs/framework/react/guide/import-protection
+
+## TanStack Router
+
+- Data Loading guide
+  https://tanstack.com/router/latest/docs/framework/react/guide/data-loading
+
+## TanStack blog
+
+- React Server Components Your Way
+  https://tanstack.com/blog/react-server-components
+
+## Vite
+
+- `@vitejs/plugin-rsc` documentation / discovery entry point
+  https://vite.dev/plugins/
+
+## Notes on drift observed during validation
+
+- Current RSC docs and blog use `renderServerComponent`, `createCompositeComponent`, `CompositeComponent`, and low-level Flight APIs from `@tanstack/react-start/rsc`.
+- Current Server Functions docs use `.inputValidator(...)`.
+- Some current RSC docs snippets still show older `.validator(...)`.
+- Older official repo examples may still show `renderRsc` and older config shapes. Prefer the current docs above.

package/skills/react-start/server-components/examples/01-renderable-route-loader.tsx

@@ -0,0 +1,28 @@
+// Current TanStack Start RSC pattern.
+// Replace route paths and data sources with your own app code.
+
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { renderServerComponent } from '@tanstack/react-start/rsc'
+
+function Greeting() {
+  return <h1>Hello from TanStack Start RSC</h1>
+}
+
+const getGreeting = createServerFn({ method: 'GET' }).handler(async () => {
+  const Renderable = await renderServerComponent(<Greeting />)
+  return { Renderable }
+})
+
+export const Route = createFileRoute('/hello')({
+  loader: async () => {
+    const { Renderable } = await getGreeting()
+    return { Greeting: Renderable }
+  },
+  component: HelloPage,
+})
+
+function HelloPage() {
+  const { Greeting } = Route.useLoaderData()
+  return <>{Greeting}</>
+}

package/skills/react-start/server-components/examples/02-composite-slots.tsx

@@ -0,0 +1,124 @@
+// Composite Component patterns:
+// - children slot for free-form composition
+// - render-prop slot when the server must pass data into client UI
+// - component prop slot for reusable typed interactive controls
+
+import type { ComponentType, ReactNode } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import {
+  CompositeComponent,
+  createCompositeComponent,
+} from '@tanstack/react-start/rsc'
+import { z } from 'zod'
+
+// Replace with your own server-only data layer
+declare const db: {
+  posts: {
+    findById(postId: string): Promise<{
+      id: string
+      authorId: string
+      title: string
+      body: string
+    }>
+  }
+  products: {
+    findById(productId: string): Promise<{
+      id: string
+      name: string
+      price: number
+    }>
+  }
+}
+
+const getPostCard = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ postId: z.string() }))
+  .handler(async ({ data }) => {
+    const post = await db.posts.findById(data.postId)
+
+    const src = await createCompositeComponent<{
+      children?: ReactNode
+      renderActions?: (args: { postId: string; authorId: string }) => ReactNode
+    }>((props) => (
+      <article className="card">
+        <h1>{post.title}</h1>
+        <p>{post.body}</p>
+
+        <footer>
+          {props.renderActions?.({
+            postId: post.id,
+            authorId: post.authorId,
+          })}
+        </footer>
+
+        <section>{props.children}</section>
+      </article>
+    ))
+
+    return { src }
+  })
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) =>
+    getPostCard({ data: { postId: params.postId } }),
+  component: PostPage,
+})
+
+function PostPage() {
+  const { src } = Route.useLoaderData()
+
+  return (
+    <CompositeComponent
+      src={src}
+      renderActions={({ postId, authorId }) => (
+        <PostActions postId={postId} authorId={authorId} />
+      )}
+    >
+      <Comments />
+    </CompositeComponent>
+  )
+}
+
+function Comments() {
+  return <div>Interactive comments go here</div>
+}
+
+function PostActions(props: { postId: string; authorId: string }) {
+  return (
+    <button type="button">
+      Moderate {props.postId} / {props.authorId}
+    </button>
+  )
+}
+
+// Component-prop slot variant
+const getProductCard = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ productId: z.string() }))
+  .handler(async ({ data }) => {
+    const product = await db.products.findById(data.productId)
+
+    const src = await createCompositeComponent<{
+      AddToCart?: ComponentType<{ productId: string; price: number }>
+    }>((props) => (
+      <section className="product-card">
+        <h2>{product.name}</h2>
+        {props.AddToCart ? (
+          <props.AddToCart productId={product.id} price={product.price} />
+        ) : null}
+      </section>
+    ))
+
+    return { src }
+  })
+
+function AddToCartButton(props: { productId: string; price: number }) {
+  return (
+    <button type="button">
+      Add {props.productId} at {props.price}
+    </button>
+  )
+}
+
+// Example usage somewhere else:
+// const { src } = await getProductCard({ data: { productId: 'p-1' } })
+// <CompositeComponent src={src} AddToCart={AddToCartButton} />

package/skills/react-start/server-components/examples/03-query-owned-rsc.tsx

@@ -0,0 +1,97 @@
+// Query-owned RSC pattern.
+// Assumes your router context provides a queryClient for SSR prefetch.
+
+import type { ReactNode } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import {
+  CompositeComponent,
+  createCompositeComponent,
+} from '@tanstack/react-start/rsc'
+import { useQueryClient, useSuspenseQuery } from '@tanstack/react-query'
+import { z } from 'zod'
+
+// Replace with your own data layer
+declare const db: {
+  posts: {
+    findById(postId: string): Promise<{
+      id: string
+      title: string
+      body: string
+    }>
+    update(
+      postId: string,
+      patch: { title?: string; body?: string },
+    ): Promise<void>
+  }
+}
+
+const getPostRsc = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ postId: z.string() }))
+  .handler(async ({ data }) => {
+    const post = await db.posts.findById(data.postId)
+
+    const src = await createCompositeComponent<{
+      renderActions?: (args: { postId: string }) => ReactNode
+    }>((props) => (
+      <article>
+        <h1>{post.title}</h1>
+        <p>{post.body}</p>
+        <footer>{props.renderActions?.({ postId: post.id })}</footer>
+      </article>
+    ))
+
+    return { src }
+  })
+
+const updatePost = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      postId: z.string(),
+      title: z.string().optional(),
+      body: z.string().optional(),
+    }),
+  )
+  .handler(async ({ data }) => {
+    await db.posts.update(data.postId, {
+      title: data.title,
+      body: data.body,
+    })
+  })
+
+const postQueryOptions = (postId: string) => ({
+  queryKey: ['post-rsc', postId],
+  structuralSharing: false,
+  queryFn: () => getPostRsc({ data: { postId } }),
+  staleTime: 5 * 60 * 1000,
+})
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ context, params }) => {
+    await context.queryClient.ensureQueryData(postQueryOptions(params.postId))
+  },
+  component: PostPage,
+})
+
+function PostPage() {
+  const { postId } = Route.useParams()
+  const queryClient = useQueryClient()
+
+  const { data } = useSuspenseQuery(postQueryOptions(postId))
+
+  const handleRename = async () => {
+    await updatePost({ data: { postId, title: 'Updated title' } })
+    await queryClient.invalidateQueries({ queryKey: ['post-rsc', postId] })
+  }
+
+  return (
+    <CompositeComponent
+      src={data.src}
+      renderActions={({ postId }) => (
+        <button type="button" onClick={handleRename}>
+          Refresh {postId}
+        </button>
+      )}
+    />
+  )
+}

package/skills/react-start/server-components/examples/04-selective-ssr-data-only.tsx

@@ -0,0 +1,72 @@
+// Selective SSR: the loader fetches the RSC on the server,
+// but the route component renders on the client because it needs browser APIs.
+
+import * as React from 'react'
+import type { ReactNode } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import {
+  CompositeComponent,
+  createCompositeComponent,
+} from '@tanstack/react-start/rsc'
+
+// Replace with your own server-side data source
+declare function getDashboardStats(): Promise<{
+  series: Array<{ x: number; y: number }>
+  totalUsers: number
+}>
+
+const getDashboard = createServerFn({ method: 'GET' }).handler(async () => {
+  const stats = await getDashboardStats()
+
+  const src = await createCompositeComponent<{
+    renderChart?: (args: {
+      series: Array<{ x: number; y: number }>
+    }) => ReactNode
+  }>((props) => (
+    <section>
+      <h1>Users: {stats.totalUsers}</h1>
+      {props.renderChart?.({ series: stats.series })}
+    </section>
+  ))
+
+  return { src }
+})
+
+export const Route = createFileRoute('/dashboard')({
+  ssr: 'data-only',
+  loader: async () => ({
+    Dashboard: await getDashboard(),
+  }),
+  component: DashboardPage,
+})
+
+function DashboardPage() {
+  const { Dashboard } = Route.useLoaderData()
+  const [width, setWidth] = React.useState(0)
+
+  React.useEffect(() => {
+    setWidth(window.innerWidth)
+  }, [])
+
+  return (
+    <CompositeComponent
+      src={Dashboard.src}
+      renderChart={({ series }) => (
+        <ResponsiveChart data={series} width={width} />
+      )}
+    />
+  )
+}
+
+// Replace with your real chart component
+function ResponsiveChart(props: {
+  data: Array<{ x: number; y: number }>
+  width: number
+}) {
+  return (
+    <pre>
+      {JSON.stringify({ width: props.width, points: props.data.length })}
+    </pre>
+  )
+}

package/skills/react-start/server-components/examples/05-ssr-false-browser-loader.tsx

@@ -0,0 +1,40 @@
+// Browser-owned loader pattern.
+// Use when the loader itself needs browser APIs such as localStorage.
+
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { renderServerComponent } from '@tanstack/react-start/rsc'
+import { z } from 'zod'
+
+const getDrawingTools = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ savedState: z.string().nullable() }))
+  .handler(async ({ data }) => {
+    const Tools = await renderServerComponent(
+      <ToolPalette savedState={data.savedState} />,
+    )
+
+    return { Tools }
+  })
+
+export const Route = createFileRoute('/canvas')({
+  ssr: false,
+  loader: async () => {
+    const savedState = localStorage.getItem('canvas-state')
+    return getDrawingTools({ data: { savedState } })
+  },
+  component: CanvasPage,
+})
+
+function CanvasPage() {
+  const { Tools } = Route.useLoaderData()
+  return <>{Tools}</>
+}
+
+function ToolPalette(props: { savedState: string | null }) {
+  return (
+    <section>
+      <h1>Canvas tools</h1>
+      <pre>{props.savedState ?? 'no saved state'}</pre>
+    </section>
+  )
+}

package/skills/react-start/server-components/examples/06-low-level-flight-api-route.tsx

@@ -0,0 +1,40 @@
+// Low-level Flight stream APIs.
+// Prefer high-level helpers unless you need a custom transport.
+
+import { createAPIFileRoute } from '@tanstack/react-start/api'
+import { createServerFn } from '@tanstack/react-start'
+import {
+  createFromFetch,
+  renderToReadableStream,
+} from '@tanstack/react-start/rsc'
+import { useSuspenseQuery } from '@tanstack/react-query'
+
+const getFlightStream = createServerFn({ method: 'GET' }).handler(async () => {
+  return renderToReadableStream(<div>Server rendered content</div>)
+})
+
+export const APIRoute = createAPIFileRoute('/api/rsc')({
+  GET: async () => {
+    const stream = await getFlightStream()
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/x-component',
+      },
+    })
+  },
+})
+
+const rscQueryOptions = () => ({
+  queryKey: ['api-rsc'],
+  structuralSharing: false,
+  queryFn: async () => {
+    const Renderable = await createFromFetch(fetch('/api/rsc'))
+    return { Renderable }
+  },
+})
+
+export function ApiBackedRscWidget() {
+  const { data } = useSuspenseQuery(rscQueryOptions())
+  return <>{data.Renderable}</>
+}