Supporting React Server Components in Vite

[jplhomer]

UPDATE (June 2023) - please see the comment below: #4591 (comment)

---

This is a discussion and a placeholder of sorts to track support for React Server Components in Vite.

I'm a developer at Shopify, and we're building Hydrogen, a new React framework powered by Vite along with a set of useful commerce components to use in other frameworks.

Hydrogen is powered by a home-grown version of React Server Components, but we're working with the React core team to create an official version that supports Vite (and Rollup-style dev tools).

Developers at Shopify are putting in the work to make this a reality 🎉 but we're also happy to welcome community contributions!

Below is a list of TODOs along with some background context.

TODO

• Implement ReactFlightWebpackPlugin for Vite
• Implement ReactFlightWebpackNodeLoader for Vite
• Implement ReactFlightClientWebpackBundlerConfig for Vite

Each of these implementations will live upstream in facebook/react and will be contributed via PRs.

Implement ReactFlightWebpackPlugin for Vite

Webpack implementation: https://github.com/facebook/react/blob/c6f2188ed6e8d44c73e61aa1ebfd10c9e066d5b3/packages/react-server-dom-webpack/src/ReactFlightClientWebpackPlugin.js

This plugin is responsible for finding all Client Components in the project and assembling a manifest to be used by the "flight runtime." Additionally, this plugin should instruct the bundler that these client components exist and are dependents of the client "flight runtime," as if they were each going to be dynamic import() (which actually happens in the flight runtime). This ensures that the same chunks are shared between multiple dependents.

This behavior is critical when it comes to building client components that depend on Context. Otherwise, Context mismatches lead to bugs in the code and the inability for components to communicate with one another.

To make this work, the clearest path is to rely on Rollup's emitFile function. We can easily search for all components in a project matching /\.client\.(t|s)x$/, emit a chunk for each one, and mark the flight runtime module as implicitlyLoadedAfterOneOf for each chunk.

Progress and blockers

• This is working in Hydrogen for vite build which has access to this.emitFile()
• vite dev mode does NOT provide access to this.emitFile(), so we need to find a workaround.

Our biggest blocker is with the fact that Vite tends to optimize dependencies in dev mode, which often leads to duplicated chunks/modules. We're forced to load the raw file path of the client components in the flight runtime, because we can't generate a manifest of chunks to reference.

Behind the scenes, Vite prevents this hook from being used because it straight-up doesn't use Rollup in dev mode. This makes sense!

Ideas for workarounds:

• See this comment: Supporting React Server Components in Vite #4591 (comment)
• Update Vite to support this.emitFile in dev mode, which ends up bundling the chunk that is referenced. Leverage existing esbuild bundle behavior used for optimizeDeps, create an in-memory manifest, and reference those chunks when performing dynamic imports of client components in the flight runtime.
• Hook into a pre hook and manually add all client components in the project to the list of optimizeDeps.include, forcing Vite to bundle all of them, and then use those when dynamically importing on the client.

Implement ReactFlightWebpackNodeLoader for Vite

Webpack implementation: https://github.com/facebook/react/blob/c6f2188ed6e8d44c73e61aa1ebfd10c9e066d5b3/packages/react-server-dom-webpack/src/ReactFlightClientNodeLoader.js

While the official server components demo resolves to a separate CJS Webpack implementation, the React team has also created an ESM version of the loader (linked above).

This loader is responsible for transforming Client Components into Proxy modules.

When a server component tree is being streamed to the client, the flight runtime on the server "renders" the tree in a JSON-ish syntax consisting of nested tuples representing the application. The tuples are created based on component types:

• Server components are "rendered" to HTML and are represented by their output, e.g. the component types are p and div
• Client components, which exist as Proxy objects thanks to this plugin, are represented by modules like @1 and @2 which are referenced in the same JSON payload. These references contain information for the client flight runtime to perform dynamic imports. This information comes from the previous plugin.

Progress and blockers

Ideally, we could just re-use the existing ESM Node loader that the React team has created! However, I do not understand the API. Maybe it's geared toward being a Babel-compatible plugin?

• Either repurpose the existing ESM loader to make work with Vite
• ...or build a new loader which is more geared toward Rollup/Vite's transform hook

Implement ReactFlightClientWebpackBundlerConfig for Vite

Webpack implementation: https://github.com/facebook/react/blob/c6f2188ed6e8d44c73e61aa1ebfd10c9e066d5b3/packages/react-server-dom-webpack/src/ReactFlightClientWebpackBundlerConfig.js

This plugin is responsible for taking the JSON-ish tuple syntax created in the previous step, and parsing it on the client. Thankfully, most of the complexity is abstracted away into the flight client runtime, so the only thing we need to customize is the bundler config.

Specifically, we need to come up with Vite-comparable methods for __webpack_chunk_load__(chunkId) and __webpack_require__(moduleData.id).

Progress and blockers

• Use simple dynamic import() to load chunks
• Find a way to perform the equivalent of a synchronous require() to load modules. Currently, React expects a synchronous function (aka async/await is not supported). We either need to find a synchronous solution in a modern/Vite world, or use import() and modify the function expectations upstream in React core.

About React Server Components

Announced in December 2020, React Server Components are the way the React core team plans to build better support for server + client interactions in modern React applications.

I highly encourage you to watch the video and check out the server components demo.

RSC is really meant to be implemented and abstracted by meta-frameworks like Next.js and Hydrogen instead of by the end-user. By providing drop-in plugins for Vite and other rollup-compat tools, we open the door to lots more modern development workflows.

The biggest benefits the Hydrogen team sees of using React Server Components:

• Clear separation of concerns between server and client components. We can isolate and enforce certain 3rd party API calls to happen on the server in a safe manner.
• Performance. We don't need to load all of the dependencies that are only used on the server, just those used in client components. This leads to lighter bundle sizes.

React Server Components is still in an experimental stage and is not yet stable, but Hydrogen is buying into this pattern and plans to help push it forward.

[jplhomer]

Implement ReactFlightWebpackPlugin for Vite

@yyx990803 recently suggested a solution for this, and this is my attempt to distill it into writing:

Rather than rely on emitFile to build a dependency graph for Server > Client components, Evan suggested using a virtual file import in our client entrypoint (e.g. entry-client.jsx). This virtual file would resolve to what would be the equivalent of dynamic import() of all the client components that might be loaded on the page:

// entry-client.jsx

import 'hydrogen:client-components'

Which resolves to:

import '/some/path/to/A.client.js';
import '/some/path/to/B.client.js';
...

This can happen during the resolveId and load hooks.

This informs Vite's module graph about all the interconnected client component dependencies, and ideally it prevents any unnecessary or duplicate chunks from being generated.

A couple follow-up questions (Evan if you're listening...)

• Can we inject this import dynamically at the top of the entrypoint during e.g. transform? So we don't have to add a hardcode reference? (this is more of a nice-to-have)
• We probably shouldn't actually be loading all of those module in the virtual file, right? Just building the graph as such, so that they can be dynamically imported later. What would be the best way to "strip" out the imports before they get added to the bundle? Would be clean up in a post transform hook?

[jplhomer]

Update: From the React core team, expectation-setting regarding trying to match parity with Webpack versions of RSC:

There’s nothing wrong to do these tasks but I just want to set expectations. Before a final stable version of Server Components, we’ll be rewriting the Webpack plugins and the mechanisms. What is there now is just the fastest we could get something out but it has a lot of flaws in terms of how the packaging works. So don’t consider it the end state to follow but rather a first demo.
So an expectation of a Vite implementation should be that the architecture likely has to change (maybe a few times).

The main thing is that by default you end up with way too many small chunks. You could use a telemetry based heuristic to inform bundling but without it, we think the best guidance is to analyze the server component's graph to group client components together by which server components use them.

We expect that the server will need to be built too, as a separate graph since best perf is gained when you prebuild the server anyway.

So it might be that the best API is building the server first and then using the data from that as input to building the client.

I feel OK with continuing to reach the capabilities I've outlined above with this expectation in mind. We'll do our best to be ahead of the curve and ready to implement further optimizations that the React team finds when iterating on the Webpack version.

[jplhomer]

Turns out that @threepointone has already put together a prototype of RSC in an esbuild environment: https://github.com/threepointone/server-components-demo/tree/esbuild-take-2

A couple great takeaways:

• https://github.com/threepointone/server-components-demo/blob/esbuild-take-2/src/Html.js#L31-L39 is a super smart shim to be able to use react-server-dom-webpack's client loader. Build a Map, populate it asynchronously, and pull from it synchronously. We should do this in the interim.
• https://github.com/threepointone/server-components-demo/blob/esbuild-take-2/scripts/build.js#L23-L51 Very simple way to build a manifest. You still have the "many chunk" problem, but I'm encouraged that this works.
• https://github.com/threepointone/server-components-demo/blob/esbuild-take-2/scripts/build.js#L122-L150 Essentially mimicking ReactFlightWebpackNodeLoader. We should even see if we can implement this shim in Hydrogen first — it would allow us to get rid of quite a bit of reverse-engineered code (ClientMarker, etc)

[gabemeola]

Hey @jplhomer, curious if this ended up landing in Vite? (or rollup)

Update: Ah if this is right, it looks like it's pending on facebook/react#22952

[jplhomer]

👍 since Hydrogen is moving away from RSC (for the time being), @frandiox has offered to keep a fork here and accept contributions to bring it up to the latest spec https://github.com/frandiox/react/tree/rsc-vite

[patak-dev]

For reference to others reaching this issue, @nksaraf is working on a new PR to add a vite integration for React server components:

• add react-server-dom-vite impl and fixture facebook/react#26926

[ocodista]

This is closed