feat: add vite plugin for RSC

[ascorbic]

First draft of a Vite plugin to extract server component modules. Made with reference to simple-rsc and Devon Govett's notes on RSC. As it stands, this is not specific to Impala (or even React).

How it works

Background

Generally, sites that use SSR need to do two builds with Vite, one with --ssr set and one without. These builds are independent of each other, and are likely to have different config etc. As a convention, SSR builds usually expect the client build to already have been done, and they may reference the manifest.json or ssr-manifest.json, which are both generated during the client build.

Client builds

The client build happens first, and currently the only special thing that happens is that we ensure that any module that has "use client" is written to a chunk of its own. The manifest is written out, which we can read later to find that chunk filename.

SSR build

The SSR build happens after the client build. To be clear, this does not refer to the actual SSR rendering - this is building the code that is used to do SSR later.

During the build, we register a transform hook. Whenever a module is loaded, we check if it has the use client pragma. We do this in two stages. First we do a quick string check. If the string is found we do a proper parse of code, and then traverse the AST to ensure that it's relevant syntax and not just random text somewhere in the file.

If it matches, then we find the module in the manifest. That will allow us to map it to a filename. We then inspect the parsed module again to check for the names of exports.

When we have the module id, filename and names of exports, we can generate the bundle map. For export we generate an entry in the form:

{
         id: "module-name.js#default",
         chunks: [],
         name: "default",
         async: true,
}

This is persisted to JSON at the end of the build.

We then replace the module code that is returned with something like the following:

import DefaultExport from "file://path/to/client/module-name.js";
DefaultExport.$$typeof = Symbol.for("react.client.reference");
DefaultExport.$$id="module-name.js#default"; 
export default DefaultExport;

This will then be included in the SSR bundle instead of the client code.

To make it easier to find the module map later, we also register a virtual module which lets us import "virtual:client-bundle-map" in our server code and get the filename to the JSON.

[netlify]

✅ Deploy Preview for impala-preact-js canceled.

Name	Link
🔨 Latest commit	5f9e71a
🔍 Latest deploy log	https://app.netlify.com/sites/impala-preact-js/deploys/6429b8607ff8c500084ee0df

[netlify]

✅ Deploy Preview for impala-preact-ts canceled.

Name	Link
🔨 Latest commit	5f9e71a
🔍 Latest deploy log	https://app.netlify.com/sites/impala-preact-ts/deploys/6429b860ef81f20008922be3

[netlify]

✅ Deploy Preview for impala-react-js canceled.

Name	Link
🔨 Latest commit	5f9e71a
🔍 Latest deploy log	https://app.netlify.com/sites/impala-react-js/deploys/6429b8609e6ef70008ef4ece

[netlify]

✅ Deploy Preview for impala-react-ts canceled.

Name	Link
🔨 Latest commit	5f9e71a
🔍 Latest deploy log	https://app.netlify.com/sites/impala-react-ts/deploys/6429b860c2988000089dde67

[ascorbic]

The manifest.json is generated when building the client code, and maps module names to chunk filenames. e.g.

{
  "index.html": {
    "file": "assets/index-3cfb730f.js",
    "isEntry": true,
    "src": "index.html"
  },
  "src/assets/impala.png": {
    "file": "assets/impala-0936a6d6.png",
    "src": "src/assets/impala.png"
  },
  "src/components/button.tsx": {
    "file": "assets/button-8f2948fa.js",
    "isEntry": true,
    "src": "src/components/button.tsx"
  }
}

During SSR we load the manifest so we can use it to find client chunk names

[ascorbic]

If we find a client component while bundling for SSR, we first find the full path to the client code. We mark it as external so that the SSR build doesn't try to re-bundle the client code when we reference it below.

[ascorbic]

If we've found it in the client manifest then we have enough info to replace it with a client reference. First we need to know what the exports are, so we parse it to an AST and extract the named and default exports. We generate an id based on the module id and export name.

[ascorbic]

Add the reference to the bundle map. This will be used in the client (and in SSR) to map client references to filenames.

[ascorbic]

Replace the client module code with the React symbol reference.

[ascorbic]

If this is a client build, ensure that the client component is emitted in its own chunk, with export signatures retained so it can be imported manually in the client.

[ascorbic]

Write the bundle map out to a JSON file, so it can be loaded and sent to the browser and SSR

[ascorbic]

These are virtual modules that just provide the path to the module map JSON files. This lets the prerender script or server load the JSON file without needing to know the path. Instead it can import the module and get the filename.

[ascorbic]

Cache the config to use later

[ascorbic]

These are not read from the config because we need to know the value of the server dist during client build and vice versa. This does not set the value for the builds - it's just for reference so we can find the manifests.

[ascorbic]

Vite doesn't provide proper types for these

[gaearon]

Thanks for writing this up! A few first thoughts without looking at the code:

The client build happens first, and currently the only special thing that happens is that we ensure that any module that has "use client" is written to a chunk of its own. The manifest is written out, which we can read later to find that chunk filename.

• Are you able to "discover" 'use client' that were never imported from the client? You need to somehow know which entry points to consider since they initially don't exist in the client graph. Consider that these entry points could also be deep inside some npm dependency. There are two strategies for this:
  • Scan the entire filesystem looking for 'use client' files. This is what the webpack plugin in React repo currently does. It's pretty slow and not good.
  • "Discover" 'use client' files by trying to walk the RSC module system graph. Since you need to walk the RSC graph anyway to "shim" the 'use client' files, this gives you a list to visit later. But this requires a tight integration between the passes. I think it's how @unstubbable's webpack plugins work. This is better.

SSR build

I would call this RSC build — I think that's what you're describing. The "SSR build" might also be necessary as a separate thing, but SSR needs to render client components. By the point you do SSR, RSC has already executed. This is because the first load is RSC -> SSR -> DOM, next loads are RSC -> diff -> DOM.