\n\nReact Router Framework Mode for Rsbuild.\n\n## Features\n\n- 🚀 Zero-config setup with sensible defaults\n- 🔄 Automatic route generation from file system\n- 🖥️ Server-Side Rendering (SSR) support\n- 📱 Client-side navigation with SPA mode (`ssr: false`)\n- 📄 Static prerendering for hybrid static/dynamic sites\n- 🛠️ TypeScript support out of the box\n- 🔧 Customizable configuration\n- 🎯 Support for route-level code splitting\n- ☁️ Cloudflare Workers deployment support\n- 🔗 Module Federation support (experimental)\n\n## Framework Mode\n\nThe plugin lets an Rsbuild application use the standard React Router Framework\nMode conventions:\n\n- `react-router.config.*` for application configuration\n- `app/routes.ts` and `@react-router/dev/routes` for route configuration\n- Route Module exports such as `loader`, `action`, `meta`, `links`, and\n `shouldRevalidate`\n- generated `./+types/*` types\n- standard `entry.client` and `entry.server` entrypoints\n\nSome React Router build-tool integrations are not supported 1:1. See the\nconfiguration and examples below for the currently supported behavior.\n\n## Installation\n\n```bash\nnpm install rsbuild-plugin-react-router\n# or\nyarn add rsbuild-plugin-react-router\n# or\npnpm add rsbuild-plugin-react-router\n```\n\n## Usage\n\nAdd the plugin to your `rsbuild.config.ts`:\n\n```ts\nimport { defineConfig } from '@rsbuild/core';\nimport { pluginReact } from '@rsbuild/plugin-react';\nimport { pluginReactRouter } from 'rsbuild-plugin-react-router';\n\nexport default defineConfig({\n plugins: [\n pluginReactRouter({\n // options here\n }),\n pluginReact(),\n ],\n});\n```\n\nContinue using the standard React Router Framework Mode project structure:\n\n```text\napp/\n root.tsx\n routes.ts\n routes/\nreact-router.config.ts\nrsbuild.config.ts\n```\n\n## Configuration\n\nThis plugin requires Rsbuild 2.2.8 or newer. Development hot data revalidation\nuses its custom-event connection API and no longer writes an HDR revision file.\n\nFor server-only changes, `rsbuild build --environment node` can reuse the\nfinalized browser manifest from a previous full build in the same project.\nKeep the browser output and build cache. Run a full build after changing routes\nor browser assets, or adding or removing a route's `loader` or `action` export.\nNode-only builds check the compiled exports against the cached manifest. If the\nmanifest is missing or incompatible, the build fails and asks for a full build.\n\nReact Router application settings live in `react-router.config.*`. The Rsbuild\nplugin only needs options for Rsbuild-specific behavior.\n\n### Plugin Options\n\n```ts\npluginReactRouter({\n typegen: true,\n customServer: false,\n lazyCompilation: true,\n unstableLazyCompilationPrewarm: false,\n logPerformance: false,\n federation: false,\n});\n```\n\n| Option | Default | Description |\n| -------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `typegen` | `true` | Generates React Router route types during development and builds. Set to `false` when type generation is managed separately. |\n| `customServer` | `false` | Disables the built-in development SSR middleware. Enable this when an app owns the server with `createDevServer()` or an adapter. |\n| `serverOutput` | Derived | Emitted Rsbuild server format: `'module'` or `'commonjs'`. When omitted, React Router's `serverModuleFormat` selects the format (`'esm'` -> `'module'`, `'cjs'` -> `'commonjs'`); setting `serverOutput` overrides it. |\n| `lazyCompilation` | `true` | Optional Rsbuild dev lazy-compilation config. When enabled here or through `dev.lazyCompilation`, React Router hydration-critical modules stay eager so the browser manifest and route modules are not replaced by lazy proxies. |\n| `unstableLazyCompilationPrewarm` | `false` | Experimental prewarm for emitted lazy-compilation proxy modules after dev compiles. Enable with `true` when route JS proxy startup should happen shortly after compiler readiness. |\n| `logPerformance` | `false` | Logs structured React Router plugin timing information. |\n| `parallelRouteTransform` | `undefined` | Controls worker-thread route transforms. `undefined` and `false` keep transforms inline, `true` uses an automatic worker count, and a positive integer sets the maximum worker count. |\n| `onRouteTopologyChange` | `undefined` | Notification for programmatic/custom dev servers. Recreate the Rsbuild server when route files are added, removed, or moved. The callback is not awaited. |\n| `federation` | `false` | Enables the plugin's experimental Module Federation integration. |\n\nWhen `federation` is enabled, configure the Module Federation plugin with\n`experiments.asyncStartup: true` on every compiler (the plugin enforces it) and\nkeep shared dependencies non-eager. The dev server resolves async server build\nexports automatically; production custom servers or adapters should resolve\nasync exports before passing the build to React Router's request handler\n(`resolveReactRouterServerBuild`). Give remote containers an explicit\n`filename` (for example `static/js/remote.js`); every other browser chunk keeps\nRsbuild's content hash. Under the hood the plugin gives each container its own\nruntime chunk (so importing a container does not start the app's own share\nconsumes), makes browser route-module entries async so their exports resolve\nthrough the async startup, and keeps server code splitting async-only so the\n`@module-federation/node` chunk loader can satisfy the server build's startup.\n\n### React Router Config\n\nPut React Router framework settings in `react-router.config.*`:\n\n```ts\nimport type { ReactRouterRsbuildConfig } from 'rsbuild-plugin-react-router';\n\nexport default {\n ssr: true,\n buildDirectory: 'build',\n appDirectory: 'app',\n basename: '/',\n splitRouteModules: true,\n subResourceIntegrity: false,\n} satisfies ReactRouterRsbuildConfig;\n```\n\nUse `ReactRouterRsbuildConfig` for Rsbuild projects so plugin-supported\nconfiguration such as `splitRouteModules` stays typed across React Router 7\nand 8 releases. The underlying route and config types come from\n`@react-router/dev`, which framework-mode apps already install for\n`routes.ts` helpers and typegen; it is declared as an optional peer\ndependency.\n\nCommonly used options:\n\n| Option | Default | Notes |\n| ---------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |\n| `ssr` | `true` | Set `false` for SPA mode. SPA mode still runs a build-time server render to create `build/client/index.html`. |\n| `buildDirectory` | `'build'` | Output root. Client assets go in `/client`; server output goes in `/server`. |\n| `appDirectory` | `'app'` | Directory containing `root`, `routes`, and optional `entry.client` / `entry.server` files. |\n| `basename` | `'/'` | Base URL used for routing, prerender requests, and manifest asset paths. |\n| `serverBuildFile` | `'index.js'` | Server build file name. It must end in `.js`. |\n| `serverModuleFormat` | `'esm'` | React Router server module format: `'esm'` or `'cjs'`. `serverOutput` can override the emitted Rsbuild server format. |\n| `serverBundles` | `undefined` | Advanced server bundle splitting by route branch. Disabled when `ssr: false`. |\n| `routeDiscovery` | React Router | Defaults to lazy discovery for SSR and initial discovery for SPA mode. `routeDiscovery.mode: 'lazy'` is invalid for SPA. |\n| `prerender` | `undefined` | `true`, an array of paths, a function, or `{ paths, concurrency }` / `{ paths, unstable_concurrency }`. |\n| `splitRouteModules` | `true` | Splits client route module exports. The legacy `future.v8_splitRouteModules` flag is also accepted. |\n| `subResourceIntegrity` | `false` | Emits SRI metadata for browser scripts. The legacy `future.unstable_subResourceIntegrity` flag is normalized to this key. |\n| `buildEnd` | `undefined` | Hook called after the build with the React Router build manifest and resolved config. |\n\n### Config File Resolution\n\nThe plugin will look for `react-router.config` with any supported JS/TS extension, in this order:\n\n- `react-router.config.tsx`\n- `react-router.config.ts`\n- `react-router.config.mts`\n- `react-router.config.jsx`\n- `react-router.config.js`\n- `react-router.config.mjs`\n\nIf none are found, it falls back to defaults.\n\n### FAQ\n\n#### rsbuild-plugin-react-router vs ModernJS\n\nThis plugin is a focused React Router Framework Mode adapter for Rsbuild. It\ndoes not aim to replace ModernJS or its higher-level framework features. If\nyour goal is a broader application framework or advanced microfrontend\nsupport, ModernJS may be a better fit.\n\n### SPA Mode (`ssr: false`)\n\nReact Router's SPA Mode still requires a build-time server render of the root route to generate a hydratable `index.html` (this is how this Rsbuild integration mirrors React Router framework behavior).\n\nWhen `ssr: false`:\n\n- The plugin builds both `web` and `node` internally.\n- It generates `build/client/index.html` by running the server build once (requesting `basename` with the `X-React-Router-SPA-Mode: yes` header). The server bundle is evaluated in a worker thread that is terminated afterwards, with `process.env.IS_RR_BUILD_REQUEST === 'yes'` set, so module-scope side effects in your root route's import graph run at build time but cannot keep `rsbuild build` alive. The same applies to prerendering.\n- It removes `build/server` after generating `index.html`, so the output is deployable as static assets.\n\n**Important:** In SPA mode, use `clientLoader` instead of `loader` for data loading since there's no server at runtime.\n\n### Static Prerendering\n\nFor static sites with multiple pages, you can prerender specific routes at build time:\n\n```ts\n// react-router.config.ts\nimport type { ReactRouterRsbuildConfig } from 'rsbuild-plugin-react-router';\n\nexport default {\n ssr: false,\n prerender: [\n '/',\n '/about',\n '/docs',\n '/docs/getting-started',\n '/docs/advanced',\n '/projects',\n ],\n} satisfies ReactRouterRsbuildConfig;\n```\n\nWhen `prerender` is specified:\n\n- Each path in the array is rendered at build time\n- Static HTML files are generated for each route (e.g., `/about` → `build/client/about/index.html`)\n- The server build is removed after prerendering for static deployment\n- Non-prerendered routes fall back to client-side routing\n\nYou can also use `prerender: true` to prerender all static routes automatically.\n\n`prerender` can also be a function:\n\n```ts\nexport default {\n ssr: false,\n prerender: ({ getStaticPaths }) =>\n getStaticPaths().filter(path => path !== '/admin'),\n} satisfies ReactRouterRsbuildConfig;\n```\n\nPrerendering defaults to one path at a time, matching React Router. Use\n`concurrency` for larger sites; `unstable_concurrency` is still accepted for\nolder configs:\n\n```ts\nexport default {\n ssr: false,\n prerender: {\n paths: ['/', '/about'],\n concurrency: 4,\n },\n} satisfies ReactRouterRsbuildConfig;\n```\n\nFor builds with 256+ routes, detailed file-size reporting is compacted to totals\nby default to avoid gzipping and printing thousands of assets. Set\n`performance.printFileSize` to an object to customize that output.\n\nRoute transform source maps are generated in development only. If you enable\nRsbuild source maps for faster local debugging, prefer a cheap JS map:\n`output.sourceMap: { js: 'cheap-module-source-map', css: false }`.\n\nLazy compilation prewarming is disabled by default. When enabled alongside\n`lazyCompilation`, the plugin fetches emitted browser entry and route JS assets,\nextracts activation keys from the generated lazy-compilation client calls, and\nPOSTs those keys to the configured lazy trigger endpoint after dev compiles. It\ndoes not request application routes or run route loaders. Because the key\nextraction depends on the generated client code shape, opt in with\n`unstableLazyCompilationPrewarm: true`.\n\nSubresource Integrity is disabled by default. Enable it with\n`subResourceIntegrity: true` in `react-router.config.*` when the deployed app\nshould emit integrity metadata for browser scripts. The legacy\n`future.unstable_subResourceIntegrity` flag is still accepted and is normalized\nto the stable option.\n\n### Route Configuration\n\nRoutes can be defined in `app/routes.ts` using the helper functions from `@react-router/dev/routes`:\n\n```ts\nimport {\n type RouteConfig,\n index,\n layout,\n prefix,\n route,\n} from '@react-router/dev/routes';\n\nexport default [\n // Index route for the home page\n index('routes/home.tsx'),\n\n // Regular route\n route('about', 'routes/about.tsx'),\n\n // Nested routes with a layout\n layout('routes/docs/layout.tsx', [\n index('routes/docs/index.tsx'),\n route('getting-started', 'routes/docs/getting-started.tsx'),\n route('advanced', 'routes/docs/advanced.tsx'),\n ]),\n\n // Routes with dynamic segments\n ...prefix('projects', [\n index('routes/projects/index.tsx'),\n layout('routes/projects/layout.tsx', [\n route(':projectId', 'routes/projects/project.tsx'),\n route(':projectId/edit', 'routes/projects/edit.tsx'),\n ]),\n ]),\n] satisfies RouteConfig;\n```\n\nThe plugin provides several helper functions for defining routes:\n\n- `index()` - Creates an index route\n- `route()` - Creates a regular route with a path\n- `layout()` - Creates a layout route with nested children\n- `prefix()` - Adds a URL prefix to a group of routes\n\n### Route Components\n\nRoute components support the following exports:\n\n#### Client-side Exports\n\n- `default` - The route component\n- `ErrorBoundary` - Error boundary component\n- `HydrateFallback` - Loading component during hydration\n- `Layout` - Layout component\n- `clientLoader` - Client-side data loading\n- `clientAction` - Client-side form actions\n- `clientMiddleware` - Client-side middleware\n- `handle` - Route handle\n- `links` - Prefetch links\n- `meta` - Route meta data\n- `shouldRevalidate` - Revalidation control\n\n#### Server-side Exports\n\n- `loader` - Server-side data loading\n- `action` - Server-side form actions\n- `middleware` - Server-side middleware\n- `headers` - HTTP headers\n\n### Client/Server-only Modules\n\n- Files ending in `.client.*` are treated as client-only. Their exports are\n stubbed to `undefined` in the server build, so they are safe to import from\n route components for browser-only behavior.\n- Files ending in `.server.*` are server-only. If they are imported by code\n compiled for the web environment, the build will fail with a clear error.\n Keep `.server` imports in server entrypoints or other server-only code.\n\n### Asset Prefix\n\nIf you configure `output.assetPrefix` in Rsbuild, the plugin uses that value\nfor the React Router browser manifest and server build `publicPath` so asset\nURLs resolve correctly when serving from a CDN or sub-path.\n\nThe web environment's own `output.assetPrefix` is passed through to the browser\ncompiler untouched, so `environments.web.output.assetPrefix: 'auto'` lets the\nbrowser runtime resolve async chunks and stylesheets relative to the loaded\nscript. The server build and browser manifest need an absolute prefix: they use\nthe web environment's prefix when it is usable and otherwise fall back to the\nroot `output.assetPrefix`. A common CDN setup is therefore:\n\n```ts\nexport default defineConfig({\n output: { assetPrefix: 'https://cdn.example.com/app/' }, // server-rendered URLs\n environments: {\n web: { output: { assetPrefix: 'auto' } }, // browser runtime resolves itself\n },\n});\n```\n\nThe plugin does not set `output.filename`, `chunkFilename`, or `publicPath`\nfor the web environment. Production browser entries use Rsbuild's default\ncontent-hashed filenames, and `output.filename`, `output.filenameHash`,\n`output.distPath`, and `tools.rspack` output settings you configure govern\nthe emitted files and the manifest URLs that reference them.\n\nSupported browser filename forms differ by mode:\n\n- **Classic mode** accepts any scheme, including `.mjs`/`.cjs` and query-hash\n names such as `[name].js?v=[contenthash:8]`; the browser manifest classifies\n emitted assets by pathname and keeps the full reference.\n- **RSC mode** requires every browser JavaScript asset to be named `*.js`\n (hashes are fine, e.g. `[contenthash:8]-[name].js`): rspack's RSC manifest\n only records `.js` files, so the build fails with a clear error for query\n hashes or other extensions.\n\n## Custom Server Setup\n\nThe plugin supports two ways to handle server-side rendering:\n\n1. **Default Server Setup**: By default, the plugin automatically sets up the necessary middleware for SSR.\n\n2. **Custom Server Setup**: For more control, you can disable the automatic middleware setup by enabling custom server mode:\n\n```ts\n// rsbuild.config.ts\nimport { defineConfig } from '@rsbuild/core';\nimport { pluginReactRouter } from 'rsbuild-plugin-react-router';\nimport { pluginReact } from '@rsbuild/plugin-react';\n\nexport default defineConfig(() => {\n return {\n plugins: [\n pluginReactRouter({\n customServer: true,\n onRouteTopologyChange() {\n console.warn('Route topology changed; restart the dev server.');\n process.exitCode = 75;\n setTimeout(() => process.exit(75), 0);\n },\n }),\n pluginReact(),\n ],\n };\n});\n```\n\nRsbuild's `reload-server` watcher is owned by the CLI and is not installed by\nthe programmatic `createDevServer()` API. The sample below therefore treats\nroute topology changes as a full process restart: do not call `startServer()`\nagain inside the same process or mount a second dev server on the same Express\napp. If you implement in-process replacement instead, route requests through\nreplaceable middleware and request-handler delegates, always `await` the active\nserver's `close()` before calling `createDevServer()` again, and do not launch\nconcurrent replacements.\n\nCreate one server entry point (`server.js`) and let it own the React Router\nrequest handler in both development and production. Only the build provider\nchanges between modes:\n\n```js\nimport { createRsbuild, loadConfig } from '@rsbuild/core';\nimport { createRequestHandler } from '@react-router/express';\nimport {\n loadReactRouterServerBuild,\n resolveReactRouterServerBuild,\n} from 'rsbuild-plugin-react-router';\nimport express from 'express';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst app = express();\nconst isDev = process.env.NODE_ENV !== 'production';\n\nasync function startServer() {\n let devServer;\n let build;\n\n if (isDev) {\n const config = await loadConfig();\n const rsbuild = await createRsbuild({\n rsbuildConfig: config.content,\n });\n const currentDevServer = await rsbuild.createDevServer();\n devServer = currentDevServer;\n app.use(currentDevServer.middlewares);\n build = () => loadReactRouterServerBuild(currentDevServer);\n } else {\n app.use(\n express.static(path.join(__dirname, 'build/client'), {\n index: false,\n })\n );\n build = await resolveReactRouterServerBuild(\n import('./build/server/static/js/app.js')\n );\n }\n\n app.use(\n createRequestHandler({\n build,\n mode: isDev ? 'development' : 'production',\n getLoadContext() {\n return {\n // Add custom loader/action context here.\n };\n },\n })\n );\n\n const port = Number.parseInt(process.env.PORT || '3000', 10);\n const server = app.listen(port, () => {\n const mode = isDev ? 'Development' : 'Production';\n console.log(`${mode} server is running on http://localhost:${port}`);\n devServer?.afterListen();\n });\n devServer?.connectWebSocket({ server });\n}\n\nstartServer().catch(console.error);\n```\n\n`loadReactRouterServerBuild` waits for a complete React Router development\ngeneration. During rebuilds it returns the last successfully evaluated server\nbuild, whose embedded manifest is paired with the selected web compilation.\nA failed or incomplete candidate does not replace that last-good pair. The\nbuilt-in development middleware uses the same path. Calling\n`devServer.environments.node.loadBundle()` directly bypasses this guarantee.\n\nWhen `serverBundles` is configured, pass its exact Rsbuild entry name as the\noptional second argument (for example, `bundle-a/index`). The default build\nand every configured bundle are\nevaluated and published as one generation; one failing bundle keeps the whole\nprevious generation active.\n\n### Sharing `createContext()` instances with a custom server\n\nReact Router middleware contexts are matched by identity, so a custom server's\n`getLoadContext` must use the same `createContext()` instance the routes import.\nWith a bundled server build that instance lives inside the build. Re-export it\nfrom `app/entry.server.tsx` and read it from `build.entry.module`:\n\n```ts\n// app/entry.server.tsx\nexport { valueContext } from './context';\n```\n\n```js\n// server.js\ngetLoadContext: async () => {\n const { valueContext } = (await build()).entry.module;\n return new RouterContextProvider([[valueContext, 'value']]);\n},\n```\n\nThis works in development through `loadReactRouterServerBuild` and in\nproduction through `resolveReactRouterServerBuild`.\n\n`resolveReactRouterServerBuild` accepts an imported production server module,\nnormalizes ESM and CommonJS namespace shapes, resolves supported asynchronous\nbuild exports, and validates the result before it reaches React Router.\n\nThis guarantee covers the eagerly evaluated server entry object and its\nembedded manifest. It does not snapshot deferred server chunks, make emitted\nclient assets immutable, or delay Rsbuild's WebSocket success notification.\nSame-path server or client chunks can change before the matching framework\ngeneration commits. Closing that publication gap requires a supported Rsbuild\ngraph-settled hook plus immutable or staged outputs.\n\nThen update your `package.json` scripts:\n\n```json\n{\n \"scripts\": {\n \"dev\": \"NODE_ENV=development NODE_OPTIONS=\\\"--experimental-vm-modules\\\" node server.js\",\n \"build\": \"rsbuild build\",\n \"start\": \"NODE_ENV=production node server.js\"\n }\n}\n```\n\n## Cloudflare Workers Deployment\n\nStart from the tested [Cloudflare example](./examples/cloudflare). It contains\nthe complete Rsbuild configuration, Worker entry, Wrangler configuration, and\ndeployment scripts. The example uses `customServer: true` so the Worker owns\nthe React Router request handler.\n\n## Development\n\nThe plugin automatically:\n\n- Runs type generation during development and build\n- Sets up development server with live reload\n- Handles route-based code splitting\n- Manages client and server builds\n\nFor local development, use Node 22 and the repository's pinned pnpm version:\n\n```bash\nnvm install\nnvm use\ncorepack enable\ncorepack prepare pnpm@9.15.3 --activate\n```\n\n### Benchmarking\n\nRun the focused local suite for plugin regression checks:\n\n```bash\npnpm bench\npnpm bench:smoke\npnpm bench:codspeed\n```\n\nSee the [benchmark guide](./benchmarks/README.md) for JSON output, pull-request\ncomparisons and comments, `BENCHMARK_PLUGIN_ROOT`, and optional CodSpeed\npublication.\n\n## Examples\n\nThe repository includes several examples demonstrating different use cases:\n\n| Example | Description | Port | Command |\n| ----------------------------------------------------------------------- | --------------------------------------- | ---- | ---------- |\n| [default-template](./examples/default-template) | Standard SSR setup with React Router | 3000 | `pnpm dev` |\n| [spa-mode](./examples/spa-mode) | Single Page Application (`ssr: false`) | 3001 | `pnpm dev` |\n| [prerender](./examples/prerender) | Static prerendering for multiple routes | 3002 | `pnpm dev` |\n| [custom-node-server](./examples/custom-node-server) | Custom Express server with SSR | 3003 | `pnpm dev` |\n| [cloudflare](./examples/cloudflare) | Cloudflare Workers deployment | 3004 | `pnpm dev` |\n| [client-only](./examples/client-only) | `.client` modules with SSR hydration | 3010 | `pnpm dev` |\n| [react-router-8](./examples/react-router-8) | React Router 8 framework-mode SSR | 3020 | `pnpm dev` |\n| [rsc-mode](./examples/rsc-mode) | Experimental RSC Framework Mode | 3021 | `pnpm dev` |\n| [epic-stack](./examples/epic-stack) | Full-featured Epic Stack example | 3005 | `pnpm dev` |\n| [federation/epic-stack](./examples/federation/epic-stack) | Module Federation host | 3006 | `pnpm dev` |\n| [federation/epic-stack-remote](./examples/federation/epic-stack-remote) | Module Federation remote | 3007 | `pnpm dev` |\n\nEach example has unique ports configured to allow running multiple examples simultaneously.\n\n### Running Examples\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the plugin\npnpm build\n\n# Run any example\ncd examples/default-template\npnpm dev\n```\n\n### Running E2E Tests\n\nEach example includes Playwright e2e tests:\n\n```bash\ncd examples/default-template\npnpm test:e2e\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}