RSC and Server Action bundle practice

[ahabhgk]

This article introduces the construction practices of RSC (React Server Components) and Server Action in React, including their concepts, rendering methods, bundling process in webpack, and how Turbopack bundles multiple environment modules in a module diagram.

A brief introduction to RSC

Before RSC, React only had Client Component, you can use the ability of Client in Client Component, including maintaining state useState, side effects useEffect, event handling, and various APIs of Client, rendering methods There are CSR and SSR, they are all rendering of Client Component.

With the launch of RSC in React, there are two components: Client Component and Server Component. Server Component can use its capabilities, including asynchronous and server-side APIs such as file systems and databases. There are also more rendering methods for Server Component.

• RSC: Server side server component rendering.
• SSR: Server side client component prerendering.
• CSR/Hydration: Client side client component rendering.

The result of Server Component rendering will be sent to Client Component for rendering in the form of a stream, so SSR is also a client of Server Component. SSR and RSC are decoupled. You can only use RSC without SSR.

Of course, Server Component does not necessarily need a Server, it can be rendered at build time like SSG, the rendering results are stored as static files, and may even be rendered by Worker, but the intention of React under RSC architecture is to combine Server.

Strongly recommend React official this RFC: React Server Component, written very clearly and comprehensively, of course, the integration part (framework integration, Router integration, Bundler integration, etc.) is written relatively simply, so this document elaborates on how to integrate with Bundler.

In addition to Server Component, React has also launched Server Action, which is still in the exploration stage and has no RFC. It is very convenient to use it to call the server API. It strongly depends on the Server, and the implementation is decoupled from the Server Component. When only using Client Component, Server Action can also be used.

Server Action will compile into an async function that calls the server endpoint during compilation, which means it is composable. You can use it as a queryFn of ReactQuery.

Bundling by webpack

The following code can be referred to: https://github.com/ahabhgk/react-flight/tree/60928e2445292ec405876112c409ec11ad6573e7

RSC

According to the RFC, RSC's requirements for bundlershave the following four points:

• Ability to recognize modules with "use client" and treat them as Client modules.
• Able to understand "react-server" exports in package.json.
• The ability to set code splitting points, the Client module introduced by the Server module ("use client") will be used as a potential code splitting point (Code Splitting)
  • Usually, in the Server environment, code splitting is not performed to load Client Component as early as possible without blocking rendering
  • In the Client environment, code splitting is performed to reduce the number of requests and code volume on the first screen.
• Can provide the ID of the Client module, export variable names (export), chunks and other metadata (manifest) of the ChunkGroup.

The first two points are relatively easy to understand. "use client" is the directive of the Client boundary. Within the boundary, the module introduced by the "use client" directive will be used as the Client module regardless of whether there is a "use client" directive. Outside the boundary, it defaults to the Server module, and the exported components of the Client module will be treated as Client Components. When bundling, we will parse the AST in a webpack loader to identify the "use client" directive.

"react-server" will introduce the corresponding file of the exports when resolving, some libraries that adapt to RSC need to specify the exports in package.json. When bundling, only need to add the resolve condition in module.rule[].resolve to achieve this.

The last two points mainly help React to load Client Components at runtime. But first, let's introduce the overall rendering process and the concept of Reference.

Rendering process

The Client module containing "use client" in the Server environment will not retain the original content, but will be replaced by Client References:

// src/ClientComp.js
"use client"
export function ClientComp() { return <div>...</div> }

will be replaced to:

import { createClientReference } from "plugin/runtime/server.js"
export let ClientComp = createClientReference("src/ClientComp.js#ClientComp")

When the Server renders the Server Component, the imported Client Component will actually be a Client Reference. The React runtime will get its exports, ChunkGroup chunks, module id and other metadata in the manifest through the path information on the Reference, and then generate the serialized JSX:

import { ClientComp } from "./ClientComp"
export async function App() { return <div><ClientComp /></div> }

0:"$L1"
// The render result of Client Reference, including some metadata, so react can find the export variable (an exported Client Component) by these metadata.
2:I{"id":"./src/ClientComp.js","chunks":["client0"],"name":"ClientComp","async":false}
1:["$","div",null,{"children":["$","$L2",null,{}]}]

When sent to the Client (including SSR) to render this Server Component result (serialized JSX), when encountering Client Reference, the Client module will be loaded through these metadata. First, React will load chunks by __webpack_chunk_load__(chunkId), and then run the corresponding module by __webpack_require__(moduleId), and finally get the exported client component for rendering.

RSC-only

Let's start with RSC-only, forget about SSR for now. We will have two compiler, onc for server environment (target: "node") and one for client environment (target: "web"), our application is also divided into two entries, client-entry.js and server-entry.js.

// src/client-entry.js
import { use } from "react";
import { createFromFetch } from "react-server-dom-webpack/client";
import ReactDOM from "react-dom/client";

const data = createFromFetch(
  fetch(location[0], { headers: { Accept: "text/x-component" } }),
  { callServer }
);
const Root = () => use(data);

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<Root />);

// src/server-entry.js
export { default as App } from "./App";
export { getServerAction } from "plugin/runtime/server";
export * as ReactServerDOMWebpackServer from "react-server-dom-webpack/server";
export * as React from "react";

client-entry.js will mount the Root component, but does not render the main App component, because App is a Server Component, which will be re-exported in server-entry.js, bundled as a library, introduced and rendered in server.js (server.js is a dev/prod server and will not be bundled by the server compiler), createFromFetch will send a network request to fetch the serialized JSX and render it on the client.

// server.js
app.get("/", async function (req, res, next) {
  if (req.accepts("text/html")) {
    next();
  } else if (req.accepts("text/x-component")) {
    const { App, ReactServerDOMWebpackServer, React } = await import(`./dist/server-entry.js?t=${+new Date()}`);
    const clientModulesManifest = await fs.promises.readFile(`./dist/client-modules.json`, "utf-8");
    // 渲染 Server Component
    const stream = ReactServerDOMWebpackServer.renderToPipeableStream(React.createElement(App), clientModulesManifest);
    res.set("Content-type", "text/x-component");
    stream.pipe(res);
  }
});

We assume our application's module graph is like this:

In the server compile, when compiling the ClientComp.js module, we will encounter "use client", we need a webpack loader to handle it, This Loader needs to parse AST to identify "use client" and collect all exports to replace it with Client Reference. There is no longer a connection to Child.js in Client Reference, so our server compile process ends, and then we enter the client compile, this is also conforms to the definition of "use client" as a boundary.

For the real Client module ClientComp.js, we will collect the paths of these dependencies in the server compile. In the client compile, we will use the AsyncDependenciesBlock as the code splitting point, and add these dependencies as the dependencies of the RSC client runtime (react-server-dom-webpack/client). Then we will have the following Module Graph:

At the same time, these dependencies' metadata will be collected in the client compile, such as the module id mentioned above, chunks in the ChunkGroup, export variable names, etc., to generate a corresponding client-side rendering manifest (client-modules.json) for rendering the Client Reference in the server.

CSS

We don't consider the runtime css-in-js solution here. Currently, the runtime css-in-js can only be used in the "use client" module (some buildtime css-in-js solutions, such as pandaCSS, can be used in Server Component). Here we only consider how to import a global style (import "./global.css") in Server Component.

If we introduce CSS in the Client module within the "use client" boundary, this part of CSS will be moved into the client compile together with the Client modules and go through the normal client compilation without any problem. However, if CSS is introduced from a Server module like App.js, this part of CSS will not enter the client compilation, and then problems will arise. Therefore, we also need a way to move this part of CSS into the client's compilation process.

Actually, it's quite simple. CSS modules can be understood as implicit "use client" modules. The only difference is that CSS modules don't need to be loaded asynchronously as code splitting points. Moreover, Server modules must be the parent modules of Client modules. The rendering of Server Components will precede that of Client Components. Therefore, CSS modules can directly serve as ModuleDependencies of react-server-dom-webpack/client and can be loaded on the first screen.

SSR

Next, let's add the Server-Side Rendering (SSR) feature. SSR is the pre-rendering of Client Components on the server side. All you need to do is add the Client Components to the server compile and bundle the output of the Client Components that can run in the server environment. However, there are currently two problems.

• During the server compile, when we compile ClientComp.js, the content will be replaced with Client Reference. Since there is no introduction of the sub-module Child.js, the server compile directly ends the construction of the module graph in the make stage. So how can we add the real ClientComp.js and its sub-modules to the module graph?
• After ClientComp.js is replaced with Client Reference, only the content has changed, and the unique identifier of the module remains unchanged. If we want to add the real ClientComp.js module to the module graph as well, how can we ensure that its identifier does not conflict with that of the Client Reference module?

For the first problem, we can construct a new virtual Entry module from the collected "use client" Client boundary modules during the finishMake hook. The content of this Entry is import(/* webpackMode: "eager" */ "ClientComp.js"). Here, using dynamic import can ensure that in the production environment, there will be no errors in the output caused by tree-shaking and module concatenation optimizations. Using webpackMode: "eager" ensures that it won't be code-split. After that, we call the addModuleTree method (which is also the underlying API used by the EntryPlugin when processing the entry in the normal config) to add this Entry module to the build queue and start the second round of make.

For the second problem, it can be achieved by using layer. Layer is an API provided by webpack that can divide the same module into multiple "clones" in the same compilation process. Different "clones" with different layer will have different identifiers. Layer can be configured through module.rule[].layer. The default layer of a module will inherit the layer of its issuer (the module that first imports it). In fact, the Client Component in SSR is also the client part of the Server Component. So we mark the original Server Component as the server layer, and mark the Client Component added by calling addModuleTree as the client layer. Then we can get the following Module Graph:

In order to render the Client Component during Server-Side Rendering (SSR), similarly, we also need to generate a corresponding manifest (client-modules-ssr.json) for SSR rendering.

HMR

The processing of Client Components is the same as that of Client-Side Rendering (CSR). Just insert the Hot Module Replacement (HMR) runtime and use react-refresh/babel to compile and insert the runtime into each Client module.

The processing of Server Components is a bit different. Since the Server Components are rendered through fetch requests and then using the results of those requests, the updates of Server Components, including those caused by code modifications in the development environment and those caused by event handling, route jumps, etc. in the production environment, only require refetching.

useEffect(() => {
  if (process.env.NODE_ENV === "development") {
    import(/* webpackMode: "eager" */ "webpack-hot-middleware/client").then((hotClient) => {
      hotClient.subscribe((payload) => {
        // After the dev-server detects changes in the Server module, it sends a "sc-refresh" event.
        if (payload.action === "sc-refresh") {
          console.log(`[HMR] server components refresh`);
          refresh(); // createFromFetch + use
        }
      });
    });
  }
}, []);

Server Action

Currently, there are three ways to define Server Action:

• If it appears in the Server module and "use server" is added at the function level, then this async function will be regarded as a Server Action.
• If it appears in a separate module which is imported by the Server module and "use server" is added at the top level of this module, then the async function exported by this module will be regarded as a Server Action.
• If it appears in a separate module which is imported by the Client module and "use server" is added at the top level of this module, then the async function exported by this module will be regarded as a Server Action.

The first two ways can be understood as being introduced by the server environment since they are either defined in the Server module itself or imported by the Server module. The third way, which is introduced by the Client module, can be understood as being introduced by the client environment. Based on this, Server Action can be divided into two types: from server and from client. The calling process and bundling methods of these two types of Server Action are also different.

Calling process of "from client" Server Action

Firstly, let's introduce the calling process of the Server Action of "from client".

Similar to "use client", the output of the module containing "use server" in the Client environment will not retain the original content but will be replaced with Server References instead.

// src/actions.js
"use server"
export async function handleSubmit() { ... }

will be replaced to:

import { createServerReference } from "react-server-dom-webpack/client"
import { callServer } from "./router"
// Since "src/actions.js#handleSubmit" contains a path and will be sent to the client side along with the client artifacts, it needs to be encrypted/hashed in the production environment. The real content should be found on the server side through decryption/lookup in a table or other means.
export let handleSubmit = createServerReference("src/actions.js#handleSubmit", callServer)
// createServerReference will return `async function(...args) { return callServer("src/actions.js#handleSubmit", args) }`

Therefore, when the handleSubmit function is called, the callServer will be invoked to make a fetch request to the server side.

// server.js
app.post("/", bodyParser.text(), async function (req, res) {
  const { ReactServerDOMWebpackServer, getServerAction } = await import(`./dist/server-entry.js?t=${+new Date()}`);
  const serverActionsManifest = await fs.promises.readFile(`./dist/server-actions.json`, "utf-8");
  const serverReference = req.get("rsc-action"); // get the id: "src/actions.js#handleSubmit"
  if (serverReference) {
    const action = getServerAction(serverReference, serverActionsManifest);
    const args = await ReactServerDOMWebpackServer.decodeReply(req.body);
    const actionResult = await action.apply(null, args);
    const stream = ReactServerDOMWebpackServer.renderToPipeableStream(actionResult);
    stream.pipe(res);
  }
});

When callServer is called, the id of the Server Reference will be passed to server.js through the rsc-action header field. In server.js, based on the manifest that records the metadata of Server Action, the real Server module (actions.js) will be found and loaded among the products of server compilation. Then, the corresponding async function will be retrieved according to the export name, and it will be called on the Server side and the result will be responded.

Bundling of "from client" Server Action

Similar to the handling of the bundling of Client Components in RSC, the webpack loader is used to replace the content of the "use server" module with Server References. The "use server" modules are collected, and a third round of "make" is carried out through addModuleTree, and then marked back to the server layer. Meanwhile, the metadata is collected to generate a manifest (server-actions.json), which includes the module id, the name of the exported variable, and the chunks in the ChunkGroup where it is located.

Taking client compile into account, the following Module Graph can be obtained:

Calling process of "from server" Server Action

Since this kind of Server Action is inherently in the server environment and is passed to the Client Component through props, when this kind of Server Action is called, React cannot obtain the called id in the Server Reference in a way similar to that of "from client". Instead, when rendering the RSC, this id has to be serialized along with the Server Component's JSX and then transmitted to the client side over the network.

import handleSubmit from "./handleSubmit"
export default async function App() {
  return <form action={handleSubmit}></form>
}

0:"$L1"
// The rendering of Server Action (from server) corresponds to this item. The id will be sent to the client side along with the RSC through network requests.
2:{"id":"src/handleSubmit.js#default","bound":null}
1:["$","form",null,{"action":"$F2"}]

When it is called, the id will be retrieved from the props of the rendered Client Component, and then a request will be sent to the server side via callServer. After that, the process will be the same as that of the "from client" case.

Bundling of "from server" Server Action

When bundling this kind of Server Action, it only needs to add some metadata, including the id and the export name, to the exports of the module through the webpack loader. When the RSC renders the props of the Client Component and encounters the Server Action, it will read this metadata and then render the corresponding serialized content.

// src/handleSubmit.js
"use server"
export default async function handleSubmit() { ... }

will be transform into something like this:

import { registerServerReference } from "react-server-dom-webpack/server"
export default async function handleSubmit() { ... }
// https://github.com/facebook/react/blob/9f4fbec5f7bb639be6dac438f9da5f032ae12c15/packages/react-server-dom-webpack/src/ReactFlightWebpackReferences.js#L76
// Object.defineProperties(handleSubmit, { $$typeof: { value: SERVER_REFERENCE }, $$id: { value: "src/handleSubmit.js#default" }, $$bound: { value: null } });
registerServerReference(handleSubmit, "src/handleSubmit.js", "default")

How to Bundling in One Compilation

Judging from the above compilation process of Webpack, it requires server compile and client compile to conduct two compilations for the server environment and the client environment respectively. So, is there a way to complete the bundling for different environments in just one compilation?

In fact, there is a similar implementation in Webpack: Worker. During compilation, it will switch from the web/node environment to the webworker environment. The core API is AsyncEntrypoint. Each new Worker() will correspondingly create an AsyncEntrypoint and attach the runtime modules required by the webworker environment. Its model is somewhat different from that of RSC, but theoretically, it is possible to use AsyncEntrypoint to achieve bundling of RSC in one compilation by webpack.

Next, let's see how Tobias achieved bundling of RSC in one compilation in Turbopack.

Switching Environments

In Turbopack, one of the core concepts is Context, which is divided into AssetContext and ChunkingContext. It can be understood as the underlying abstraction of Webpack configuration. AssetContext corresponds to some configurations in the make phase, while ChunkingContext corresponds to some configurations in the seal phase.

Different modules can have different AssetContexts. The AssetContext of modules can be changed through Transition. For example, JavaScript modules and CSS modules use different AssetContexts to implement different resolve logics, use different AssetContexts to generate modules of different layers, and modules belonging to different environments use different AssetContexts to generate products for different environments.

Different chunks can have different ChunkingContexts. Currently, they are divided into DevChunkingContext and BuildChunkingContext. For example, in development mode and production mode, different ChunkingContexts are used to implement different bundling strategies, insert different runtime codes, and control the paths of the products.

Turbopack changes the environmental information of modules by changing AssetContext. Then it calls chunk_group/evaluated_chunk_group, taking this module as the entry module to generate the entry chunk, and then generates ChunkGroup/Entrypoint. According to the environmental information of the entry module, products for different environments are thus generated (actually, it can also be seen from this that a significant difference between Turbopack and Webpack is that Turbopack is pull-based while Webpack is push-based, including the generation of Module Graph and Chunk Graph, as well as the implementation of incremental compilation).

In this way, Turbopack achieves the switching of environments and also meets the third condition for RSC bundling, serving as a code splitting point, that is, generating ChunkGroup from the client boundary module.

Manifest

The second condition for RSC bundling is the ability to provide sufficient metadata to enable the client side to request and load the Client Component based on the serialized JSX (Server Component render results). In the current development mode, Turbopack does not write these metadata into a separate manifest file. Instead, it uses a special module. It can be simply understood that this metadata is included in the generated Client Reference module (of course, this requires some changes to the way the React runtime reads this information). This is not only the case for the manifest required by RSC, but also for the manifest of entry chunks required for SSR rendering.

Bundling

Next, let's briefly go through the bundling process of Turbopack. We'll start from the following initial module graph (for the sake of easy understanding, there are some simplifications to the actual implementation).

Firstly, start bundling from server.js, which is the server-entry (since the environment can be switched, there is no need to bundle it as a library and re-export modules like App.js anymore). When bundling encounters hydrate.js, which is the client-entry and a dependency of the server-entry, this module serves as the entry for the client and performs operations like hydration. It belongs to the client environment, so we use Transition to switch this module to the client environment. Meanwhile, since it is the Entrypoint for the client and server.js needs all the script paths of this Entrypoint when handling the "/" request for the first-screen SSR rendering, we add a special module and generate the paths of these chunks when generating its code. And when generating the code for the Entrypoint, it should be attached with the runtime code required by the client side. We use evaluated_chunk_group to bundle this module and its dependencies as an Entrypoint.

"[next]/entry/app/hydrate.tsx (ecmascript, chunk group files, ssr)": (({ r: __turbopack_require__, f: __turbopack_require_context__, i: __turbopack_import__, s: __turbopack_esm__, v: __turbopack_export_value__, n: __turbopack_export_namespace__, c: __turbopack_cache__, l: __turbopack_load__, j: __turbopack_dynamic__, g: global, __dirname }) => (() => {

__turbopack_export_value__([
  "static/chunks/_5654f9._.js",
  "static/chunks/[next]_common_2185c6._.js",
  "static/chunks/[next]_entry_app_hydrate_tsx_b53fce._.js",
  "static/chunks/[turbopack]_dev_client_3861d9._.js",
]); // chunks

})()),

After that, continue with the compilation. When encountering ClientComp.js, after recognizing "use client" during parsing, start the Transition and switch to the compilation environment on the client side. Then add the "react-server" resolve condition, and generate the Client Reference module and relevant meta-information. Meanwhile, since ClientComp.js will serve as a code splitting point, we use chunk_group to bundle this module and its dependencies as a ChunkGroup.

"[next]/entry/app/server-to-client-ssr.tsx/(CLIENT_MODULE)/[project]/App.tsx (ecmascript, with chunking context scope)/(CLIENT_CHUNKS)/[project]/App.tsx (ecmascript, chunks) (ecmascript, rsc)": (({ r: __turbopack_require__, f: __turbopack_require_context__, i: __turbopack_import__, s: __turbopack_esm__, v: __turbopack_export_value__, n: __turbopack_export_namespace__, c: __turbopack_cache__, l: __turbopack_load__, j: __turbopack_dynamic__, g: global, __dirname, x: __turbopack_external_require__, k: __turbopack_refresh__ }) => (() => {

__turbopack_esm__({
    "default": ()=>__TURBOPACK__default__export__
});
var __next_module_proxy = __turbopack_import__("[project]/node_modules/next/dist/next/module-proxy.js (ecmascript, rsc)");

const __TURBOPACK__default__export__ = __next_module_proxy["createProxy"](JSON.stringify([
    "[project]/App.tsx (ecmascript)", // module id
    ["static/chunks/[next]_common_2185c6._.js"], // chunks
]));

})()),

Based on this, we obtain the following Module Graph:

Here is a more complete diagram that summarizes and compares the two compilation methods:

Advantages

There may be some advantages compared to two compilations. Because in the same compilation, more information about modules in other environments can be obtained, such as the used exports (usedExport), so that tree-shaking can be done on the unused exports. However, in the case of two compilations, since this information is lost (it may be possible to save this information through a manifest), in order to ensure that the used exports are not tree-shaked, tree-shaking should not be done on all exports (setUsedInUnknownWay).

Of course, not all scenarios are suitable for completing bundling in one compilation. For RSC, where some modules run on the server and some modules run on the client, and even in next.js there are some middleware modules that will run on the server, it is quite suitable. But for SSR, where basically all modules run both on the server and on the client, it is not so necessary.

[cordelia-sixth]

Very usefull article!! Thank you so much!!