Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

server-components.md

1,135 lines31.3 KB

1---
2id: server-components
3title: Server Components
4---
5​
6> [!WARNING]
7> Server Components are experimental! The API may see refinements.
8​
9Server Components let you render React components on the server and stream them to the client. Heavy dependencies stay out of your bundle, data fetching lives in the component, and sensitive logic never reaches the browser.
10​
11## Setup
12​
13**Server Components are not enabled by default.** Complete these three steps first:
14​
15### 1. Install Build Tool-Specific RSC Dependencies
16​
17<!-- ::start:tabs variant="bundler" -->
18​
19# Vite
20​
21```bash
22npm install -D @vitejs/plugin-rsc
23# or
24pnpm add -D @vitejs/plugin-rsc
25# or
26yarn add -D @vitejs/plugin-rsc
27# or
28bun add -D @vitejs/plugin-rsc
29```
30​
31# Rsbuild
32​
33Rsbuild does not need a separate RSC plugin. Make sure your Rsbuild React dependencies are installed:
34​
35```bash
36npm install -D @rsbuild/core @rsbuild/plugin-react
37```
38​
39<!-- ::end:tabs -->
40​
41### 2. Configure Your Build Tool
42​
43Update your build tool config to enable RSC in the TanStack Start plugin:
44​
45<!-- ::start:tabs variant="bundler" -->
46​
47# Vite
48​
49```ts title="vite.config.ts"
50import { defineConfig } from 'vite'
51import { tanstackStart } from '@tanstack/react-start/plugin/vite'
52import viteReact from '@vitejs/plugin-react'
53import rsc from '@vitejs/plugin-rsc'
54​
55export default defineConfig({
56 plugins: [
57 tanstackStart({
58 rsc: {
59 enabled: true,
60 },
61 }),
62 rsc(),
63 viteReact(),
64 ],
65})
66```
67​
68# Rsbuild
69​
70```ts title="rsbuild.config.ts"
71import { defineConfig } from '@rsbuild/core'
72import { pluginReact } from '@rsbuild/plugin-react'
73import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'
74​
75export default defineConfig({
76 plugins: [
77 pluginReact(),
78 tanstackStart({
79 rsc: {
80 enabled: true,
81 },
82 }),
83 ],
84})
85```
86​
87<!-- ::end:tabs -->
88​
89**Requirements:** React 19+, Vite 8+ or Rsbuild 2+
90​
91## Quick Start
92​
93In TanStack Start, you typically create server-rendered UI in a server function, then return it through a route `loader`.
94​
95There are two high-level RSC helpers:
96​
97- `renderServerComponent(<Element />)` returns a **renderable value** you can inline like `{Renderable}`.
98- `createCompositeComponent((props) => <Element />)` returns a **composite source** rendered via `<CompositeComponent src={...} />` (supports slots).
99​
100### Renderable (no slots)
101​
102```tsx
103import { createFileRoute } from '@tanstack/react-router'
104import { createServerFn } from '@tanstack/react-start'
105import { renderServerComponent } from '@tanstack/react-start/rsc'
106​
107function Greeting() {
108 return <h1>Hello from RSC</h1>
110​
111const getGreeting = createServerFn().handler(async () => {
112 const Renderable = await renderServerComponent(<Greeting />)
113 return { Renderable }
114})
115​
116export const Route = createFileRoute('/')({
117 loader: async () => {
118 const { Renderable } = await getGreeting()
119 return { Greeting: Renderable }
120 },
121 component: HomePage,
122})
123​
124function HomePage() {
125 const { Greeting } = Route.useLoaderData()
126 return <>{Greeting}</>
128```
129​
130### Composite (slots)
131​
132```tsx
133import { createFileRoute } from '@tanstack/react-router'
134import { createServerFn } from '@tanstack/react-start'
135import {
136 CompositeComponent,
137 createCompositeComponent,
138} from '@tanstack/react-start/rsc'
139​
140const getCard = createServerFn().handler(async () => {
141 const src = await createCompositeComponent(
142 (props: { children?: React.ReactNode }) => (
143 <div className="card">
144 <h2>Server-rendered header</h2>
145 <div>{props.children}</div>
146 </div>
147 ),
148 )
149​
150 return { src }
151})
152​
153export const Route = createFileRoute('/')({
154 loader: async () => ({
155 Card: await getCard(),
156 }),
157 component: HomePage,
158})
159​
160function HomePage() {
161 const { Card } = Route.useLoaderData()
162​
163 return (
164 <CompositeComponent src={Card.src}>
165 <Counter />
166 </CompositeComponent>
167 )
169```
170​
171## Why Server Components?
172​
173- **Smaller bundles.** Markdown parsers, syntax highlighters, and heavy libraries run on the server. Only rendered HTML reaches the client.
174- **Colocated data fetching.** Fetch data directly in the component that needs it.
175- **Secure by default.** API keys, database queries, and business logic never appear in the client bundle.
176- **Progressive streaming.** UI streams to the browser as it renders. Users see content immediately.
177​
178## Passing Props and Composition
179​
180Renderable values returned from `renderServerComponent` do not support slots.
181​
182To accept client-provided props ("slots"), use `createCompositeComponent` and render it with `<CompositeComponent src={...} />`.
183​
184Slots are declared on the server component props. There are three types of slots:
185​
186| Slot Type | Use Case | Server Can Pass Data? |
187| --------------- | ------------------------------------------------- | --------------------- |
188| `children` | Simple composition | No |
189| Render props | Server passes data to client-rendered content | Yes |
190| Component props | Pass reusable components that receive server data | Yes |
191​
192### Children Slots
193​
194Pass client components as children. Simple and familiar, but the server cannot pass data to them:
195​
196```tsx
197import {
198 CompositeComponent,
199 createCompositeComponent,
200} from '@tanstack/react-start/rsc'
201​
202const getCard = createServerFn().handler(async () => {
203 const src = await createCompositeComponent(
204 (props: { children?: React.ReactNode }) => (
205 <div className="card">
206 <h2>Server-rendered header</h2>
207 <div>{props.children}</div>
208 </div>
209 ),
210 )
211​
212 return { src }
213})
214​
215function MyPage() {
216 const { src } = Route.useLoaderData()
217​
218 return (
219 <CompositeComponent src={src}>
220 {/* Client components with full interactivity */}
221 <Counter />
222 <button onClick={() => alert('Clicked!')}>Click me</button>
223 </CompositeComponent>
224 )
226```
227​
228### Render Props
229​
230Use render props when the server needs to pass data to client-rendered content:
231​
232```tsx
233import {
234 CompositeComponent,
235 createCompositeComponent,
236} from '@tanstack/react-start/rsc'
237​
238const getPost = createServerFn()
239 .validator(z.object({ postId: z.string() }))
240 .handler(async ({ data }) => {
241 const post = await db.posts.findById(data.postId)
242​
243 const src = await createCompositeComponent(
244 (props: {
245 children?: React.ReactNode
246 renderActions?: (data: {
247 postId: string
248 authorId: string
249 }) => React.ReactNode
250 }) => (
251 <article>
252 <h1>{post.title}</h1>
253 <p>{post.body}</p>
254 <footer>
255 {props.renderActions?.({
256 postId: post.id,
257 authorId: post.authorId,
258 })}
259 </footer>
260 {props.children}
261 </article>
262 ),
263 )
264​
265 return { src }
266 })
267​
268function PostPage() {
269 const { src } = Route.useLoaderData()
270​
271 return (
272 <CompositeComponent
273 src={src}
274 renderActions={({ postId, authorId }) => (
275 <PostActions postId={postId} authorId={authorId} />
276 )}
277 >
278 <Comments />
279 </CompositeComponent>
280 )
282```
283​
284### Component Props
285​
286Pass React components as props. On the client, the passed in props will be rendered with data supplied by the server:
287​
288```tsx
289import {
290 CompositeComponent,
291 createCompositeComponent,
292} from '@tanstack/react-start/rsc'
293​
294const getProductCard = createServerFn()
295 .validator(z.object({ productId: z.string() }))
296 .handler(async ({ data }) => {
297 const product = await db.products.findById(data.productId)
298​
299 const src = await createCompositeComponent(
300 ({
301 AddToCart,
302 }: {
303 AddToCart: React.ComponentType<{ productId: string; price: number }>
304 }) => (
305 <div className="product-card">
306 <h2>{product.name}</h2>
307 <p>${product.price}</p>
308 <AddToCart productId={product.id} price={product.price} />
309 </div>
310 ),
311 )
312​
313 return { src }
314 })
315​
316// Client component with interactivity
317function AddToCartButton({
318 productId,
319 price,
320}: {
321 productId: string
322 price: number
323}) {
324 const [added, setAdded] = React.useState(false)
325​
326 return (
327 <button onClick={() => setAdded(true)}>
328 {added ? 'âś“ Added!' : `Add to Cart - $${price}`}
329 </button>
330 )
332​
333function ProductPage() {
334 const { src } = Route.useLoaderData()
335​
336 return <CompositeComponent src={src} AddToCart={AddToCartButton} />
338```
339​
340Component props are useful when:
341​
342- You want to pass reusable client components
343- The component needs its own state or event handlers
344- You prefer component composition over render prop callbacks
345​
346All three slot types can be combined. `createCompositeComponent` provides full type safety for slot props.
347​
348## Caching
349​
350Server components work with TanStack Router's built-in caching. The cache key is the route path plus params:
351​
352```tsx
353export const Route = createFileRoute('/posts/$postId')({
354 loader: async ({ params }) => ({
355 Post: await getPost({ data: { postId: params.postId } }),
356 }),
357 component: PostPage,
358})
359```
360​
361Navigate to `/posts/abc`, then `/posts/xyz`, then back to `/posts/abc` - the cached component renders instantly.
362​
363Control freshness with `staleTime`:
364​
365```tsx
366export const Route = createFileRoute('/posts/$postId')({
367 staleTime: 10_000, // Fresh for 10 seconds
368 loader: async ({ params }) => ({
369 Post: await getPost({ data: { postId: params.postId } }),
370 }),
371 component: PostPage,
372})
373```
374​
375For cache keys beyond route params, use `loaderDeps`:
376​
377```tsx
378export const Route = createFileRoute('/posts/$postId')({
379 loaderDeps: ({ search }) => ({ tab: search.tab }),
380 loader: async ({ params, deps }) => ({
381 Post: await getPost({ data: { postId: params.postId, tab: deps.tab } }),
382 }),
383 component: PostPage,
384})
385```
386​
387### TanStack Query
388​
389For fine-grained control, use TanStack Query:
390​
391```tsx
392import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query'
393​
394const postQueryOptions = (postId: string) => ({
395 queryKey: ['post', postId],
396 structuralSharing: false, // Required - RSC values must not be merged
397 queryFn: () => getPost({ data: { postId } }),
398 staleTime: 5 * 60 * 1000,
399})
400​
401export const Route = createFileRoute('/posts/$postId')({
402 loader: async ({ context, params }) => {
403 // Prefetch during SSR - data reused on client without refetch
404 await context.queryClient.query({
405 ...postQueryOptions(params.postId),
406 staleTime: 'static',
407 })
408 },
409 component: PostPage,
410})
411​
412function PostPage() {
413 const { postId } = Route.useParams()
414 const queryClient = useQueryClient()
415​
416 const { data } = useSuspenseQuery(postQueryOptions(postId))
417​
418 const handleRefresh = () => {
419 // Manually refetch the RSC
420 queryClient.refetchQueries({ queryKey: ['post', postId] })
421 }
422​
423 return <CompositeComponent src={data.src} />
425```
426​
427> [!IMPORTANT]
428> Always set `structuralSharing: false` when caching server components with React Query. Without this, React Query may attempt to merge RSC values between fetches, which can cause errors.
429​
430### Invalidation
431​
432To refetch a server component after data changes, use `router.invalidate()`:
433​
434```tsx
435import { useRouter } from '@tanstack/react-router'
436​
437function PostPage() {
438 const router = useRouter()
439 const { Post } = Route.useLoaderData()
440​
441 const handleUpdate = async () => {
442 await updatePost({ data: { ... } })
443 // Refetch the route's loader, including the RSC
444 router.invalidate()
445 }
446​
447 return (
448 <CompositeComponent
449 src={Post.src}
450 renderActions={() => (
451 <button onClick={handleUpdate}>Update Post</button>
452 )}
453 />
454 )
456```
457​
458This pattern is useful when server functions mutate data that the RSC displays. After the mutation completes, `router.invalidate()` triggers the loader to run again, fetching a fresh server component with updated data.
459​
460## Combining with Selective SSR
461​
462Server Components pair with [Selective SSR](./selective-ssr.md) when you need server-rendered content but client-only rendering for the route component itself.
463​
464### Example: `ssr: 'data-only'`
465​
466The server fetches the RSC, but the route component renders on the client:
467​
468```tsx
469export const Route = createFileRoute('/dashboard')({
470 ssr: 'data-only',
471 loader: async () => ({
472 Dashboard: await getDashboard(),
473 }),
474 component: DashboardPage,
475})
476​
477function DashboardPage() {
478 const { Dashboard } = Route.useLoaderData()
479 const [width, setWidth] = React.useState(0)
480​
481 React.useEffect(() => {
482 setWidth(window.innerWidth) // Browser API
483 }, [])
484​
485 return (
486 <Dashboard
487 renderChart={({ data }) => <ResponsiveChart data={data} width={width} />}
488 />
489 )
491```
492​
493This is useful when:
494​
495- The server component fetches data and renders static content
496- The route component needs `window`, `localStorage`, or other browser APIs
497- You want the server component data ready before the client renders
498​
499### Example: `ssr: false`
500​
501Both loader and component run on the client:
502​
503```tsx
504export const Route = createFileRoute('/canvas')({
505 ssr: false,
506 loader: async () => {
507 const savedState = localStorage.getItem('canvas-state')
508 return { Tools: await getDrawingTools({ data: { savedState } }) }
509 },
510 component: CanvasPage,
511})
512```
513​
514Use this when the loader itself requires browser APIs.
515​
516## Advanced Patterns
517​
518### Multiple Server Components in Parallel
519​
520When a page needs several independent server components, fetch them in parallel using `Promise.all`. Each component renders independently with its own data.
521​
522**When to use:** Components from separate data sources with no shared dependencies. Maximizes concurrency when each component has independent fetch logic.
523​
524```tsx
525const getArticleA = createServerFn().handler(async () => {
526 const article = await db.articles.findById('a')
527 return renderServerComponent(<Article data={article} />)
528})
529​
530const getArticleB = createServerFn().handler(async () => {
531 const article = await db.articles.findById('b')
532 return renderServerComponent(<Article data={article} />)
533})
534​
535const getSidebar = createServerFn().handler(async () => {
536 const trending = await db.articles.getTrending()
537 return renderServerComponent(<Sidebar items={trending} />)
538})
539​
540export const Route = createFileRoute('/news')({
541 loader: async () => {
542 const [ArticleA, ArticleB, Sidebar] = await Promise.all([
543 getArticleA(),
544 getArticleB(),
545 getSidebar(),
546 ])
547 return { ArticleA, ArticleB, Sidebar }
548 },
549 component: NewsPage,
550})
551​
552function NewsPage() {
553 const { ArticleA, ArticleB, Sidebar } = Route.useLoaderData()
554​
555 return (
556 <div className="grid">
557 <main>
558 {ArticleA}
559 {ArticleB}
560 </main>
561 <aside>{Sidebar}</aside>
562 </div>
563 )
565```
566​
567Each server function executes concurrently. The page renders when all complete.
568​
569### Bundling Multiple Components
570​
571Return multiple server components from a single server function when they share data or should be fetched together. This reduces network round trips.
572​
573**When to use:** Components that share fetched data, need a single cache key, or should invalidate together. Reduces database queries and network round trips.
574​
575#### Using Promise.all
576​
577Create multiple `renderServerComponent` or `createCompositeComponent` calls and return them as an object:
578​
579```tsx
580const getPageLayout = createServerFn().handler(async () => {
581 // Fetch shared data once
582 const user = await db.users.getCurrent()
583 const config = await db.config.get()
584​
585 // Create multiple components that share this data
586 const [Header, Content, Footer] = await Promise.all([
587 renderServerComponent(
588 <header>
589 <Logo />
590 <nav>
591 {config.navItems.map((item) => (
592 <NavLink key={item.id} {...item} />
593 ))}
594 </nav>
595 <UserMenu name={user.name} />
596 </header>,
597 ),
598 renderServerComponent(
599 <main>
600 <h1>Welcome, {user.name}</h1>
601 <Dashboard stats={user.stats} />
602 </main>,
603 ),
604 renderServerComponent(
605 <footer>
606 <span>{config.copyright}</span>
607 {config.footerLinks.map((link) => (
608 <a key={link.id} href={link.url}>
609 {link.label}
610 </a>
611 ))}
612 </footer>,
613 ),
614 ])
615​
616 return { Header, Content, Footer }
617})
618​
619export const Route = createFileRoute('/dashboard')({
620 loader: async () => await getPageLayout(),
621 component: DashboardPage,
622})
623​
624function DashboardPage() {
625 const { Header, Content, Footer } = Route.useLoaderData()
626​
627 return (
628 <>
629 {Header}
630 {Content}
631 {Footer}
632 </>
633 )
635```
636​
637#### Using Nested Structures
638​
639Alternatively, return a nested object structure from a single server function.
640​
641- Use `renderServerComponent` when you just need renderables (no slots).
642- Use `createCompositeComponent` when you want each part to accept slots.
643​
644```tsx
645const getPageLayout = createServerFn().handler(async () => {
646 const user = await db.users.getCurrent()
647 const config = await db.config.get()
648​
649 const [Header, Content, Footer] = await Promise.all([
650 createCompositeComponent((props: { children?: React.ReactNode }) => (
651 <header>
652 <Logo />
653 <nav>
654 {config.navItems.map((item) => (
655 <NavLink key={item.id} {...item} />
656 ))}
657 </nav>
658 <UserMenu name={user.name} />
659 {props.children}
660 </header>
661 )),
662 createCompositeComponent(
663 (props: { renderActions?: () => React.ReactNode }) => (
664 <main>
665 <h1>Welcome, {user.name}</h1>
666 <Dashboard stats={user.stats} />
667 {props.renderActions?.()}
668 </main>
669 ),
670 ),
671 createCompositeComponent(() => (
672 <footer>
673 <span>{config.copyright}</span>
674 {config.footerLinks.map((link) => (
675 <a key={link.id} href={link.url}>
676 {link.label}
677 </a>
678 ))}
679 </footer>
680 )),
681 ])
682​
683 return { Header, Content, Footer }
684})
685​
686export const Route = createFileRoute('/dashboard')({
687 loader: async () => ({
688 Layout: await getPageLayout(),
689 }),
690 component: DashboardPage,
691})
692```
693​
694Render nested composites using dot notation:
695​
696```tsx
697import { CompositeComponent } from '@tanstack/react-start/rsc'
698​
699function DashboardPage() {
700 const { Layout } = Route.useLoaderData()
701​
702 return (
703 <>
704 <CompositeComponent src={Layout.Header}>
705 <button onClick={() => setMenuOpen(true)}>Menu</button>
706 </CompositeComponent>
707 <CompositeComponent
708 src={Layout.Content}
709 renderActions={() => <ActionButtons />}
710 />
711 <CompositeComponent src={Layout.Footer} />
712 </>
713 )
715```
716​
717Or destructure them from the loader data:
718​
719```tsx
720import { CompositeComponent } from '@tanstack/react-start/rsc'
721​
722function DashboardPage() {
723 const { Header, Content, Footer } = Route.useLoaderData().Layout
724​
725 return (
726 <>
727 <CompositeComponent src={Header}>
728 <button onClick={() => setMenuOpen(true)}>Menu</button>
729 </CompositeComponent>
730 <CompositeComponent
731 src={Content}
732 renderActions={() => <ActionButtons />}
733 />
734 <CompositeComponent src={Footer} />
735 </>
736 )
738```
739​
740Each nested component receives its own slot props independently. The `children` passed to `<CompositeComponent src={Header}>` only affects that component, not the others.
741​
742All three components share the same user and config data from a single database query.
743​
744### Deferred Component Loading
745​
746Return promises for server components instead of awaiting them. The client uses `React.use()` with `Suspense` to render each component as it resolves.
747​
748**When to use:** Components with varying data latencies where faster results should render before slower ones complete. Avoids blocking on the slowest query.
749​
750```tsx
751import { Suspense, use } from 'react'
752​
753const getDashboardBundle = createServerFn().handler(() => ({
754 // Fast - resolves in ~100ms
755 QuickStats: (async () => {
756 const stats = await cache.getStats() // Fast cache hit
757 return renderServerComponent(<StatsCard data={stats} />)
758 })(),
759​
760 // Medium - resolves in ~500ms
761 RecentActivity: (async () => {
762 const activity = await db.activity.getRecent()
763 return renderServerComponent(<ActivityFeed items={activity} />)
764 })(),
765​
766 // Slow - resolves in ~2000ms
767 Analytics: (async () => {
768 const data = await analytics.computeMetrics() // Expensive query
769 return renderServerComponent(<AnalyticsChart data={data} />)
770 })(),
771}))
772​
773export const Route = createFileRoute('/dashboard')({
774 loader: () => getDashboardBundle(),
775 component: DashboardPage,
776})
777​
778function DashboardPage() {
779 const { QuickStats, RecentActivity, Analytics } = Route.useLoaderData()
780​
781 return (
782 <div>
783 <Suspense fallback={<Skeleton />}>
784 <Deferred promise={QuickStats} />
785 </Suspense>
786​
787 <Suspense fallback={<Skeleton />}>
788 <Deferred promise={RecentActivity} />
789 </Suspense>
790​
791 <Suspense fallback={<Skeleton />}>
792 <Deferred promise={Analytics} />
793 </Suspense>
794 </div>
795 )
797​
798function Deferred({ promise }: { promise: Promise<unknown> }) {
799 const Renderable = use(promise)
800 return <>{Renderable}</>
802```
803​
804QuickStats appears first, RecentActivity follows, then Analytics loads last. Users see progressive content instead of waiting for everything.
805​
806### Suspense Inside Server Components
807​
808Use React's `Suspense` directly inside server components to stream parts of the component as they become ready.
809​
810**When to use:** A single server component with multiple async child components that should stream independently. Keeps related UI in one component while allowing progressive rendering.
811​
812```tsx
813async function SlowMetric({ label, delay }: { label: string; delay: number }) {
814 await new Promise((resolve) => setTimeout(resolve, delay))
815 const value = await db.metrics.get(label)
816​
817 return (
818 <div className="metric">
819 <span>{label}</span>
820 <span>{value.toLocaleString()}</span>
821 </div>
822 )
824​
825const getAnalyticsDashboard = createServerFn().handler(() =>
826 renderServerComponent(
827 <div className="dashboard">
828 <h1>Analytics</h1>
829​
830 <div className="metrics-grid">
831 <Suspense fallback={<MetricSkeleton label="Active Users" />}>
832 <SlowMetric label="Active Users" delay={500} />
833 </Suspense>
834​
835 <Suspense fallback={<MetricSkeleton label="Revenue" />}>
836 <SlowMetric label="Revenue" delay={1500} />
837 </Suspense>
838​
839 <Suspense fallback={<MetricSkeleton label="Conversion" />}>
840 <SlowMetric label="Conversion" delay={2500} />
841 </Suspense>
842 </div>
843 </div>,
844 ),
846```
847​
848Each metric streams independently. The dashboard shell appears immediately, then metrics pop in as their data loads.
849​
850### Streaming with Async Generators
851​
852Use async generators to stream server components one at a time. The client receives and renders each component as it's yielded.
853​
854**When to use:** Unbounded or large result sets where items should render incrementally. Useful when processing time per item varies or total count is unknown upfront.
855​
856```tsx
857import {
858 CompositeComponent,
859 createCompositeComponent,
860} from '@tanstack/react-start/rsc'
861​
862const streamNotifications = createServerFn().handler(async function* () {
863 // Yield initial batch immediately
864 const recent = await db.notifications.getRecent(3)
865 for (const notification of recent) {
866 yield await createCompositeComponent<{
867 renderActions?: (data: { id: string }) => React.ReactNode
868 }>((props) => (
869 <div className="notification">
870 <h3>{notification.title}</h3>
871 <p>{notification.message}</p>
872 {props.renderActions?.({ id: notification.id })}
873 </div>
874 ))
875 }
876​
877 // Stream older notifications with delays
878 const older = await db.notifications.getOlder(5)
879 for (const notification of older) {
880 await new Promise((resolve) => setTimeout(resolve, 300))
881 yield await createCompositeComponent<{
882 renderActions?: (data: { id: string }) => React.ReactNode
883 }>((props) => (
884 <div className="notification">
885 <h3>{notification.title}</h3>
886 <p>{notification.message}</p>
887 {props.renderActions?.({ id: notification.id })}
888 </div>
889 ))
890 }
891})
892​
893export const Route = createFileRoute('/notifications')({
894 component: NotificationsPage,
895})
896​
897function NotificationsPage() {
898 const [notifications, setNotifications] = React.useState<Array<unknown>>([])
899 const [isStreaming, setIsStreaming] = React.useState(false)
900​
901 const startStreaming = React.useCallback(async () => {
902 setNotifications([])
903 setIsStreaming(true)
904​
905 const stream = await streamNotifications()
906 for await (const notification of stream) {
907 setNotifications((prev) => [...prev, notification])
908 }
909​
910 setIsStreaming(false)
911 }, [])
912​
913 return (
914 <div>
915 <button onClick={startStreaming} disabled={isStreaming}>
916 {isStreaming ? 'Streaming...' : 'Load Notifications'}
917 </button>
918​
919 {notifications.map((notificationSrc, i) => (
920 <CompositeComponent
921 key={i}
922 src={notificationSrc}
923 renderActions={({ id }) => (
924 <button onClick={() => markAsRead(id)}>Mark read</button>
925 )}
926 />
927 ))}
928 </div>
929 )
931```
932​
933Notifications appear one by one. The first three show immediately, then more stream in. Each supports client interactivity through render props.
934​
935## Error Handling
936​
937Errors in Server Components—whether during data fetching or rendering—propagate to the client.
938​
939### Route Level Errors
940​
941If a Server Component fails to load in the `loader`, the route's `errorComponent` renders:
942​
943```tsx
944export const Route = createFileRoute('/')({
945 loader: async () => ({
946 // If this fails, the errorComponent renders
947 Greeting: await getGreeting(),
948 }),
949 errorComponent: ({ error }) => <div>Failed to load: {error.message}</div>,
950 component: HomePage,
951})
952```
953​
954### Component Level Errors
955​
956To isolate errors (e.g., preventing a single failing widget from crashing the page), you must use **[Deferred Loading](#deferred-component-loading)**.
957​
958By returning a Promise from the loader instead of awaiting it, the Route Component renders immediately. If the Promise later rejects, the `ErrorBoundary` inside your component catches it.
959​
960```tsx
961// 1. Loader returns a Promise (don't await!)
962export const Route = createFileRoute('/dashboard')({
963 loader: () => ({
964 // If this fails, only the specific ErrorBoundary below catches it
965 WidgetPromise: getWidget(),
966 }),
967 component: DashboardPage,
968})
969​
970// 2. Component handles the potential failure
971function DashboardPage() {
972 const { WidgetPromise } = Route.useLoaderData()
973​
974 return (
975 <ErrorBoundary fallback={<div>Widget unavailable</div>}>
976 <React.Suspense fallback={<Skeleton />}>
977 <Deferred promise={WidgetPromise} />
978 </React.Suspense>
979 </ErrorBoundary>
980 )
982```
983​
984## Tips
985​
986### Using `React.cache`
987​
988`React.cache` works inside server components for request-scoped memoization. This is useful when multiple components need the same expensive computation:
989​
990```tsx
991import { cache } from 'react'
992​
993const getUser = cache(async (userId: string) => {
994 return db.users.findById(userId)
995})
996​
997// Both components share the same cached result within a single request
998async function UserHeader() {
999 const user = await getUser('123') // Fetches from DB
1000 return <h1>{user.name}</h1>
1002​
1003async function UserSidebar() {
1004 const user = await getUser('123') // Returns cached result
1005 return <aside>{user.bio}</aside>
1007```
1008​
1009### Router Links in Server Components
1010​
1011TanStack Router's `Link` component works inside server components. The link is serialized and hydrates on the client for client-side navigation:
1012​
1013```tsx
1014import { Link } from '@tanstack/react-router'
1015​
1016const getNavigation = createServerFn().handler(async () => {
1017 const pages = await db.pages.list()
1018​
1019 return renderServerComponent(
1020 <nav>
1021 {pages.map((page) => (
1022 <Link key={page.id} to="/pages/$pageId" params={{ pageId: page.id }}>
1023 {page.title}
1024 </Link>
1025 ))}
1026 </nav>,
1029```
1030​
1031### CSS in Server Components
1032​
1033CSS Modules and global CSS imports work in server components. Styles are extracted and sent to the client:
1034​
1035```tsx
1036import styles from './Card.module.css'
1037​
1038const getCard = createServerFn().handler(async () => {
1039 return renderServerComponent(
1040 <div className={styles.card}>
1041 <h2 className={styles.title}>Server Rendered</h2>
1042 </div>,
1045```
1046​
1047## Rules and Limitations
1048​
1049### Slots are opaque on the server
1050​
1051The server cannot inspect slot content. `React.Children.map()` and `cloneElement()` won't work on `props.children`:
1052​
1053```tsx
1054// Won't work - children is a placeholder on the server
1055createCompositeComponent((props: { children?: React.ReactNode }) => (
1056 <div>
1057 {React.Children.map(props.children, (child) =>
1058 React.cloneElement(child, { extra: 'prop' }),
1059 )}
1060 </div>
1062​
1063// Do this instead - use render props
1064createCompositeComponent<{
1065 renderItem?: (data: { extra: string }) => React.ReactNode
1066}>((props) => <div>{props.renderItem?.({ extra: 'prop' })}</div>)
1067```
1068​
1069### Render prop arguments must be serializable
1070​
1071Arguments passed to slots via render props and or components travel through React's Flight protocol. Use serializable values only: strings, numbers, booleans, null, plain objects, and arrays.
1072​
1073## How It Works
1074​
1075When a server component accesses slot props, it accesses a proxy:
1076​
1077- Reading `props.children` creates a placeholder for "whatever children the caller provides"
1078- Calling `props.renderFn(args)` creates a placeholder that records `args`
1079​
1080TanStack Start sends a React Flight stream with these placeholders. On the client, placeholders are replaced with the actual props you passed when rendering.
1081​
1082## Current Status
1083​
1084Server Components are experimental in TanStack Start and will remain so into early v1.
1085​
1086**Serialization:** Uses React's native Flight protocol. TanStack Start's custom serialization isn't available in server components yet. Primitives, Dates, and React elements work. Custom serialization coming in a future release.
1087​
1088**API:** The RSC helper APIs may see refinements.
1089​
1090Questions? [Open an issue](https://github.com/tanstack/router/issues) or join the [Discord](https://tlinz.com/discord).
1091​
1092## Low-Level Flight Stream APIs
1093​
1094For advanced use cases (custom streaming protocols, API route integration, external RSC-aware systems), TanStack Start exposes low-level Flight stream APIs. For most cases, prefer the high-level helpers which handle caching, streaming, and (for composites) slots automatically.
1095​
1096Import from `@tanstack/react-start/rsc`:
1097​
1098| Function | Available in | Description |
1099| -------------------------- | --------------------- | -------------------------------------------------- |
1100| `renderToReadableStream` | server functions only | Renders React elements to a Flight stream |
1101| `createFromFetch` | Client | Decodes a Flight stream from a `Promise<Response>` |
1102| `createFromReadableStream` | Client/SSR | Decodes a Flight stream from a `ReadableStream` |
1103​
1104`createFromFetch` is a convenience wrapper around `createFromReadableStream` that accepts a fetch promise directly and extracts the body stream internally.
1105​
1106### Example
1107​
1108```tsx
1109// src/routes/api/rsc.ts - API route with Flight stream
1110import { createAPIFileRoute } from '@tanstack/react-start/api'
1111import { createServerFn } from '@tanstack/react-start'
1112import { renderToReadableStream } from '@tanstack/react-start/rsc'
1113​
1114const getFlightStream = createServerFn({ method: 'GET' }).handler(async () => {
1115 return renderToReadableStream(<div>Server Rendered Content</div>)
1117​
1118export const APIRoute = createAPIFileRoute('/api/rsc')({
1119 GET: async () => {
1120 const stream = await getFlightStream()
1121 return new Response(stream, {
1122 headers: { 'Content-Type': 'text/x-component' },
1123 })
1124 },
1126```
1127​
1128```tsx
1129// Client: fetch and decode the Flight stream
1130import { createFromFetch } from '@tanstack/react-start/rsc'
1131​
1132async function fetchRSC() {
1133 return createFromFetch(fetch('/api/rsc'))
1135```