rsbuild-plugin-react-router 0.3.0 → 0.3.1

package/src/server-utils.ts

@@ -1,5 +1,7 @@
 import { resolve } from 'pathe';
 import type { ServerBuild } from 'react-router';
+import { runPluginEffect } from './effect-runtime.js';
+import { resolveServerBuildModuleEffect } from './server-build-resolution.js';
 import type { Route } from './types.js';
 
 /**
@@ -91,120 +93,19 @@ function generateServerBuild(
   return generateStaticTemplate(routes, options);
 }
 
-const RESOLVABLE_BUILD_EXPORTS = new Set([
-  'allowedActionOrigins',
-  'assets',
-  'assetsBuildDirectory',
-  'basename',
-  'entry',
-  'future',
-  'isSpaMode',
-  'prerender',
-  'publicPath',
-  'routeDiscovery',
-  'routes',
-  'ssr',
-]);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
-  return isRecord(value) && typeof value.then === 'function';
-}
-
-function isRouteDiscovery(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    (value.mode === 'initial' ||
-      (value.mode === 'lazy' &&
-        (value.manifestPath === undefined ||
-          typeof value.manifestPath === 'string')))
-  );
-}
-
-async function resolveBuildExports(
-  build: Record<string, unknown>
-): Promise<Record<string, unknown>> {
-  const resolved = { ...build };
-  for (const key of Object.keys(build)) {
-    if (!RESOLVABLE_BUILD_EXPORTS.has(key)) {
-      continue;
-    }
-    const value = build[key];
-    if (typeof value === 'function' && value.length === 0) {
-      const result = value();
-      resolved[key] = isPromiseLike(result) ? await result : result;
-      continue;
-    }
-    if (isPromiseLike(value)) {
-      resolved[key] = await value;
-    }
-  }
-  return resolved;
-}
-
-function isServerBuild(value: unknown): value is ServerBuild {
-  return Boolean(
-    isRecord(value) &&
-    isRecord(value.entry) &&
-    isRecord(value.entry.module) &&
-    typeof value.entry.module.default === 'function' &&
-    isRecord(value.routes) &&
-    isRecord(value.assets) &&
-    typeof value.assetsBuildDirectory === 'string' &&
-    (value.basename === undefined || typeof value.basename === 'string') &&
-    isRecord(value.future) &&
-    typeof value.isSpaMode === 'boolean' &&
-    Array.isArray(value.prerender) &&
-    typeof value.publicPath === 'string' &&
-    isRouteDiscovery(value.routeDiscovery) &&
-    typeof value.ssr === 'boolean'
-  );
-}
-
-async function resolveServerBuildCandidate(
-  candidate: unknown
-): Promise<ServerBuild | undefined> {
-  if (!isRecord(candidate)) {
-    return undefined;
-  }
-  const resolved = await resolveBuildExports(candidate);
-  return isServerBuild(resolved) ? resolved : undefined;
-}
-
-export async function resolveServerBuildModule(
+export function resolveServerBuildModule(
   buildModule: unknown,
   source: string
 ): Promise<ServerBuild> {
-  const moduleValue = await buildModule;
-  const candidates = [() => moduleValue];
-  if (isRecord(moduleValue)) {
-    if ('default' in moduleValue) {
-      candidates.push(() => moduleValue.default);
-    }
-    if ('module.exports' in moduleValue) {
-      candidates.push(() => moduleValue['module.exports']);
-    }
-  }
-
-  for (const getCandidate of candidates) {
-    const candidate = await getCandidate();
-    const serverBuild = await resolveServerBuildCandidate(candidate);
-    if (serverBuild) {
-      return serverBuild;
-    }
-  }
-  throw new Error(
-    `[rsbuild-plugin-react-router] ${source} did not contain a valid React Router ServerBuild.`
-  );
+  return runPluginEffect(resolveServerBuildModuleEffect(buildModule, source));
 }
 
 export function resolveReactRouterServerBuild(
   buildModule: unknown
 ): Promise<ServerBuild> {
-  return resolveServerBuildModule(buildModule, 'Imported module');
+  return runPluginEffect(
+    resolveServerBuildModuleEffect(buildModule, 'Imported module')
+  );
 }
 
 export { generateServerBuild };

package/src/ssr-externals.ts

@@ -15,7 +15,7 @@ const REACT_ROUTER_EXTERNALS = [
 
 const requireFromHere = createRequire(import.meta.url);
 
-function resolvePackageJson(
+export function resolvePackageJson(
   name: string,
   rootDirectory: string
 ): string | null {

package/src/typegen.ts

@@ -1,49 +1,178 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import type { RsbuildPluginAPI } from '@rsbuild/core';
 import type { ResultPromise } from 'execa';
+import * as Effect from 'effect/Effect';
+import { createDelayedPluginTask, tryPluginPromise } from './effect-runtime.js';
+import { resolvePackageJson } from './ssr-externals.js';
 
-export const registerReactRouterTypegen = (api: RsbuildPluginAPI): void => {
-  let typegenProcess: ResultPromise | undefined;
+// Quiet period with no dev compiles before the typegen watch starts. Long
+// enough that route-load and HMR compile bursts (each rescheduling the task)
+// finish before the typegen process competes for CPU on small machines.
+const TYPEGEN_IDLE_DELAY_MS = 10_000;
+
+type Execa = typeof import('execa').execa;
+type LoadExeca = () => Promise<Execa>;
+
+export type ReactRouterTypegenRunner = {
+  startWatch(): Promise<void>;
+  closeWatch(): Promise<void>;
+  runBuild(): Promise<void>;
+};
+
+const loadDefaultExeca: LoadExeca = async () => {
+  const { execa } = await import('execa');
+  return execa;
+};
+
+type TypegenCommand = {
+  command: string;
+  args: string[];
+};
 
-  api.onBeforeStartDevServer(async () => {
-    if (typegenProcess) {
-      return;
+// The `react-router` CLI bin is provided by `@react-router/dev`. Spawning it
+// directly through `process.execPath` skips the npx bootstrap (npm config
+// load and package resolution), which otherwise costs several hundred ms of
+// CPU during dev-server startup and every production build.
+const resolveDirectTypegenCommand = (
+  appDirectory: string
+): TypegenCommand | undefined => {
+  const packageJsonPath = resolvePackageJson('@react-router/dev', appDirectory);
+  if (!packageJsonPath) {
+    // `@react-router/dev` is not resolvable from the app directory; the
+    // caller falls back to spawning through npx.
+    return undefined;
+  }
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+      bin?: string | Record<string, string>;
+    };
+    const binRelativePath =
+      typeof packageJson.bin === 'string'
+        ? packageJson.bin
+        : packageJson.bin?.['react-router'];
+    if (!binRelativePath) {
+      return undefined;
     }
-    const { execa } = await import('execa');
-    const process = execa(
-      'npx',
-      ['--yes', 'react-router', 'typegen', '--watch'],
-      {
-        stdio: 'inherit',
-        detached: false,
-        cleanup: true,
-      }
-    );
-    typegenProcess = process;
-    process
-      .catch(() => {
-        // Ignore errors when the process is killed on server shutdown.
-      })
+    return {
+      command: process.execPath,
+      args: [resolve(dirname(packageJsonPath), binRelativePath)],
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+export const createReactRouterTypegenRunner = (
+  loadExeca: LoadExeca = loadDefaultExeca,
+  appDirectory?: string
+): ReactRouterTypegenRunner => {
+  let typegenProcess: ResultPromise | undefined;
+  let typegenCommand: TypegenCommand | undefined;
+
+  const getTypegenCommand = (): TypegenCommand => {
+    typegenCommand ??= (appDirectory
+      ? resolveDirectTypegenCommand(appDirectory)
+      : undefined) ?? {
+      command: 'npx',
+      args: ['--yes', 'react-router'],
+    };
+    return typegenCommand;
+  };
+
+  const observeWatchExit = (process: ResultPromise): void => {
+    void process
+      .catch(() => undefined)
       .finally(() => {
         if (typegenProcess === process) {
           typegenProcess = undefined;
         }
       });
-  });
+  };
 
-  api.onCloseDevServer(async () => {
-    const process = typegenProcess;
-    typegenProcess = undefined;
-    if (!process) {
-      return;
-    }
-    process.kill('SIGTERM');
-    await process.catch(() => undefined);
+  return {
+    async startWatch(): Promise<void> {
+      if (typegenProcess) {
+        return;
+      }
+
+      const execa = await loadExeca();
+      const { command, args } = getTypegenCommand();
+      const process = execa(command, [...args, 'typegen', '--watch'], {
+        stdio: 'inherit',
+        detached: false,
+        cleanup: true,
+      });
+      typegenProcess = process;
+      observeWatchExit(process);
+    },
+
+    async closeWatch(): Promise<void> {
+      const process = typegenProcess;
+      typegenProcess = undefined;
+      if (!process) {
+        return;
+      }
+
+      process.kill('SIGTERM');
+      await process.catch(() => undefined);
+    },
+
+    async runBuild(): Promise<void> {
+      const execa = await loadExeca();
+      const { command, args } = getTypegenCommand();
+      await execa(command, [...args, 'typegen'], {
+        stdio: 'inherit',
+      });
+    },
+  };
+};
+
+export const registerReactRouterTypegen = (
+  api: RsbuildPluginAPI,
+  {
+    runner,
+    devWatchDelayMs = TYPEGEN_IDLE_DELAY_MS,
+    appDirectory,
+  }: {
+    runner?: ReactRouterTypegenRunner;
+    devWatchDelayMs?: number;
+    appDirectory?: string;
+  } = {}
+): void => {
+  const resolvedRunner =
+    runner ?? createReactRouterTypegenRunner(loadDefaultExeca, appDirectory);
+  let devWatchStarted = false;
+  const devWatchTask = createDelayedPluginTask({
+    delayMs: devWatchDelayMs,
+    run: () =>
+      tryPluginPromise(() => {
+        devWatchStarted = true;
+        return resolvedRunner.startWatch();
+      }).pipe(Effect.asVoid),
+    onError(error) {
+      api.logger.warn(
+        `[react-router] Failed to start React Router typegen watch: ${error}`
+      );
+    },
   });
 
-  api.onBeforeBuild(async () => {
-    const { execa } = await import('execa');
-    await execa('npx', ['--yes', 'react-router', 'typegen'], {
-      stdio: 'inherit',
+  if (api.context.action !== 'build') {
+    // Reschedule on every compile so the typegen watch only starts after a
+    // quiet period with no compiles. Starting it during the initial compile
+    // burst competes with HMR rebuilds for CPU on small machines.
+    api.onAfterDevCompile(() => {
+      if (devWatchStarted) {
+        return;
+      }
+      devWatchTask.reschedule();
     });
+  }
+
+  api.onCloseDevServer(async () => {
+    await devWatchTask.cancel();
+    await resolvedRunner.closeWatch();
   });
+
+  api.onBeforeBuild(() => resolvedRunner.runBuild());
 };

package/src/types.ts

@@ -20,8 +20,8 @@ export type PluginOptions = {
 
   /**
    * The output format for server builds.
-   * When set to "module", no package.json will be emitted.
-   * @default "module"
+   * When omitted, React Router's `serverModuleFormat` selects the emitted
+   * Rsbuild format (`"esm"` -> `"module"`, `"cjs"` -> `"commonjs"`).
    */
   serverOutput?: 'module' | 'commonjs';
 
@@ -31,15 +31,25 @@ export type PluginOptions = {
   federation?: boolean;
 
   /**
-   * Opt in to Rsbuild's dev-only lazy compilation behavior.
+   * Rsbuild 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.
+   * React Router's browser manifest remains eager so initial dev requests can
+   * discover browser assets without lazy proxy delays.
    *
-   * @default undefined
+   * Pass `false` to disable.
+   * @default true
    */
   lazyCompilation?: NonNullable<RsbuildConfig['dev']>['lazyCompilation'];
 
+  /**
+   * Prewarm Rspack lazy-compilation proxy modules after dev compiles.
+   * This depends on Rspack's generated lazy-compilation client shape and should
+   * be treated as experimental.
+   *
+   * @default false
+   */
+  unstableLazyCompilationPrewarm?: boolean;
+
   /**
    * Emit structured React Router plugin timing logs.
    * @default false