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.

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.

#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.

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.

See the Rsbuild SSR HTML example.

#Good to know

  • rsbuild preview only serves the client output. Use node .output/server/index.mjs (or the preview command printed after the build) to preview the full build.
  • rsbuild build --watch is not supported yet.
  • 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 first client environment is used.

Nitro  builds full-stack servers that deploy anywhere.