rsbuild-plugin-react-router 0.2.0 → 0.3.0

package/dist/typegen.d.ts

@@ -0,0 +1,2 @@
+import type { RsbuildPluginAPI } from '@rsbuild/core';
+export declare const registerReactRouterTypegen: (api: RsbuildPluginAPI) => void;

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { RsbuildConfig } from '@rsbuild/core';
 export type Route = {
     id: string;
     parentId?: string;
@@ -24,18 +25,35 @@ export type PluginOptions = {
      * Federation mode configuration
      */
     federation?: boolean;
-};
-/**
- * Arguments passed to transform functions
- */
-export type TransformArgs = {
-    code: string;
-    resource: string;
-    resourcePath: string;
-    context?: string | null;
-    environment?: {
-        name: string;
-    };
+    /**
+     * Opt in to Rsbuild's dev-only lazy compilation behavior.
+     *
+     * React Router hydration modules remain eager so initial dev requests can
+     * load the browser manifest and route modules without lazy proxy delays.
+     *
+     * @default undefined
+     */
+    lazyCompilation?: NonNullable<RsbuildConfig['dev']>['lazyCompilation'];
+    /**
+     * Emit structured React Router plugin timing logs.
+     * @default false
+     */
+    logPerformance?: boolean;
+    /**
+     * Run route transforms in a worker-thread pool.
+     * Pass `true` to force the default worker count, a positive integer to set
+     * the worker count, or `false` to disable.
+     * @default Automatically enabled for 256+ resolved routes. The automatic
+     * pool uses available CPU cores minus 2.
+     */
+    parallelRouteTransform?: boolean | number;
+    /**
+     * Called when the route graph changes during development.
+     * Programmatic/custom servers can use this to recreate their Rsbuild server;
+     * the CLI uses its built-in reload-server watcher when this is omitted. This
+     * notification is not awaited, so it may safely close the current server.
+     */
+    onRouteTopologyChange?: () => void | Promise<void>;
 };
 export type RouteManifestItem = Omit<Route, 'file' | 'children'> & {
     module: string;

package/dist/virtual-modules.d.ts

@@ -0,0 +1,2 @@
+export declare const getVirtualModuleFilePath: (moduleId: string) => string;
+export declare const mapVirtualModules: (modules: Record<string, string>) => Record<string, string>;

package/dist/warnings/warn-on-client-source-maps.d.ts

@@ -1,5 +1,6 @@
 import type { NormalizedConfig } from '@rsbuild/core';
 type Warn = (message: string) => void;
+export declare function isSourceMapEnabled(value: unknown): boolean;
 export declare function getClientSourceMapSetting(normalized: NormalizedConfig, clientEnvName?: string): unknown;
 export declare function getClientDevtoolSetting(normalized: NormalizedConfig, clientEnvName?: string): unknown;
 export declare function warnOnClientSourceMaps(normalized: NormalizedConfig, warn: Warn, clientEnvName?: string): void;

package/dist/yuku.d.ts

@@ -0,0 +1,15 @@
+import { walk, type ParseOptions, type ParseResult } from 'yuku-parser';
+import type { Rspack } from '@rsbuild/core';
+export declare const parse: (code: string, options?: ParseOptions) => ParseResult;
+export declare const traverse: typeof walk;
+export declare const generate: (ast: ParseResult | {
+    type: "Program";
+}, options?: {
+    sourceMaps?: boolean;
+    filename?: string;
+    sourceFileName?: string;
+}) => {
+    code: string;
+    map: Rspack.RawSourceMap | null;
+};
+export type { ParseResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsbuild-plugin-react-router",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React Router plugin for Rsbuild",
   "repository": {
     "type": "git",
@@ -42,22 +42,16 @@
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publint": {
     "ignoreMissingDts": true
   },
   "dependencies": {
-    "@babel/core": "^7.28.6",
-    "@babel/generator": "^7.28.6",
-    "@babel/parser": "^7.28.6",
-    "@babel/traverse": "^7.28.6",
-    "@babel/types": "^7.28.6",
     "@react-router/node": "^7.13.0",
     "@remix-run/node-fetch-server": "^0.13.0",
     "@rspack/plugin-react-refresh": "^2.0.2",
-    "babel-dead-code-elimination": "^1.0.12",
-    "esbuild": "^0.27.2",
     "execa": "^9.6.1",
     "fs-extra": "11.3.3",
     "isbot": "5.1.34",
@@ -65,20 +59,20 @@
     "jsesc": "^3.1.0",
     "pathe": "^2.0.3",
     "react-refresh": "^0.18.0",
-    "rspack-plugin-virtual-module": "^1.0.1"
+    "yuku-analyzer": "0.5.39",
+    "yuku-codegen": "0.5.39",
+    "yuku-parser": "0.5.39"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
-    "@react-router/dev": "^7.13.0",
-    "@rsbuild/core": "2.0.15",
+    "@react-router/dev": "^8.0.1",
+    "@rsbuild/core": "2.1.0",
+    "@rsbuild/plugin-react": "2.1.0",
     "@rslib/core": "^0.22.1",
-    "@rspack/core": "2.0.8",
-    "@swc/helpers": "^0.5.23",
+    "@rspack/core": "2.1.0",
     "@rstest/core": "^0.8.1",
     "@rstest/coverage-istanbul": "^0.2.0",
-    "@types/babel__core": "^7.20.5",
-    "@types/babel__generator": "^7.27.0",
-    "@types/babel__traverse": "^7.28.0",
+    "@swc/helpers": "^0.5.23",
     "@types/fs-extra": "11.0.4",
     "@types/jsesc": "^3.0.3",
     "@types/node": "^25.0.10",
@@ -86,7 +80,8 @@
     "@types/react-dom": "^19.2.3",
     "es-module-lexer": "1.7.0",
     "kill-port": "^2.0.1",
-    "playwright": "^1.58.0",
+    "pkg-pr-new": "^0.0.75",
+    "playwright": "1.58.0",
     "prettier": "3.8.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
@@ -105,13 +100,21 @@
   },
   "scripts": {
     "build": "rslib build",
-    "e2e": "pnpm build && pnpm --filter './examples/{default-template,spa-mode,prerender,custom-node-server,cloudflare,client-only}' test:e2e",
+    "bench": "node scripts/bench-builds.mjs",
+    "bench:ci-report": "node scripts/report-benchmark-ci.mjs",
+    "bench:compare": "node scripts/compare-benchmarks.mjs",
+    "bench:smoke": "node scripts/bench-builds.mjs --profile smoke --iterations 1 --warmup 0 --format both --out .benchmark/results/smoke",
+    "bench:baseline": "node scripts/bench-builds.mjs --profile default --iterations 5 --warmup 1 --clean build --format both --out .benchmark/results/baseline",
+    "bench:full": "node scripts/bench-builds.mjs --profile full --iterations 5 --warmup 1 --clean build --format both --out .benchmark/results/full",
+    "bench:large": "node scripts/bench-builds.mjs --profile large --iterations 1 --warmup 0 --clean cold --format both --out .benchmark/results/large",
+    "e2e": "pnpm build && pnpm test:package-interop && pnpm --filter './examples/{default-template,spa-mode,prerender,custom-node-server,cloudflare,client-only}' test:e2e",
     "dev": "rslib build --watch",
     "test": "rstest run",
     "test:watch": "rstest watch",
     "test:coverage": "rstest run --coverage",
     "test:core": "rstest run -c ./rstest.config.ts",
     "test:core:watch": "rstest watch -c ./rstest.config.ts",
+    "test:package-interop": "node scripts/test-package-interop.mjs",
     "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx}\"",
     "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\"",
     "changeset": "changeset",

package/src/bounded-cache.ts

@@ -0,0 +1,18 @@
+export const setBoundedCacheEntry = <Key, Value>(
+  cache: Map<Key, Value>,
+  key: Key,
+  value: Value,
+  maxEntries: number
+): void => {
+  if (maxEntries <= 0) {
+    cache.clear();
+    return;
+  }
+  if (!cache.has(key) && cache.size >= maxEntries) {
+    const oldestEntry = cache.keys().next();
+    if (!oldestEntry.done) {
+      cache.delete(oldestEntry.value);
+    }
+  }
+  cache.set(key, value);
+};

package/src/build-manifest.ts

@@ -0,0 +1,168 @@
+import { relative, resolve } from 'pathe';
+import type { Config } from './react-router-config.js';
+import type { Route } from './types.js';
+
+type BuildManifest =
+  | {
+      routes: Record<string, Route>;
+    }
+  | {
+      routes: Record<string, Route>;
+      serverBundles: Record<string, { id: string; file: string }>;
+      routeIdToServerBundleId: Record<string, string>;
+    };
+
+const normalizePath = (value: string): string => value.replace(/\\/g, '/');
+
+const getAddressableRoutes = (routes: Record<string, Route>): Route[] => {
+  const nonAddressableIds = new Set<string>();
+  for (const id in routes) {
+    const route = routes[id];
+    if (route.index) {
+      if (!route.parentId) {
+        continue;
+      }
+      nonAddressableIds.add(route.parentId);
+    }
+    if (typeof route.path !== 'string' && !route.index) {
+      nonAddressableIds.add(id);
+    }
+  }
+  return Object.values(routes).filter(
+    route => !nonAddressableIds.has(route.id)
+  );
+};
+
+const getRouteBranch = (
+  routes: Record<string, Route>,
+  routeId: string
+): Route[] => {
+  const branch: Route[] = [];
+  let current = routeId;
+  while (current) {
+    const route = routes[current];
+    if (!route) {
+      throw new Error(`Missing route for ${current}`);
+    }
+    branch.push(route);
+    current = route.parentId || '';
+  }
+  return branch.reverse();
+};
+
+const configRouteToBranchRoute = (route: Route) => ({
+  id: route.id,
+  path: route.path,
+  file: route.file,
+  index: route.index,
+});
+
+export const getBuildManifest = async ({
+  reactRouterConfig,
+  routes,
+  rootDirectory,
+}: {
+  reactRouterConfig: Required<
+    Pick<
+      Config,
+      'appDirectory' | 'buildDirectory' | 'serverBuildFile' | 'future'
+    >
+  > &
+    Pick<Config, 'serverBundles'>;
+  routes: Record<string, Route>;
+  rootDirectory: string;
+}): Promise<BuildManifest | undefined> => {
+  const {
+    serverBundles,
+    appDirectory,
+    buildDirectory,
+    serverBuildFile,
+    future,
+  } = reactRouterConfig;
+
+  if (!serverBundles) {
+    return { routes };
+  }
+
+  const rootRelativeRoutes = Object.fromEntries(
+    Object.entries(routes).map(([id, route]) => {
+      const filePath = resolve(appDirectory, route.file);
+      return [
+        id,
+        { ...route, file: normalizePath(relative(rootDirectory, filePath)) },
+      ];
+    })
+  );
+
+  const serverBuildDirectory = resolve(buildDirectory, 'server');
+
+  const buildManifest: BuildManifest = {
+    routes: rootRelativeRoutes,
+    serverBundles: {},
+    routeIdToServerBundleId: {},
+  };
+
+  await Promise.all(
+    getAddressableRoutes(routes).map(async route => {
+      const branch = getRouteBranch(routes, route.id);
+      const serverBundleId = await serverBundles({
+        branch: branch.map(branchRoute =>
+          configRouteToBranchRoute({
+            ...branchRoute,
+            file: resolve(appDirectory, branchRoute.file),
+          })
+        ),
+      });
+
+      if (typeof serverBundleId !== 'string') {
+        throw new Error('The "serverBundles" function must return a string');
+      }
+
+      if (future?.v8_viteEnvironmentApi) {
+        if (!/^[a-zA-Z0-9_]+$/.test(serverBundleId)) {
+          throw new Error(
+            'The "serverBundles" function must only return strings containing alphanumeric characters and underscores.'
+          );
+        }
+      } else if (!/^[a-zA-Z0-9-_]+$/.test(serverBundleId)) {
+        throw new Error(
+          'The "serverBundles" function must only return strings containing alphanumeric characters, hyphens and underscores.'
+        );
+      }
+
+      buildManifest.routeIdToServerBundleId![route.id] = serverBundleId;
+      buildManifest.serverBundles![serverBundleId] ??= {
+        id: serverBundleId,
+        file: normalizePath(
+          relative(
+            rootDirectory,
+            resolve(serverBuildDirectory, serverBundleId, serverBuildFile)
+          )
+        ),
+      };
+    })
+  );
+
+  return buildManifest;
+};
+
+export const getRoutesByServerBundleId = (
+  buildManifest: BuildManifest | undefined,
+  sourceRoutes: Record<string, Route>
+): Record<string, Record<string, Route>> => {
+  if (!buildManifest || !('routeIdToServerBundleId' in buildManifest)) {
+    return {};
+  }
+
+  const routesByServerBundleId: Record<string, Record<string, Route>> = {};
+  for (const [routeId, serverBundleId] of Object.entries(
+    buildManifest.routeIdToServerBundleId
+  )) {
+    routesByServerBundleId[serverBundleId] ??= {};
+    const branch = getRouteBranch(sourceRoutes, routeId);
+    for (const route of branch) {
+      routesByServerBundleId[serverBundleId][route.id] = route;
+    }
+  }
+  return routesByServerBundleId;
+};

package/src/build-output-transforms.ts

@@ -0,0 +1,273 @@
+import type { RsbuildPluginAPI, TransformHandler } from '@rsbuild/core';
+import jsesc from 'jsesc';
+import { relative } from 'pathe';
+import { PLUGIN_NAME } from './constants.js';
+import {
+  getReactRouterManifestForDev,
+  type ReactRouterManifestStats,
+} from './manifest.js';
+import type { RouteTransformExecutor } from './parallel-route-transforms.js';
+import type { ReactRouterPerformanceProfiler } from './performance.js';
+import { createBundlerRouteExportResolver } from './route-export-resolution.js';
+import type { RouteChunkConfig } from './route-chunks.js';
+import type { PluginOptions, Route } from './types.js';
+import { isSourceMapEnabled } from './warnings/warn-on-client-source-maps.js';
+
+type ReactRouterManifest = Awaited<
+  ReturnType<typeof getReactRouterManifestForDev>
+>;
+
+type RegisterBuildOutputTransformsOptions = {
+  api: RsbuildPluginAPI;
+  resolvedServerOutput: 'module' | 'commonjs';
+  performanceProfiler: ReactRouterPerformanceProfiler;
+  getLatestServerManifest: () => ReactRouterManifest | null;
+  getLatestServerManifestByBundleId: (
+    bundleId: string
+  ) => ReactRouterManifest | undefined;
+  routes: Record<string, Route>;
+  pluginOptions: PluginOptions;
+  getClientStats: () => ReactRouterManifestStats | undefined;
+  appDirectory: string;
+  getAssetPrefix: () => string;
+  routeChunkOptions: Parameters<typeof getReactRouterManifestForDev>[5];
+  routeTransformExecutor: RouteTransformExecutor;
+  routeByFilePath: Map<string, Route>;
+  routeChunkConfig: RouteChunkConfig;
+  isBuild: boolean;
+  splitRouteModules: boolean;
+  ssr: boolean;
+  isSpaMode: boolean;
+  rootRoutePath: string;
+};
+
+export const registerBuildOutputTransforms = ({
+  api,
+  resolvedServerOutput,
+  performanceProfiler,
+  getLatestServerManifest,
+  getLatestServerManifestByBundleId,
+  routes,
+  pluginOptions,
+  getClientStats,
+  appDirectory,
+  getAssetPrefix,
+  routeChunkOptions,
+  routeTransformExecutor,
+  routeByFilePath,
+  routeChunkConfig,
+  isBuild,
+  splitRouteModules,
+  ssr,
+  isSpaMode,
+  rootRoutePath,
+}: RegisterBuildOutputTransformsOptions): void => {
+  const transformRouteModule = async (args: Parameters<TransformHandler>[0]) =>
+    performanceProfiler.record(
+      args.environment?.name,
+      'route:module',
+      args.resource,
+      async () =>
+        routeTransformExecutor.run({
+          kind: 'routeModule',
+          code: args.code,
+          resource: args.resource,
+          resourcePath: args.resourcePath,
+          environmentName: args.environment.name,
+          sourceMaps: isSourceMapEnabled(
+            args.environment.config.output.sourceMap
+          ),
+          ssr,
+          isBuild,
+          isSpaMode,
+          rootRoutePath,
+        })
+    );
+
+  api.processAssets(
+    { stage: 'additional', targets: ['node'] },
+    ({ sources, compilation }) => {
+      const packageJsonPath = 'package.json';
+      const source = new sources.RawSource(
+        `{"type": "${resolvedServerOutput}"}`
+      );
+
+      if (compilation.getAsset(packageJsonPath)) {
+        compilation.updateAsset(packageJsonPath, source);
+      } else {
+        compilation.emitAsset(packageJsonPath, source);
+      }
+    }
+  );
+
+  api.transform(
+    {
+      test: /virtual\/react-router\/(browser|server)-manifest/,
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'manifest:transform',
+        args.resource,
+        async () => {
+          if (args.environment.name === 'web') {
+            return {
+              code: `window.__reactRouterManifest = "PLACEHOLDER";`,
+            };
+          }
+
+          const bundleMatch = args.resource.match(
+            /virtual\/react-router\/server-manifest(?:-([^?]+))?/
+          );
+          const bundleId = bundleMatch?.[1]?.replace(/\.js$/, '');
+          const latestServerManifest = getLatestServerManifest();
+          const manifest =
+            (latestServerManifest
+              ? ((bundleId && getLatestServerManifestByBundleId(bundleId)) ??
+                latestServerManifest)
+              : null) ??
+            (await getReactRouterManifestForDev(
+              routes,
+              pluginOptions,
+              getClientStats(),
+              appDirectory,
+              getAssetPrefix(),
+              routeChunkOptions
+            ));
+          return {
+            code: `export default ${jsesc(manifest, { es6: true })};`,
+          };
+        }
+      )
+  );
+
+  api.transform(
+    {
+      resourceQuery: /__react-router-build-client-route/,
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'route:client-entry',
+        args.resource,
+        async () =>
+          routeTransformExecutor.run({
+            kind: 'routeClientEntry',
+            code: args.code,
+            resourcePath: args.resourcePath,
+            environmentName: args.environment?.name,
+            isBuild,
+            routeChunkConfig,
+          })
+      )
+  );
+
+  api.transform(
+    {
+      resourceQuery: /route-chunk=/,
+      environments: ['web'],
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'route:chunk',
+        args.resource,
+        async () =>
+          routeTransformExecutor.run({
+            kind: 'routeChunk',
+            code: args.code,
+            resource: args.resource,
+            resourcePath: args.resourcePath,
+            isBuild,
+            routeChunkConfig,
+          })
+      )
+  );
+
+  if (isBuild && splitRouteModules) {
+    api.transform(
+      {
+        test: path => routeByFilePath.has(path),
+        resourceQuery: {
+          not: /__react-router-build-client-route|react-router-route|route-chunk=/,
+        },
+        environments: ['web'],
+      },
+      async args =>
+        performanceProfiler.record(
+          args.environment?.name,
+          'route:split-exports',
+          args.resource,
+          async () =>
+            routeTransformExecutor.run({
+              kind: 'splitRouteExports',
+              code: args.code,
+              resourcePath: args.resourcePath,
+              routeChunkConfig,
+            })
+        )
+    );
+  }
+
+  api.transform(
+    {
+      test: /[\\/]\.server[\\/]|\.server(\.[cm]?[jt]sx?)?$/,
+      environments: ['web'],
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'module:server-only-guard',
+        args.resource,
+        async () => {
+          const relativePath = relative(process.cwd(), args.resourcePath);
+          throw new Error(
+            `[${PLUGIN_NAME}] Server-only module referenced by client: ${relativePath}`
+          );
+        }
+      )
+  );
+
+  api.transform(
+    {
+      test: /[\\/]\.client[\\/]|\.client(\.[cm]?[jt]sx?)?$/,
+      environments: ['node'],
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'module:client-only-stub',
+        args.resource,
+        async () => {
+          return routeTransformExecutor.run({
+            kind: 'clientOnlyStub',
+            code: args.code,
+            resourcePath: args.resourcePath,
+            resolveExportAllModule:
+              typeof args.resolve === 'function'
+                ? createBundlerRouteExportResolver(args.resolve)
+                : undefined,
+          });
+        }
+      )
+  );
+
+  api.transform(
+    {
+      resourceQuery: /\?react-router-route/,
+      order: 'post',
+    },
+    transformRouteModule
+  );
+
+  api.transform(
+    {
+      test: path => routeByFilePath.has(path),
+      resourceQuery: {
+        not: /__react-router-build-client-route|react-router-route|route-chunk=/,
+      },
+      order: 'post',
+    },
+    transformRouteModule
+  );
+};

package/src/concurrency.ts

@@ -0,0 +1,34 @@
+import { availableParallelism, cpus } from 'node:os';
+
+const DEFAULT_RESERVED_CORES = 2;
+
+const getAvailableCpuCount = (): number =>
+  typeof availableParallelism === 'function'
+    ? availableParallelism()
+    : cpus().length;
+
+export const getDefaultConcurrency = (
+  cpuCount: number = getAvailableCpuCount()
+): number => Math.max(0, Math.floor(cpuCount) - DEFAULT_RESERVED_CORES);
+
+export const mapWithConcurrency = async <Item, Result>(
+  items: readonly Item[],
+  concurrency: number,
+  worker: (item: Item, index: number) => Promise<Result>
+): Promise<Result[]> => {
+  const results = new Array<Result>(items.length);
+  let nextIndex = 0;
+  const workerCount = Math.max(1, Math.min(concurrency, items.length));
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (true) {
+        const index = nextIndex++;
+        if (index >= items.length) {
+          return;
+        }
+        results[index] = await worker(items[index], index);
+      }
+    })
+  );
+  return results;
+};