@vitejs/plugin-rsc

This package provides React Server Components (RSC) support for Vite.

Features

- Framework-agnostic: The plugin implements RSC bundler features and provides low level RSC runtime (react-server-dom) API without framework-specific abstractions.
- Runtime-agnostic: Built on Vite environment API and works with other runtimes (e.g., @cloudflare/vite-plugin).
- HMR support: Enables editing both client and server components without full page reloads.
- CSS support: CSS is automatically code-split both at client and server components and they are injected upon rendering.

Getting Started

You can create a starter project by:

``sh
npm create vite@latest -- --template rsc
`

Examples

Start here: ./examples/starter - Recommended for understanding the package

- Provides an in-depth overview of API with inline comments to explain how they function within RSC-powered React application.

Integration examples:

- ./examples/basic - Advanced RSC features and testing
- This is mainly used for e2e testing and includes various advanced RSC usages (e.g. "use cache" example).
- ./examples/ssg - Static site generation with MDX and client components for interactivity.
- ./examples/react-router - React Router RSC integration
- Demonstrates how to integrate experimental React Router RSC API. React Router now provides official RSC support, so it's recommended to follow React Router's official documentation for the latest integration.

Basic Concepts

This example is a simplified version of ./examples/starter. You can read ./examples/starter/src/framework/entry.{rsc,ssr,browser}.tsx for more in-depth commentary, which includes server function handling and client-side RSC re-fetching/re-rendering.

This is the diagram to show the basic flow of RSC rendering process. See also https://github.com/hi-ogawa/vite-plugins/discussions/606.

`mermaid
graph TD

subgraph "rsc environment"
A["React virtual dom tree"] --> |"[@vitejs/plugin-rsc/rsc]
renderToReadableStream"| B1["RSC Stream"];
end

B1 --> B2
B1 --> B3

subgraph "ssr environment"
B2["RSC Stream"] --> |"[@vitejs/plugin-rsc/ssr]
createFromReadableStream"| C1["React virtual dom tree"];
C1 --> |"[react-dom/server]
SSR"| E["HTML String/Stream"];
end

subgraph "client environment"
B3["RSC Stream"] --> |"[@vitejs/plugin-rsc/browser]
createFromReadableStream"| C2["React virtual dom tree"];
C2 --> |"[react-dom/client]
CSR: mount, hydration"| D["DOM Elements"];
end

style A fill:#D6EAF8,stroke:#333,stroke-width:2px
style B1 fill:#FEF9E7,stroke:#333,stroke-width:2px
style B2 fill:#FEF9E7,stroke:#333,stroke-width:2px
style B3 fill:#FEF9E7,stroke:#333,stroke-width:2px
style C1 fill:#D6EAF8,stroke:#333,stroke-width:2px
style C2 fill:#D6EAF8,stroke:#333,stroke-width:2px
style D fill:#D5F5E3,stroke:#333,stroke-width:2px
style E fill:#FADBD8,stroke:#333,stroke-width:2px
`

- vite.config.ts

`js
import rsc from '@vitejs/plugin-rsc'
import { defineConfig } from 'vite'

export default defineConfig({
plugins: [
// add plugin
rsc(),
],

// specify entry point for each environment.
environments: {
// rsc environment loads modules with react-server condition.
// this environment is responsible for:
// - RSC stream serialization (React VDOM -> RSC stream)
// - server functions handling
rsc: {
build: {
rollupOptions: {
input: {
index: './src/framework/entry.rsc.tsx',
},
},
},
},

// ssr environment loads modules without react-server condition.
// this environment is responsible for:
// - RSC stream deserialization (RSC stream -> React VDOM)
// - traditional SSR (React VDOM -> HTML string/stream)
ssr: {
build: {
rollupOptions: {
input: {
index: './src/framework/entry.ssr.tsx',
},
},
},
},

// client environment is used for hydration and client-side rendering
// this environment is responsible for:
// - RSC stream deserialization (RSC stream -> React VDOM)
// - traditional CSR (React VDOM -> Browser DOM tree mount/hydration)
// - refetch and re-render RSC
// - calling server functions
client: {
build: {
rollupOptions: {
input: {
index: './src/framework/entry.browser.tsx',
},
},
},
},
},
})
`

- entry.rsc.tsx

`tsx
import { renderToReadableStream } from '@vitejs/plugin-rsc/rsc'

// the plugin assumes rsc entry having default export of request handler
export default async function handler(request: Request): Promise {
// serialize React VDOM to RSC stream
const root = (




Test

// delegate to SSR environment for html rendering
// loadModule is a helper API provided by the plugin for multi environment interaction.
const ssrEntry = await import.meta.viteRsc.loadModule<
typeof import('./entry.ssr.tsx')
>('ssr', 'index')
const htmlStream = await ssrEntry.handleSsr(rscStream)

// respond html
return new Response(htmlStream, {
headers: {
'Content-type': 'text/html',
},
})
}

// add import.meta.hot.accept to handle server module change efficiently
if (import.meta.hot) {
import.meta.hot.accept()
}
`

- entry.ssr.tsx

`tsx
import { createFromReadableStream } from '@vitejs/plugin-rsc/ssr'
import { renderToReadableStream } from 'react-dom/server.edge'

export async function handleSsr(rscStream: ReadableStream) {
// deserialize RSC stream back to React VDOM
const root = await createFromReadableStream(rscStream)

// helper API to allow referencing browser entry content from SSR environment
const bootstrapScriptContent =
await import.meta.viteRsc.loadBootstrapScriptContent('index')

// render html (traditional SSR)
const htmlStream = renderToReadableStream(root, {
bootstrapScriptContent,
})

return htmlStream
}
`

- entry.browser.tsx

`tsx
import { createFromReadableStream } from '@vitejs/plugin-rsc/browser'
import { hydrateRoot } from 'react-dom/client'

async function main() {
// fetch and deserialize RSC stream back to React VDOM
const rscResponse = await fetch(window.location.href + '.rsc')
const root = await createFromReadableStream(rscResponse.body)

// hydration (traditional CSR)
hydrateRoot(document, root)
}

main()
`

Environment helper API

The plugin provides an additional helper for multi environment interaction.

$3

#### import.meta.viteRsc.loadModule

- Type: (environmentName: "ssr" | "rsc", entryName?: string) => Promise

This allows importing ssr environment module specified by environments.ssr.build.rollupOptions.input[entryName] inside rsc environment and vice versa. When entryName is omitted, the function automatically uses the single entry from the target environment's rollupOptions.input.

During development, by default, this API assumes both rsc and ssr environments execute under the main Vite process as RunnableDevEnvironment. Internally, loadModule uses the global __VITE_ENVIRONMENT_RUNNER_IMPORT__ function to import modules in the target environment (see __VITE_ENVIRONMENT_RUNNER_IMPORT__ below).

When enabling rsc({ loadModuleDevProxy: true }) plugin option, the loaded module is implemented as a proxy with fetch-based RPC to call in node environment on the main Vite process, which for example, allows rsc environment inside cloudflare workers to access ssr environment on the main Vite process. This proxy mechanism uses turbo-stream for serializing data types beyond JSON, with custom encoders/decoders to additionally support Request and Response instances.

During production build, this API will be rewritten into a static import of the specified entry of other environment build and the modules are executed inside the same runtime.

For example,

`js
// ./entry.rsc.tsx
const ssrModule = await import.meta.viteRsc.loadModule("ssr", "index");
ssrModule.renderHTML(...);

// ./entry.ssr.tsx (with environments.ssr.build.rollupOptions.input.index = "./entry.ssr.tsx")
export function renderHTML(...) {}
`

#### import.meta.viteRsc.import

- Type: (specifier: string, options: { environment: string }) => Promise

A more ergonomic alternative to loadModule:

1. No manual rollupOptions.input config needed - entries are auto-discovered
2. Specifier matches the path in typeof import(...) type annotations

Comparison:

`ts
// Before (loadModule) - requires vite.config.ts:
// environments.ssr.build.rollupOptions.input = { index: './entry.ssr.tsx' }
import.meta.viteRsc.loadModule('ssr', 'index')

// After (import) - no config needed, auto-discovered
import.meta.viteRsc.import(
'./entry.ssr.tsx',
{ environment: 'ssr' },
)
`

During development, this works the same as loadModule, using the __VITE_ENVIRONMENT_RUNNER_IMPORT__ function to import modules in the target environment.

During production build, the plugin auto-discovers these imports and emits them as entries in the target environment. A manifest file (__vite_rsc_env_imports_manifest.js) is generated to map module specifiers to their output filenames.

$3

#### import.meta.viteRsc.loadCss

> [!NOTE]
> The plugin automatically injects CSS for server components. See the CSS Support section for detailed information about automatic CSS injection.

- Type: (importer?: string) => React.ReactNode

This allows collecting css which is imported through a current server module and injecting them inside server components.

`tsx
import './test.css'
import dep from './dep.tsx'

export function ServerPage() {
// this will include css assets for "test.css"
// and any css transitively imported through "dep.tsx"
return (
<>
{import.meta.viteRsc.loadCss()}
...

)
}
`

When specifying loadCss(), it will collect css through the server module resolved by .

`tsx
// virtual:my-framework-helper
export function Assets() {
return <>
{import.meta.viteRsc.loadCss("/routes/home.tsx")}
{import.meta.viteRsc.loadCss("/routes/about.tsx")}
{...}

}

// user-app.tsx
import { Assets } from "virtual:my-framework-helper";

export function UserApp() {
return



...

}
`

$3

#### import.meta.viteRsc.loadBootstrapScriptContent("index")

This provides a raw js code to execute a browser entry file specified by environments.client.build.rollupOptions.input.index. This is intended to be used with React DOM SSR API, such as renderToReadableStream

`js
import { renderToReadableStream } from 'react-dom/server.edge'

const bootstrapScriptContent =
await import.meta.viteRsc.loadBootstrapScriptContent('index')
const htmlStream = await renderToReadableStream(reactNode, {
bootstrapScriptContent,
})
`

$3

#### rsc:update event

This event is fired when server modules are updated, which can be used to trigger re-fetching and re-rendering of RSC components on browser.

`js
import { createFromFetch } from '@vitejs/plugin-rsc/browser'

import.meta.hot.on('rsc:update', async () => {
// re-fetch RSC stream
const rscPayload = await createFromFetch(fetch(window.location.href + '.rsc'))
// re-render ...
})
`

$3

#### __VITE_ENVIRONMENT_RUNNER_IMPORT__

- Type: (environmentName: string, id: string) => Promise

This global function provides a standardized way to import a module in a given environment during development. It is used internally by import.meta.viteRsc.loadModule to execute modules in the target environment.

By default, the plugin sets this global to import via the environment's module runner:

`js
globalThis.__VITE_ENVIRONMENT_RUNNER_IMPORT__ = async (environmentName, id) => {
return server.environments[environmentName].runner.import(id)
}
`

Custom Environment Integration:

Frameworks with custom environment setups (e.g., environments running in separate workers or with custom module loading) can override this global to provide their own module import logic.

`js
// Custom logic to import module between multiple environments inside worker
globalThis.__VITE_ENVIRONMENT_RUNNER_IMPORT__ = async (environmentName, id) => {
return myWorkerRunners[environmentname].import(id)
}
`

This allows import.meta.viteRsc.loadModule to work seamlessly with different runtime configurations without requiring changes to user code.

Plugin API

$3

- Type: rsc: (options?: RscPluginOptions) => Plugin[];

`js
import rsc from '@vitejs/plugin-rsc'
import { defineConfig } from 'vite'

export default defineConfig({
plugins: [
rsc({
// this is only a shorthand of specifying each rollup input via
// environments[name].build.rollupOptions.input.index
entries: {
rsc: '...',
ssr: '...',
client: '...',
},

// by default, the plugin sets up middleware
// using default export of rsc environment index entry.
// this behavior can be customized by serverHandler option.
serverHandler: false,

// the plugin provides build-time validation of 'server-only' and 'client-only' imports.
// this is enabled by default. See the "server-only and client-only import" section below for details.
validateImports: true,

// by default, the plugin uses a build-time generated encryption key for
// "use server" closure argument binding.
// This can be overwritten by configuring defineEncryptionKey option,
// for example, to obtain a key through environment variable during runtime.
// cf. https://nextjs.org/docs/app/guides/data-security#overwriting-encryption-keys-advanced
defineEncryptionKey: 'process.env.MY_ENCRYPTION_KEY',

// when loadModuleDevProxy: true, import.meta.viteRsc.loadModule is implemented
// through fetch based RPC, which allows, for example, rsc environment inside
// cloudflare workers to communicate with node ssr environment on main Vite process.
loadModuleDevProxy: true,

// by default, loadCss() helper is injected based on certain heuristics.
// if it breaks, it can be opt-out or selectively applied based on files.
rscCssTransform: { filter: (id) => id.includes('/my-app/') },

// see RscPluginOptions for full options ...
}),
],
// the same options can be also specified via top-level rsc property.
// this allows other plugin to set options via config hook.
rsc: {
// ...
},
})
`

RSC runtime (react-server-dom) API

$3

This module re-exports RSC runtime API provided by react-server-dom/server.edge and react-server-dom/client.edge such as:

- renderToReadableStream: RSC serialization (React VDOM -> RSC stream)
- createFromReadableStream: RSC deserialization (RSC stream -> React VDOM). This is also available on rsc environment itself. For example, it allows saving serialized RSC and deserializing it for later use.
- decodeAction/decodeReply/decodeFormState/loadServerAction/createTemporaryReferenceSet
- encodeReply/createClientTemporaryReferenceSet

#### Vite-specific extension: renderToReadableStream (experimental)

> [!NOTE]
> This is a Vite-specific extension to the standard React RSC API. The official react-server-dom does not provide this callback mechanism.

renderToReadableStream API is extended with an optional third parameter with onClientReference callback.
This is invoked whenever a client reference is used in RSC stream rendering.

`ts
function renderToReadableStream(
data: T,
// standard options (e.g. temporaryReferences, onError, etc.)
options?: object,
// vite-specific options
extraOptions?: {
onClientReference?: (metadata: {
id: string
name: string
deps: { js: string[]; css: string[] }
}) => void
},
): ReadableStream
`

$3

This module re-exports RSC runtime API provided by react-server-dom/client.edge

- createFromReadableStream: RSC deserialization (RSC stream -> React VDOM)

$3

This module re-exports RSC runtime API provided by react-server-dom/client.browser

- createFromReadableStream: RSC deserialization (RSC stream -> React VDOM)
- createFromFetch: a robust way of createFromReadableStream((await fetch("...")).body)
- encodeReply/setServerCallback: server function related...

Tips

$3

The plugin automatically handles CSS code-splitting and injection for server components. This eliminates the need to manually call import.meta.viteRsc.loadCss() in most cases.

1. Component Detection: The plugin automatically detects server components by looking for:
- Function exports with capital letter names (e.g., export function Page() {})
- Default exports that are functions with capital names (e.g., export default function Page() {})
- Const exports assigned to functions with capital names (e.g., export const Page = () => {})

2. CSS Import Detection: For detected components, the plugin checks if the module imports any CSS files (.css, .scss, .sass, etc.)

3. Automatic Wrapping: When both conditions are met, the plugin wraps the component with a CSS injection wrapper:

`tsx
// Before transformation
import './styles.css'

export function Page() {
return

By default, @vitejs/plugin-rsc includes a vendored version of react-server-dom-webpack. When react-server-dom-webpack is installed in your project's dependencies, the plugin will automatically use it instead, allowing you to use any React version you need.

Canary or experimental versions:

`json
{
"dependencies": {
"react": "canary",
"react-dom": "canary",
"react-server-dom-webpack": "canary"
}
}
`

Specific versions (e.g., for security updates):

`json
{
"dependencies": {
"react": "19.2.3",
"react-dom": "19.2.3",
"react-server-dom-webpack": "19.2.3"
}
}
`

$3

By default, @vitejs/plugin-rsc is expected to be used as peerDependencies similar to react and react-dom. When @vitejs/plugin-rsc is not available at the project root (e.g., in node_modules/@vitejs/plugin-rsc), you will see warnings like:

`sh
Failed to resolve dependency: @vitejs/plugin-rsc/vendor/react-server-dom/client.browser, present in client 'optimizeDeps.include'
`

This can be fixed by updating optimizeDeps.include to reference @vitejs/plugin-rsc through your framework package. For example, you can add the following plugin:

`js
// package name is "my-rsc-framework"
export default function myRscFrameworkPlugin() {
return {
name: 'my-rsc-framework:config',
configEnvironment(_name, config) {
if (config.optimizeDeps?.include) {
config.optimizeDeps.include = config.optimizeDeps.include.map(
(entry) => {
if (entry.startsWith('@vitejs/plugin-rsc')) {
entry = my-rsc-framework > ${entry}
}
return entry
},
)
}
},
}
}
`

$3

Types for global API are defined in @vitejs/plugin-rsc/types. For example, you can add it to tsconfig.json to have types for import.meta.viteRsc APIs:

`json
{
"compilerOptions": {
"types": ["vite/client", "@vitejs/plugin-rsc/types"]
}
}
`

`ts
import.meta.viteRsc.loadModule
// ^^^^^^^^^^
// (environmentName: string, entryName?: string) => Promise
`

See also Vite documentation for vite/client types.

$3

You can use the server-only import to prevent accidentally importing server-only code into client bundles, which can expose sensitive server code in public static assets.
For example, the plugin will show an error 'server-only' cannot be imported in client build for the following code:

- server-utils.js

`tsx
import 'server-only'

export async function getData() {
const res = await fetch('https://internal-service.com/data', {
headers: {
authorization: process.env.API_KEY,
},
})
return res.json()
}
`

- client.js

`tsx
'use client'
import { getData } from './server-utils.js' // ❌ 'server-only' cannot be imported in client build
...
`

Similarly, the client-only import ensures browser-specific code isn't accidentally imported into server environments.
For example, the plugin will show an error 'client-only' cannot be imported in server build for the following code:

- client-utils.js

`tsx
import 'client-only'

export function getStorage(key) {
// This uses browser-only APIs
return window.localStorage.getItem(key)
}
`

- server.js

`tsx
import { getStorage } from './client-utils.js' // ❌ 'client-only' cannot be imported in server build

export function ServerComponent() {
const data = getStorage("settings")
...
}
`

Note that while there are official npm packages server-only and client-only created by React team, they don't need to be installed. The plugin internally overrides these imports and surfaces their runtime errors as build-time errors.

This build-time validation is enabled by default and can be disabled by setting validateImports: false` in the plugin options.

Architecture Documentation

For developers interested in the internal architecture:

- docs/architecture.md - Build pipeline, data flow, and key components
- docs/bundler-comparison.md - How different bundlers approach RSC

Credits

This project builds on fundamental techniques and insights from pioneering Vite RSC implementations.
Additionally, Parcel and React Router's work on standardizing the RSC bundler/app responsibility has guided this plugin's API design:

- Waku
- @lazarv/react-server
- @jacob-ebey/vite-react-server-dom
- React Router RSC
- Parcel RSC