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:
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():
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.templatecontains 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 thessrentry. - Full response: otherwise, the
ssrentry renders pages itself, and itsfetchmethod returns the fullResponse.
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 previewonly serves the client output. Usenode .output/server/index.mjs(or the preview command printed after the build) to preview the full build.rsbuild build --watchis 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
nitroenvironment. UsebuildPluginsfor server build plugins. - With an HTML template, only the
index.htmlpage of the first client environment is used.