Rsbuild Integration

Use Nitro as an Rsbuild plugin to add a server to your Rsbuild app (experimental).

Warning

The Rsbuild plugin is experimental. Its behavior may change in minor releases.

Nitro integrates with Rsbuild (v2.3+) as a plugin. It adds a full server to your Rsbuild app (API routes, server-side rendering, WebSockets) and builds client and server into a single .output/ directory that deploys with any deployment preset.

#Nitro as an Rsbuild plugin

Add the plugin to your Rsbuild config:

rsbuild.config.ts
import { defineConfig } from "@rsbuild/core";
import { nitro } from "nitro/rsbuild";

export default defineConfig({
  plugins: [nitro({ serverDir: "./" })],
});

With the plugin enabled, you use the Rsbuild CLI:

  • rsbuild dev: One dev server for both frontend and backend. Nitro routes are handled before the Rsbuild middlewares, so they take precedence over client assets. Other requests are served by Rsbuild first (compiled assets, the public directory and HTML pages), then by Nitro. Server code reloads when server files change, while client code keeps Rsbuild's hot module replacement.
  • rsbuild build: Builds the client into the Nitro public output, then the server with the configured preset. Hashed client assets (static/ by default) are served with immutable cache headers.
  • rsbuild preview: Serves the production build locally through Nitro, including static assets and WebSocket support.

Nitro options are passed to nitro() (or set in nitro.config.ts). The server is bundled with the rspack builder config, using the Rspack instance of Rsbuild.

In development, asset loads that Rsbuild cannot serve (a script, style or image request) respond with a 404, even when a catch-all route or the SSR renderer would answer them with a page.

The baseURL of Nitro is the base of the Rsbuild server (server.base): client pages and assets are served under it. When only server.base is set, it is used as the baseURL of Nitro.

#Environments

The plugin uses Rsbuild environments and adds a nitro environment, which builds the server. Every environment with output.target: "web" (the default web environment, unless you define environments) is a client environment, emitted to the public output. With several client environments, pages (the HTML template and the client assets of server-side rendering) are owned by the client environment, then web, then the first one defined.

Every other environment with output.target: "node" is a service: Nitro bundles its output with the server, and you call it with fetchRsbuildEnv():

routes/[...
import { defineHandler } from "nitro";
import { fetchRsbuildEnv } from "nitro/rsbuild/runtime";

export default defineHandler((event) => fetchRsbuildEnv("ssr", event.req));

The entry of a service exports a fetch method (as default.fetch or fetch). Services share the Nitro runtime of the server, so imports of nitro/* (such as nitro/runtime-config or nitro/storage) work in their code.

#Server-side rendering

Nitro detects a file named entry-server.(ts|js|tsx|jsx|mts|mjs) (in the project root, app/, src/, or the server directory) and adds an ssr environment for it, if you have not defined one.

  • HTML template: when the Rsbuild html.template contains an <!--ssr-outlet--> comment, Nitro renders pages from the HTML generated by Rsbuild (with the client scripts injected) and replaces the comment with the response of the ssr entry.
  • Full response: otherwise, the ssr entry renders pages itself, and its fetch method returns the full Response.
import { defineConfig } from "@rsbuild/core";
import { nitro } from "nitro/rsbuild";

export default defineConfig({
  source: { entry: { index: "./app/entry-client.ts" } },
  html: { template: "./index.html" },
  plugins: [nitro({ serverDir: "./" })],
});

In development, page requests (navigations to paths without a file extension) are rendered by Nitro instead of the client HTML of Rsbuild.

The HTML template is compiled into the server bundle (it can also use renderer template syntax), so no template is compiled at runtime, including on runtimes that disallow it such as Cloudflare Workers. In development, the server is rebuilt when the generated HTML changes.

#Client assets

An SSR entry rendering the whole document (without an HTML template) gets the script and style URLs of a client entry with getRsbuildClientAssets():

app/entry-server.ts
import { getRsbuildClientAssets } from "nitro/rsbuild/runtime";

export default {
  async fetch(req: Request) {
    const { js, css } = getRsbuildClientAssets("index");
    const head = [
      ...css.map((href) => `<link rel="stylesheet" href="${href}">`),
      ...js.map((src) => `<script defer src="${src}"></script>`),
    ].join("");
    const html = `<!doctype html><html><head>${head}</head><body>...</body></html>`;
    return new Response(html, { headers: { "content-type": "text/html" } });
  },
};

The assets are those of the client environment owning pages (see Environments), keyed by entry name (index by default).

See the Rsbuild SSR HTML example (HTML template) and the Rsbuild SSR with React example (full document, with getRsbuildClientAssets()).

#Good to know

  • rsbuild build --watch is not supported yet.
  • Presets running the development server in another runtime (such as cloudflare-module with workerd) are supported, including server environments.
  • The server is built with the Rspack config of Nitro: Rsbuild rules and transforms of other plugins apply to the client and service environments, not to the nitro environment. Use buildPlugins for server build plugins.
  • With an HTML template, only the index.html page of the client environment owning pages is used.

Nitro  builds full-stack servers that deploy anywhere.