React Server Components

Relevant source files

• docs/api/rsc/RSCHydratedRouter.md
• docs/api/rsc/RSCStaticRouter.md
• docs/api/rsc/createCallServer.md
• docs/api/rsc/getRSCStream.md
• docs/api/rsc/matchRSCServerRequest.md
• docs/api/rsc/routeRSCServerRequest.md
• docs/how-to/middleware.md
• docs/how-to/react-server-components.md
• docs/index.md
• docs/start/data/route-object.md
• docs/start/data/routing.md
• docs/start/framework/actions.md
• docs/start/framework/data-loading.md
• docs/start/framework/installation.md
• docs/start/framework/navigating.md
• docs/start/framework/pending-ui.md
• docs/start/framework/rendering.md
• docs/start/framework/route-module.md
• docs/start/framework/routing.md
• integration/helpers/rsc-vite/src/entry.ssr.tsx
• integration/rsc/rsc-nojs-test.ts
• integration/rsc/rsc-test.ts
• integration/single-fetch-test.ts
• integration/vite-prerender-test.ts
• integration/vite-spa-mode-test.ts
• packages/react-router-dev/config/default-rsc-entries/entry.ssr.tsx
• packages/react-router-dev/vite/plugin.ts
• packages/react-router/lib/dom-export/hydrated-router.tsx
• packages/react-router/lib/dom/ssr/components.tsx
• packages/react-router/lib/dom/ssr/single-fetch.tsx
• packages/react-router/lib/errors.ts
• packages/react-router/lib/rsc/browser.tsx
• packages/react-router/lib/rsc/server.rsc.ts
• packages/react-router/lib/rsc/server.ssr.tsx
• packages/react-router/lib/server-runtime/routes.ts
• packages/react-router/lib/server-runtime/server.ts
• packages/react-router/lib/server-runtime/single-fetch.ts
• playground/rsc-vite/src/entry.ssr.tsx

Purpose and Scope

This document describes React Router's integration with React Server Components (RSC), an experimental feature that enables server-side rendering of React components in a separate environment from client code. This covers the server-side request matching and payload generation, client-side hydration and navigation, and the communication protocol between server and client.

For information about standard server-side rendering without RSC, see sections 4.1 and 4.2. For middleware integration, see 3.5.

Status: RSC support is experimental and subject to breaking changes in minor/patch releases.

Architecture Overview

React Router's RSC implementation provides a complete solution for server components, including request routing, payload serialization, client hydration, and navigation. The system operates in both Framework Mode and Data Mode, with slight API differences between them.

Core Components

Sources: packages/react-router/lib/rsc/server.rsc.ts1-900 packages/react-router/lib/rsc/server.ssr.tsx1-400 packages/react-router/lib/rsc/browser.tsx1-800

Request Processing Pipeline

Server-Side Request Matching

The matchRSCServerRequest function handles incoming requests and routes them to the appropriate handlers. It operates in two modes: document requests and data requests.

Key Functions:

Function	Location	Purpose
matchRSCServerRequest	server.rsc.ts700-900	Main entry point for RSC request handling
handleAction	server.rsc.ts450-550	Executes server actions and manages redirects
handleLoaders	server.rsc.ts550-650	Runs loader functions for matched routes
encodeRSCPayload	server.rsc.ts850-900	Serializes payload to ReadableStream

Sources: packages/react-router/lib/rsc/server.rsc.ts700-900 docs/api/rsc/matchRSCServerRequest.md1-100

SSR Integration

The routeRSCServerRequest function integrates RSC with traditional SSR, handling both HTML rendering and data requests:

Integration Points:

• Payload Decoding: Uses bundler-specific createFromReadableStream (server.ssr.tsx38-40)
• HTML Streaming: Leverages React 19's renderHTMLToReadableStream (server.ssr.tsx100-150)
• Payload Injection: Embeds RSC payload in HTML for hydration (server.ssr.tsx200-250)

Sources: packages/react-router/lib/rsc/server.ssr.tsx1-400 docs/api/rsc/routeRSCServerRequest.md1-80

Payload Types and Structure

React Router defines four distinct payload types for different response scenarios:

Payload Type Definitions

Payload Type Details:

Type	Purpose	Key Fields	Usage
RSCRenderPayload	Full page render	matches, loaderData, errors, patches	Initial page load, navigation
RSCManifestPayload	Route discovery	patches	Fog-of-war route loading
RSCActionPayload	Server action result	actionResult, rerender	Form submissions, server actions
RSCRedirectPayload	Navigation redirect	location, status, replace	Server-initiated redirects

Sources: packages/react-router/lib/rsc/server.rsc.ts228-277

Route Manifest Structure

The RSCRouteManifest describes route metadata for client-side routing:

Sources: packages/react-router/lib/rsc/server.rsc.ts202-221

Client-Side Hydration and Navigation

RSCHydratedRouter

The RSCHydratedRouter component manages client-side routing with RSC payloads:

Initialization Flow:

1. Payload Retrieval: Calls getPayload() to decode initial RSC payload from SSR (browser.tsx200-250)
2. Route Construction: Builds DataRouteObject[] from RSCRouteManifest[] (browser.tsx250-300)
3. Hydration Data: Extracts loader data and errors for initial state (browser.tsx300-350)
4. Data Strategy: Configures navigation data fetching with getRSCDataStrategy() (browser.tsx400-500)

Sources: packages/react-router/lib/rsc/browser.tsx150-500 docs/api/rsc/RSCHydratedRouter.md1-100

Navigation Data Strategy

The RSC data strategy handles navigation and data fetching differently from standard single-fetch:

Key Differences from Standard Single Fetch:

Aspect	Standard Single Fetch	RSC Single Fetch
URL Extension	.data	.rsc
Encoding	Turbo-stream	React Flight
Server Actions	Regular POST	callServer() with encoding
Components	Client-only	Server + Client components
Streaming	Turbo-stream decoder	createFromReadableStream

Sources: packages/react-router/lib/rsc/browser.tsx500-800 packages/react-router/lib/dom/ssr/single-fetch.tsx178-297

Server Actions and CallServer

Server Action Execution

Server actions allow client components to call server-side functions directly:

Server Action Context:

The AsyncLocalStorage context tracks whether an action is currently executing, allowing the redirect(), redirectDocument(), and replace() functions to capture redirects and store them for later processing (server.rsc.ts79-122).

Action Handler Flow:

1. Action Discovery: Server receives POST with action ID (server.rsc.ts450-480)
2. Decoding: decodeAction(formData) deserializes arguments (server.rsc.ts480-500)
3. Execution: Action runs within AsyncLocalStorage context (server.rsc.ts500-530)
4. Redirect Capture: If action calls redirect(), stored in context (server.rsc.ts91-99)
5. Result Encoding: Action result serialized to RSC payload (server.rsc.ts530-550)

Sources: packages/react-router/lib/rsc/server.rsc.ts79-550 packages/react-router/lib/rsc/browser.tsx100-200

CallServer Implementation

The createCallServer function creates the React callServer implementation:

Action ID Management:

Each server action call increments window.__routerActionID to provide unique identifiers for tracking and debugging (browser.tsx120-150).

Sources: packages/react-router/lib/rsc/browser.tsx67-200 docs/api/rsc/createCallServer.md1-80

Error Handling

Error Boundary Hierarchy

RSC error handling uses a specialized error boundary structure:

Error Flow:

1. Error Origin: Errors can originate from loaders, actions, or component rendering (server.rsc.ts450-650)
2. Digest Creation: Server wraps certain errors in digests for serialization (server.rsc.ts300-350)
3. Client Decoding: Client unwraps digests to reconstruct errors (browser.tsx600-650)
4. Boundary Rendering: Nearest ErrorBoundary catches and renders error UI (errorBoundaries.tsx1-100)

Special Error Types:

• Redirect Errors: Captured via digest, trigger client-side navigation (errors.ts67-80)
• RouteErrorResponse: 404s and other HTTP errors serialized with digest (errors.ts69-90)

Sources: packages/react-router/lib/rsc/server.rsc.ts300-350 packages/react-router/lib/errors.ts67-90 packages/react-router/lib/rsc/errorBoundaries.tsx1-100

Route Discovery and Manifest Updates

Fog-of-War Pattern

RSC supports lazy route discovery through manifest requests:

Manifest Request Parameters:

• paths: Comma-separated list of paths to fetch routes for
• Includes partial paths for pathless/index route discovery
• Response cached by version to avoid duplicate requests

Patch Processing:

1. Client Request: Navigation to unknown path triggers manifest fetch (browser.tsx700-750)
2. Server Matching: Server matches all paths and collects route definitions (server.rsc.ts650-700)
3. Patch Transmission: RSCManifestPayload contains route metadata (server.rsc.ts245-249)
4. Client Update: patchRoutesOnNavigation adds routes to router (browser.tsx750-800)

Sources: packages/react-router/lib/rsc/server.rsc.ts650-700 packages/react-router/lib/rsc/browser.tsx700-800

Integration with Standard Features

Middleware Compatibility

RSC routes support middleware in a similar way to standard routes, with some limitations:

Middleware Execution Context:

• Middleware runs in same AsyncLocalStorage context as actions
• Can access and modify request/context before handlers
• Response transformations limited by RSC encoding requirements

Sources: packages/react-router/lib/rsc/server.rsc.ts400-450 docs/how-to/middleware.md1-100

Single Fetch Integration

RSC uses a modified version of the single fetch protocol:

Feature	Standard	RSC
URL pattern	path.data	path.rsc
Response type	text/x-script	text/x-component
Encoding	Turbo-stream	React Flight
Actions	Form encoding	encodeReply()
Server functions	Not supported	Supported via callServer

Shared Concepts:

• _routes parameter for selective loader execution
• Route-level revalidation control via shouldRevalidate
• Error propagation through route hierarchy
• Support for data() response helper

Sources: packages/react-router/lib/rsc/browser.tsx500-600 packages/react-router/lib/dom/ssr/single-fetch.tsx612-649

Configuration and Setup

Route Configuration

RSC routes use RSCRouteConfigEntry type:

Key Configuration Points:

• Component: Server component (default export from route module)
• lazy: Dynamic import for code splitting
• clientAction/clientLoader: Client-side overrides (if needed)
• ErrorBoundary: Must be client component (marked with "use client")

Sources: packages/react-router/lib/rsc/server.rsc.ts159-198

Required Bundler Integration

RSC requires bundler-specific implementations:

Function	Location	Purpose
createFromReadableStream	Bundler-specific	Decode RSC payloads
encodeReply	Bundler-specific	Serialize server action args
createTemporaryReferenceSet	Bundler-specific	Track references during encoding
decodeReply	Server-side	Deserialize action arguments

Example Integration:

Sources: packages/react-router/lib/rsc/server.ssr.tsx36-100 integration/helpers/rsc-vite/src/entry.ssr.tsx1-50