#React Server Components

Server Components are a new type of Component that renders ahead of time, before bundling, in an environment separate from your client app or SSR server. Rspack v2.0.0 and later have built-in full support for Server Components.

#How to use

Rspack provides two solutions to support React Server Components:

• Using Rsbuild: Rsbuild provides out-of-the-box support for React Server Components, allowing you to quickly create a React Server Component project. See rsbuild-plugin-rsc for details.
• Manually Configuring Rspack: You can refer to this document to manually add configurations related to React Server Components.

#Example

The rspack-rsc-examples repository contains full examples of building React Server Component applications using Rspack.

#Install dependencies

npm install react react-dom react-server-dom-rspack

yarn add react react-dom react-server-dom-rspack

pnpm add react react-dom react-server-dom-rspack

bun add react react-dom react-server-dom-rspack

deno add npm:react npm:react-dom npm:react-server-dom-rspack

#Basic concepts

React Server Component artifacts require cooperative execution across both server and browser environments. To support this architecture, Rspack launches two Compiler instances to separately build the server and browser artifacts. The diagram below illustrates the overall build flow:

• Client Compiler (target: 'web'): Responsible for generating code that runs in the browser. It primarily bundles Client Components, as well as CSS and static resources required by the application, and handles the hydration logic for components.
• Server Compiler (target: 'node'): Responsible for generating code that runs on the server. It handles the pre-rendering of React Server Components, bundles the execution logic for Server Actions, and handles code related to Server-Side Rendering (SSR).

In the configuration file, this corresponds to two Compiler configurations:

export default [
  // Client Compiler: Builds browser-side resources
  {
    target: 'web',
    // ...client-specific config
  },
  // Server Compiler: Builds RSC Payload and Server Actions
  {
    target: 'node',
    // ...server-specific config
  },
];

#Configure plugin

Rspack supports React Server Components through a pair of coordinating plugins. You must call rsc.createPlugins() once to get ServerPlugin and ClientPlugin, then attach each to the corresponding Compiler:

import { experiments } from '@rspack/core';

const { createPlugins, Layers } = experiments.rsc;
const { ServerPlugin, ClientPlugin } = createPlugins();

export default [
  {
    // Client Compiler
    target: 'web',
    plugins: [new ClientPlugin()],
    // ...client-specific config
  },
  {
    // Server Compiler
    target: 'node',
    plugins: [new ServerPlugin()],
    // ...server-specific config
  },
];

These two plugins internally schedule the build processes of the Client Compiler and Server Compiler, establishing a communication mechanism to synchronize compilation state, module info, and generate the client reference manifest.

#Configuring build entries

You need to configure entries for the Client Compiler and Server Compiler respectively. There must be an entry in the Client Compiler with the exact same name as the one in the Server Compiler.

export default [
  {
    target: 'web',
    entry: {
      // A 'main' entry with the same name as the server entry must exist,
      // acting as the module graph root node for the client RSC runtime.
      main: { import: './src/entry.client.tsx' },
    },
  },
  {
    target: 'node',
    entry: {
      // The server entry name is 'main'
      main: { import: './src/entry.rsc.tsx' },
    },
  },
];

When the Server Compiler finds "use client" components, it delegates those modules to the Client Compiler. Because the client config can have multiple entries, the RSC plugin uses a same-name convention: the client entry that has the same name as a server entry is treated as the RSC runtime mount for that entry.

Discovered "use client" modules are injected into that matching entry’s module graph. If no client entry with the same name exists, the plugin reports an "RSC Client Entry Mismatch" diagnostic and client components will not load correctly in the browser.

#Configure layer

In the Server Compiler, Rspack uses layer to distinguish RSC from SSR. The RSC plugin uses these layer names:

• Layers.rsc ('react-server-components'): RSC environment. Only modules in this layer have "use client" turned into client references and "use server" registered as Server Actions.
• Layers.ssr ('server-side-rendering'): SSR environment. Use this to mark the SSR entry; if no modules are assigned to this layer, Rspack skips SSR output.

import path from 'node:path';

const ssrEntry = path.resolve(
  import.meta.dirname,
  'src/framework/entry.ssr.tsx',
);
const rscEntry = path.resolve(
  import.meta.dirname,
  'src/framework/entry.rsc.tsx',
);

export default [
  // ...
  {
    target: 'node',
    module: {
      rules: [
        { resource: ssrEntry, layer: Layers.ssr },
        {
          resource: rscEntry,
          layer: Layers.rsc,
          resolve: { conditionNames: ['react-server', '...'] },
        },
        {
          issuerLayer: Layers.rsc,
          exclude: ssrEntry,
          resolve: { conditionNames: ['react-server', '...'] },
        },
      ],
    },
    // ...
  },
];

#Server entry

"use server-entry" is a specific directive introduced by Rspack, designed primarily for framework developers. It is used to mark a Server Component as the logical entry point for a page or route.

When compiling a component with "use server-entry", Rspack generates the complete set of resources required to initialize the RSC application in the browser and records this information by mounting static properties directly onto the exported component:

• entryJsFiles: Bootstrap scripts. These correspond to the output of the build entry with the same name in the Client Compiler. They are responsible for initializing the React runtime and rendering flow on the browser side.
• entryCssFiles: Style resources. Rspack collects all CSS files depended upon by this Server Component and its descendant component tree.

'use server-entry';

import './Todos.css';
import { Dialog } from './Dialog';
import { TodoDetail } from './TodoDetail';
import { TodoCreate } from './TodoCreate';
import { TodoList } from './TodoList';

export async function Todos({ id }: { id?: number }) {
  // ...component logic
}

During the server runtime, you can directly access these static properties mounted on the component to construct HTML head resources:

import type { ServerEntry } from 'react-server-dom-rspack/server.node';

const { Todos } = await import('../Todos.tsx');
const serverEntry = Todos as ServerEntry<typeof Todos>;

const root = (
  <>
    {/* Read static properties from the component to inject CSS for the current route */}
    {serverEntry.entryCssFiles
      ? serverEntry.entryCssFiles.map((href) => (
          <link
            key={href}
            rel="stylesheet"
            href={href}
            precedence="default"
          ></link>
        ))
      : null}
    <Todos id={id} />
  </>
);

const response = await handleRequest({
  request,
  getRoot: () => root,
  // Read static properties from the component to use as bootstrap scripts
  bootstrapScripts: serverEntry.entryJsFiles,
  nonce,
});

#Configure JSX/TSX

Add builtin:swc-loader for .jsx / .tsx and enable rspackExperiments.reactServerComponents so Rspack parses and transforms RSC directives such as "use client", "use server", and "use server-entry".

const jsxRule = {
  test: /\.jsx$/,
  use: {
    loader: 'builtin:swc-loader',
    options: {
      jsc: {
        parser: {
          syntax: 'ecmascript',
          jsx: true,
        },
      },
    },
    rspackExperiments: {
      reactServerComponents: true,
    },
  },
  type: 'javascript/auto',
};

const tsxRule = {
  test: /\.tsx$/,
  use: {
    loader: 'builtin:swc-loader',
    options: {
      jsc: {
        parser: {
          syntax: 'typescript',
          tsx: true,
        },
      },
    },
    rspackExperiments: {
      reactServerComponents: true,
    },
  },
  type: 'javascript/auto',
};

export default [
  {
    target: 'web',
    module: {
      rules: [jsxRule, tsxRule],
    },
  },
  {
    target: 'node',
    module: {
      rules: [jsxRule, tsxRule],
    },
  },
];

The loader executes different transformation logic for "use client" and "use server" directives based on the layer to which the module belongs:

1. When the module belongs to Layers.rsc (Server Component environment), react-server-dom-rspack is invoked for transformation:

   • Modules with "use client" are transformed into Client References.
   • Modules with "use server" are registered as Server Actions, enabling them to respond to remote calls from the client.

2. When the module does not belong to Layers.rsc (e.g., client or SSR environments):

   • "use server": The module is transformed into a Server Reference.

The RSC plugin uses the loader’s directive info to tell client and server components apart, and uses it to inject client entries, collect Server Actions, and generate the RSC manifest.

#Dev server

The RSC architecture requires handling client and server builds, responding to RSC requests, and managing server component HMR. Consequently, Rspack's built-in Dev Server cannot meet these requirements. You need to implement a custom development server to provide the following core capabilities:

• Handling RSC Requests: Intercept and process RSC (or SSR) requests initiated by the client, invoke the render logic using artifacts generated by the Server Compiler, and return the serialized RSC Payload (or HTML stream).
• Server Runtime Management: Execute server build artifacts in an isolated context (such as Worker Threads or child processes) to ensure environment isolation. Additionally, ensure that when server code updates, the old instance is cleanly destroyed and restarted to execute the new code.
• Server Component HMR: Monitor build changes in server components and notify the browser via communication mechanisms like WebSocket. Upon receiving the signal, the browser should trigger a re-request for RSC to update the page content.

To support Server Component HMR, Rspack provides the onServerComponentChanges hook on ServerPlugin (it runs after a build when server component output has changed). In your custom dev server, use this callback to notify the browser (e.g. via WebSocket) so it can re-request RSC and refresh the page.

export default [
  // ...
  {
    target: 'node',
    plugins: [
      new ServerPlugin({
        onServerComponentChanges() {
          // Invoke a method on your custom server to notify the client to refresh
        },
      }),
    ],
  },
];