rsbuild-plugin-react-router 0.1.1 → 0.3.0

package/README.md

@@ -8,7 +8,6 @@ A Rsbuild plugin that provides seamless integration with React Router, supportin
 
 ## Features
 
-
 - 🚀 Zero-config setup with sensible defaults
 - 🔄 Automatic route generation from file system
 - 🖥️ Server-Side Rendering (SSR) support
@@ -48,128 +47,86 @@ Add the plugin to your `rsbuild.config.ts`:
 
 ```ts
 import { defineConfig } from '@rsbuild/core';
-import { pluginReactRouter } from 'rsbuild-plugin-react-router';
 import { pluginReact } from '@rsbuild/plugin-react';
+import { pluginReactRouter } from 'rsbuild-plugin-react-router';
 
-export default defineConfig(() => {
-  return {
-    plugins: [
-      pluginReactRouter({
-        // Optional: Enable custom server mode
-        customServer: false,
-        // Optional: Specify server output format
-        serverOutput: "commonjs",
-        // Optional: enable experimental support for module federation
-        federation: false
-      }), 
-      pluginReact()
-    ],
-  };
+export default defineConfig({
+  plugins: [
+    pluginReactRouter({
+      // options here
+    }),
+    pluginReact(),
+  ],
 });
 ```
 
 ## Configuration
 
-The plugin uses a two-part configuration system:
+React Router application settings live in `react-router.config.*`. The Rsbuild
+plugin only needs options for Rsbuild-specific behavior.
+
+### Plugin Options
 
-1. **Plugin Options** (in `rsbuild.config.ts`):
 ```ts
 pluginReactRouter({
-  /**
-   * Whether to disable automatic middleware setup for custom server implementation.
-   * Enable this when you want to handle server setup manually.
-   * @default false
-   */
-  customServer?: boolean,
-
-  /**
-   * Specify the output format for server-side code.
-   * Options: "commonjs" | "module"
-   * @default "module"
-   */
-  serverOutput?: "commonjs" | "module"
-  /**
-   * Enable experimental support for module federation
-   * @default false
-   */
-  federation?: boolean
-})
-
-When Module Federation is enabled, configure your Federation plugin with
-`experiments.asyncStartup: true` to avoid requiring entrypoint `import()` hacks.
-See the Module Federation examples under `examples/federation`.
-
-When Module Federation is enabled, some runtimes may expose server build exports
-as async getters. The dev server resolves these exports automatically. For
-production, use a custom server or an adapter that resolves async exports before
-passing the build to React Router's request handler.
+  customServer: false,
+  serverOutput: 'module',
+  lazyCompilation: undefined,
+  logPerformance: false,
+  parallelRouteTransform: undefined,
+  onRouteTopologyChange: undefined,
+  federation: false,
+});
 ```
 
-2. **React Router Configuration** (in `react-router.config.*`):
+| Option                   | Default     | Description                                                                                                                                                                                                                      |
+| ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `customServer`           | `false`     | Disables the built-in development SSR middleware. Enable this when an app owns the server with `createDevServer()` or an adapter.                                                                                                |
+| `serverOutput`           | `'module'`  | Emitted Rsbuild server format: `'module'` or `'commonjs'`. When omitted, React Router's `serverModuleFormat` selects the format (`'esm'` -> `'module'`, `'cjs'` -> `'commonjs'`); setting `serverOutput` overrides it.           |
+| `lazyCompilation`        | `undefined` | 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. |
+| `logPerformance`         | `false`     | Logs structured React Router plugin timing information through the Rsbuild logger.                                                                                                                                               |
+| `parallelRouteTransform` | `undefined` | Controls worker-thread route transforms. `undefined` auto-enables workers for 256+ routes, `true` forces the default worker count, a positive integer sets the worker count, and `false` keeps transforms inline.                |
+| `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.                                                                        |
+| `federation`             | `false`     | Enables the plugin's experimental Module Federation integration.                                                                                                                                                                 |
+
+When `federation` is enabled, configure the Module Federation plugin with
+`experiments.asyncStartup: true`. The dev server resolves async server build
+exports automatically; production custom servers or adapters should resolve
+async exports before passing the build to React Router's request handler.
+
+### React Router Config
+
+Put React Router framework settings in `react-router.config.*`:
+
 ```ts
 import type { Config } from '@react-router/dev/config';
 
 export default {
-  /**
-   * Whether to enable Server-Side Rendering (SSR) support.
-   * @default true
-   */
   ssr: true,
-
-  /**
-   * The file name for the server build output.
-   * @default "index.js"
-   */
-  serverBuildFile: "index.js",
-
-  /**
-   * The output format for the server build.
-   * Options: "esm" | "cjs"
-   * @default "esm"
-   */
-  serverModuleFormat: "esm",
-
-  /**
-   * Split server bundles by route branch (advanced).
-   */
-  serverBundles: async ({ branch }) => branch[0]?.id ?? "main",
-
-  /**
-   * Hook called after the build completes.
-   */
-  buildEnd: async ({ buildManifest, reactRouterConfig }) => {
-    console.log(buildManifest, reactRouterConfig);
-  },
-
-  /**
-   * Build directory for output files
-   * @default 'build'
-   */
-  buildDirectory: 'dist',
-
-  /**
-   * Application source directory
-   * @default 'app'
-   */
+  buildDirectory: 'build',
   appDirectory: 'app',
-
-  /**
-   * Base URL path
-   * @default '/'
-   */
-  basename: '/my-app',
-
-  /**
-   * React Router future flags (optional).
-   * Example: split client route modules into separate chunks.
-   */
-  future: {
-    v8_splitRouteModules: true,
-  },
+  basename: '/',
+  splitRouteModules: true,
+  subResourceIntegrity: false,
 } satisfies Config;
 ```
 
-All configuration options are optional and will use sensible defaults if not specified.
+Commonly used options:
+
+| Option                 | Default      | Notes                                                                                                                     |
+| ---------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `ssr`                  | `true`       | Set `false` for SPA mode. SPA mode still runs a build-time server render to create `build/client/index.html`.             |
+| `buildDirectory`       | `'build'`    | Output root. Client assets go in `<buildDirectory>/client`; server output goes in `<buildDirectory>/server`.              |
+| `appDirectory`         | `'app'`      | Directory containing `root`, `routes`, and optional `entry.client` / `entry.server` files.                                |
+| `basename`             | `'/'`        | Base URL used for routing, prerender requests, and manifest asset paths.                                                  |
+| `serverBuildFile`      | `'index.js'` | Server build file name. It must end in `.js`.                                                                             |
+| `serverModuleFormat`   | `'esm'`      | React Router server module format: `'esm'` or `'cjs'`. `serverOutput` can override the emitted Rsbuild server format.     |
+| `serverBundles`        | `undefined`  | Advanced server bundle splitting by route branch. Disabled when `ssr: false`.                                             |
+| `routeDiscovery`       | React Router | Defaults to lazy discovery for SSR and initial discovery for SPA mode. `routeDiscovery.mode: 'lazy'` is invalid for SPA.  |
+| `prerender`            | `undefined`  | `true`, an array of paths, a function, or `{ paths, concurrency }` / `{ paths, unstable_concurrency }`.                   |
+| `splitRouteModules`    | `true`       | Splits client route module exports. The legacy `future.v8_splitRouteModules` flag is also accepted.                       |
+| `subResourceIntegrity` | `false`      | Emits SRI metadata for browser scripts. The legacy `future.unstable_subResourceIntegrity` flag is normalized to this key. |
+| `buildEnd`             | `undefined`  | Hook called after the build with the React Router build manifest and resolved config.                                     |
 
 ### Config File Resolution
 
@@ -256,36 +213,27 @@ export default {
 } satisfies Config;
 ```
 
-For large sites, you can tune prerender concurrency:
+Prerendering defaults to one path at a time, matching React Router. Use
+`concurrency` for larger sites; `unstable_concurrency` is still accepted for
+older configs:
 
 ```ts
 export default {
   ssr: false,
   prerender: {
-    paths: ['/','/about'],
-    unstable_concurrency: 4,
+    paths: ['/', '/about'],
+    concurrency: 4,
   },
 } satisfies Config;
 ```
 
-### Default Configuration Values
-
-If no configuration is provided, the following defaults will be used:
+For builds with 256+ routes, detailed file-size reporting is compacted to totals
+by default to avoid gzipping and printing thousands of assets. Set
+`performance.printFileSize` to an object to customize that output.
 
-```ts
-// Plugin defaults (rsbuild.config.ts)
-{
-  customServer: false
-}
-
-// Router defaults (react-router.config.ts)
-{
-  ssr: true,
-  buildDirectory: 'build',
-  appDirectory: 'app',
-  basename: '/'
-}
-```
+Route transform source maps are generated in development only. If you enable
+Rsbuild source maps for faster local debugging, prefer a cheap JS map:
+`output.sourceMap: { js: 'cheap-module-source-map', css: false }`.
 
 ### Route Configuration
 
@@ -326,6 +274,7 @@ export default [
 ```
 
 The plugin provides several helper functions for defining routes:
+
 - `index()` - Creates an index route
 - `route()` - Creates a regular route with a path
 - `layout()` - Creates a layout route with nested children
@@ -336,6 +285,7 @@ The plugin provides several helper functions for defining routes:
 Route components support the following exports:
 
 #### Client-side Exports
+
 - `default` - The route component
 - `ErrorBoundary` - Error boundary component
 - `HydrateFallback` - Loading component during hydration
@@ -349,6 +299,7 @@ Route components support the following exports:
 - `shouldRevalidate` - Revalidation control
 
 #### Server-side Exports
+
 - `loader` - Server-side data loading
 - `action` - Server-side form actions
 - `middleware` - Server-side middleware
@@ -387,34 +338,37 @@ export default defineConfig(() => {
   return {
     plugins: [
       pluginReactRouter({
-        customServer: true
-      }), 
-      pluginReact()
+        customServer: true,
+      }),
+      pluginReact(),
     ],
   };
 });
 ```
 
-When using a custom server, you'll need to:
-
-1. Create a server handler (`server/index.ts`):
-```ts
-import { createRequestHandler } from '@react-router/express';
-
-export const app = createRequestHandler({
-  build: () => import('virtual/react-router/server-build'),
-  getLoadContext() {
-    // Add custom context available to your loaders/actions
-    return {
-      // ... your custom context
-    };
-  },
-});
-```
+If the server is created programmatically with `createDevServer()`, pass
+`onRouteTopologyChange` and use it to recreate that server. Rsbuild's
+`reload-server` watcher is owned by the CLI and is not installed by the
+programmatic API. The callback is a notification and is not awaited, so it can
+safely start a serialized replacement task. Always `await` the active server's
+`close()` before calling `createDevServer()` again; the plugin rejects overlapping
+or out-of-order replacement instead of closing one server from inside another
+server's startup hooks. If startup fails before returning a server, or if
+`close()` rejects, restart the process before retrying unless you can externally
+prove and force complete teardown; a fresh Rsbuild instance alone is not
+sufficient. Do not launch concurrent `createDevServer()` calls.
+
+Create one server entry point (`server.js`) and let it own the React Router
+request handler in both development and production. Only the build provider
+changes between modes:
 
-2. Set up your server entry point (`server.js`):
 ```js
 import { createRsbuild, loadConfig } from '@rsbuild/core';
+import { createRequestHandler } from '@react-router/express';
+import {
+  loadReactRouterServerBuild,
+  resolveReactRouterServerBuild,
+} from 'rsbuild-plugin-react-router';
 import express from 'express';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -426,80 +380,95 @@ const app = express();
 const isDev = process.env.NODE_ENV !== 'production';
 
 async function startServer() {
+  let devServer;
+  let build;
+
   if (isDev) {
     const config = await loadConfig();
     const rsbuild = await createRsbuild({
       rsbuildConfig: config.content,
     });
-    const devServer = await rsbuild.createDevServer();
-    app.use(devServer.middlewares);
-
-    app.use(async (req, res, next) => {
-      try {
-        const bundle = await devServer.environments.node.loadBundle('app');
-        await bundle.app(req, res, next);
-      } catch (e) {
-        next(e);
-      }
-    });
-
-    const port = Number.parseInt(process.env.PORT || '3000', 10);
-    const server = app.listen(port, () => {
-      console.log(`Development server is running on http://localhost:${port}`);
-      devServer.afterListen();
-    });
-    devServer.connectWebSocket({ server });
+    const currentDevServer = await rsbuild.createDevServer();
+    devServer = currentDevServer;
+    app.use(currentDevServer.middlewares);
+    build = () => loadReactRouterServerBuild(currentDevServer);
   } else {
-    // Production mode
-    app.use(express.static(path.join(__dirname, 'build/client'), {
-      index: false
-    }));
-
-    // Load the server bundle
-    const serverBundle = await import('./build/server/static/js/app.js');
-    // Mount the server app after static file handling
-    app.use(async (req, res, next) => {
-      try {
-        await serverBundle.default.app(req, res, next);
-      } catch (e) {
-        next(e);
-      }
-    });
-
-    const port = Number.parseInt(process.env.PORT || '3000', 10);
-    app.listen(port, () => {
-      console.log(`Production server is running on http://localhost:${port}`);
-    });
+    app.use(
+      express.static(path.join(__dirname, 'build/client'), {
+        index: false,
+      })
+    );
+    build = await resolveReactRouterServerBuild(
+      import('./build/server/static/js/app.js')
+    );
   }
+
+  app.use(
+    createRequestHandler({
+      build,
+      mode: isDev ? 'development' : 'production',
+      getLoadContext() {
+        return {
+          // Add custom loader/action context here.
+        };
+      },
+    })
+  );
+
+  const port = Number.parseInt(process.env.PORT || '3000', 10);
+  const server = app.listen(port, () => {
+    const mode = isDev ? 'Development' : 'Production';
+    console.log(`${mode} server is running on http://localhost:${port}`);
+    devServer?.afterListen();
+  });
+  devServer?.connectWebSocket({ server });
 }
 
 startServer().catch(console.error);
 ```
 
-3. Update your `package.json` scripts:
+`loadReactRouterServerBuild` waits for a complete React Router development
+generation. During rebuilds it returns the last successfully evaluated server
+build, whose embedded manifest is paired with the selected web compilation.
+A failed or incomplete candidate does not replace that last-good pair. The
+built-in development middleware uses the same path. Calling
+`devServer.environments.node.loadBundle()` directly bypasses this guarantee.
+
+When `serverBundles` is configured, pass its exact Rsbuild entry name as the
+optional second argument (for example, `bundle-a/index`). The default build
+and every configured bundle are
+evaluated and published as one generation; one failing bundle keeps the whole
+previous generation active.
+
+`resolveReactRouterServerBuild` accepts an imported production server module,
+normalizes ESM and CommonJS namespace shapes, resolves supported asynchronous
+build exports, and validates the result before it reaches React Router.
+
+This guarantee covers the eagerly evaluated server entry object and its
+embedded manifest. It does not snapshot deferred server chunks, make emitted
+client assets immutable, or delay Rsbuild's WebSocket success notification.
+Same-path server or client chunks can change before the matching framework
+generation commits. Closing that publication gap requires a supported Rsbuild
+graph-settled hook plus immutable or staged outputs.
+
+Then update your `package.json` scripts:
+
 ```json
 {
   "scripts": {
-    "dev": "node server.js",
+    "dev": "NODE_ENV=development NODE_OPTIONS=\"--experimental-vm-modules\" node server.js",
     "build": "rsbuild build",
     "start": "NODE_ENV=production node server.js"
   }
 }
 ```
 
-The custom server setup allows you to:
-- Add custom middleware
-- Handle API routes
-- Integrate with databases
-- Implement custom authentication
-- Add server-side caching
-- And more!
-
 ## Cloudflare Workers Deployment
 
 To deploy your React Router app to Cloudflare Workers:
 
 1. **Configure Rsbuild** (`rsbuild.config.ts`):
+
 ```ts
 import { defineConfig } from '@rsbuild/core';
 import { pluginReact } from '@rsbuild/plugin-react';
@@ -524,17 +493,24 @@ export default defineConfig({
             module: true,
           },
           resolve: {
-            conditionNames: ['workerd', 'worker', 'browser', 'import', 'require'],
+            conditionNames: [
+              'workerd',
+              'worker',
+              'browser',
+              'import',
+              'require',
+            ],
           },
         },
       },
     },
   },
-  plugins: [pluginReactRouter({customServer: true}), pluginReact()],
+  plugins: [pluginReactRouter({ customServer: true }), pluginReact()],
 });
 ```
 
 2. **Configure Wrangler** (`wrangler.toml`):
+
 ```toml
 workers_dev = true
 name = "my-react-router-worker"
@@ -552,6 +528,7 @@ VALUE_FROM_CLOUDFLARE = "Hello from Cloudflare"
 ```
 
 3. **Create Worker Entry** (`server/index.ts`):
+
 ```ts
 import { createRequestHandler } from 'react-router';
 
@@ -588,6 +565,7 @@ export default {
 ```
 
 4. **Update Package Dependencies**:
+
 ```json
 {
   "dependencies": {
@@ -605,6 +583,7 @@ export default {
 ```
 
 5. **Setup Deployment Scripts** (`package.json`):
+
 ```json
 {
   "scripts": {
@@ -630,6 +609,7 @@ export default {
 ### Development Workflow:
 
 1. Local Development:
+
    ```bash
    # Start local development server
    npm run dev
@@ -646,6 +626,7 @@ export default {
 ## Development
 
 The plugin automatically:
+
 - Runs type generation during development and build
 - Sets up development server with live reload
 - Handles route-based code splitting
@@ -657,7 +638,7 @@ React Router "Framework Mode" wraps Data Mode using a Vite plugin. This Rsbuild
 plugin aims to match the important behaviors without depending on Vite:
 
 - Typegen + Route Module API types (`./+types/*`)
-- Route module splitting (`future.v8_splitRouteModules`)
+- Route module splitting (`splitRouteModules`)
 - SPA mode (`ssr: false`), SSR mode, and static prerendering (`prerender`)
 
 Some Vite-specific integrations (for example Vite's environment API + critical
@@ -667,17 +648,17 @@ CSS endpoint) are not supported 1:1.
 
 The repository includes several examples demonstrating different use cases:
 
-| Example | Description | Port | Command |
-|---------|-------------|------|---------|
-| [default-template](./examples/default-template) | Standard SSR setup with React Router | 3000 | `pnpm dev` |
-| [spa-mode](./examples/spa-mode) | Single Page Application (`ssr: false`) | 3001 | `pnpm dev` |
-| [prerender](./examples/prerender) | Static prerendering for multiple routes | 3002 | `pnpm dev` |
-| [custom-node-server](./examples/custom-node-server) | Custom Express server with SSR | 3003 | `pnpm dev` |
-| [cloudflare](./examples/cloudflare) | Cloudflare Workers deployment | 3004 | `pnpm dev` |
-| [client-only](./examples/client-only) | `.client` modules with SSR hydration | 3010 | `pnpm dev` |
-| [epic-stack](./examples/epic-stack) | Full-featured Epic Stack example | 3005 | `pnpm dev` |
-| [federation/epic-stack](./examples/federation/epic-stack) | Module Federation host | 3006 | `pnpm dev` |
-| [federation/epic-stack-remote](./examples/federation/epic-stack-remote) | Module Federation remote | 3007 | `pnpm dev` |
+| Example                                                                 | Description                             | Port | Command    |
+| ----------------------------------------------------------------------- | --------------------------------------- | ---- | ---------- |
+| [default-template](./examples/default-template)                         | Standard SSR setup with React Router    | 3000 | `pnpm dev` |
+| [spa-mode](./examples/spa-mode)                                         | Single Page Application (`ssr: false`)  | 3001 | `pnpm dev` |
+| [prerender](./examples/prerender)                                       | Static prerendering for multiple routes | 3002 | `pnpm dev` |
+| [custom-node-server](./examples/custom-node-server)                     | Custom Express server with SSR          | 3003 | `pnpm dev` |
+| [cloudflare](./examples/cloudflare)                                     | Cloudflare Workers deployment           | 3004 | `pnpm dev` |
+| [client-only](./examples/client-only)                                   | `.client` modules with SSR hydration    | 3010 | `pnpm dev` |
+| [epic-stack](./examples/epic-stack)                                     | Full-featured Epic Stack example        | 3005 | `pnpm dev` |
+| [federation/epic-stack](./examples/federation/epic-stack)               | Module Federation host                  | 3006 | `pnpm dev` |
+| [federation/epic-stack-remote](./examples/federation/epic-stack-remote) | Module Federation remote                | 3007 | `pnpm dev` |
 
 Each example has unique ports configured to allow running multiple examples simultaneously.