bun-plugin-server-components

The official Bun plugin for server components.

Installation

bun add bun-plugin-server-components -d

Context

Server components are a new abstraction for building web applications. They look similar to standard React/JSX components, but render exclusively on the server. They differ from classic "client components" in a few ways:

1. They can be async.
2. Their implementation can run privileged code like database queries. Normally this would be unsafe, because the source code of client components are typically bundled and sent to the client, where they can be inspected and reverse-engineered. Server components are never sent to the client, so they can run privileged code safely.
3. They cannot contain stateful hooks like useState or useEffect.

Server components require a deep integration with the bundler to work. To understand why, we need a bit of background on how server components work.

How server components work

Imagine you have a server component that looks like this:

// index.tsx
import { Component } from "./Component";
export default async function HomePage() {
  return (
    <div>
      <Component />
    </div>
  );
}

This file imports a client component called Component.

// ./Component.tsx
"use client";

export function Component() {
  return <div>Hello world</div>;
}

To run this component we need to generate two builds.

Here the term "build" refers to a typical bundling step—the act of converting a set of entrypoints into a set of bundles.

1. The first is our "server component build". It contains all the code we need to render HomePage to a component tree. When an incoming Request comes in, we can use React's built-in tools to convert this tree into a "virtual DOM stream" that we can return as a Response.
2. The second is our "client build". It contains the bundled versions of all client components that were referenced by our server components.

The browser hits the server and gets back the "virtual DOM stream". The virtual DOM stream will contain references to client components, which will be loaded from the client bundle. React provides a built-in utility (createFromFetch)that accepts the VDOM stream, dynamically loads the necessary client components, and returns a renderable component.

import { createRoot } from "react-dom/client";
import { createFromFetch } from "react-server-dom-webpack/client.browser";

const stream = fetch("/", { headers: { Accept: "text/x-component" } });
const data = createFromFetch(stream);

const root = createRoot(document);
root.render(<App />);

Server-side rendering

One potentially confusing aspect of server components is that they "return" virtual DOM. From the perspective of a server component, client components are black boxes.

If we want to do server-side rendering, we need to render our server component to VDOM, then render the VDOM to plain HTML. These are two distinct steps. The second step requires a third build, we we'll call the "SSR build". Like the "client build", this build will bundle all the client components. Unlike the "client build", those bundles will be intended for consumption on the server; in bundler terms, the build's "target" will be"bun" (or perhaps "node").

Bundling server components

That's a high-level overview of how server components work. The important takeaway is that we need to generate totally separate bundles for server and client components.

But it's not just a simple matter of running two separate bundling scripts. The true "entrypoints" of our application are the server components. Over the course of bundling our server components, we will discover some files containing the "use client" directive; these files then become the entrypoints for our "client build", which will require a totally separate build configuration from the server build.

The goal of this plugin is to hide the complexty of this multi-stage build from the user.

Usage

To use this plugin:

import ServerComponentsPlugin from "bun-plugin-server-components";

await Bun.build({
  entrypoints: ["./index.tsx"], // server component files
  plugins: [
    ServerComponentsPlugin({
      // plugin configuration
    }),
  ],
  // other configuration
});

The "entrypoints" you pass into Bun.build() should be your server components. Bun's bundler will automatically detect any files containing the "use client" directive, and will use those files as entrypoints for the "client build" and "SSR build". The bundler configuration for these builds can be provided client and ssr keys respectively.

import ServerComponentsPlugin from "bun-plugin-server-components";

await Bun.build({
  entrypoints: ["./index.tsx"], // server component files
  outdir: "./build",
  manifest: true,
  plugins: [ServerComponentsPlugin({
    client: {
      entrypoints: [], // optional - additional client entrypoints
      outdir: "./build/client", // default: inherits from the main build
      target: "browser",
      plugins: [/* */],
    }
    ssr: {
      entrypoints: [], // optional - additional SSR entrypoints
      outdir: "./build/client", // default: inherits from the main build
      target: "bun", // this is default
      plugins: [/* */],
    }
  })],
});

The result of Bun.build() will contain additional manifests for the SSR and client builds.

const result = await Bun.build({
  // config
  plugins: [
    ServerComponentsPlugin({
      /* config */
    }),
  ],
});

// standard manifest
// for the top-level (server components) build
result.manifest;

// manifest for client build
result.clientManifest;

// manifest for client build
result.ssrManifest;

Once the build is complete, you can use the manifests to implement your RSC server.