TanStack Start React Server Components

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