rsbuild-plugin-react-router 0.2.0 → 0.3.1

package/src/ssr-externals.ts

@@ -0,0 +1,59 @@
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { sep } from 'node:path';
+
+const REACT_ROUTER_EXTERNALS = [
+  'react-router',
+  'react-router-dom',
+  '@react-router/architect',
+  '@react-router/cloudflare',
+  '@react-router/dev',
+  '@react-router/express',
+  '@react-router/node',
+  '@react-router/serve',
+];
+
+const requireFromHere = createRequire(import.meta.url);
+
+export function resolvePackageJson(
+  name: string,
+  rootDirectory: string
+): string | null {
+  try {
+    return requireFromHere.resolve(`${name}/package.json`, {
+      paths: [rootDirectory],
+    });
+  } catch {
+    return null;
+  }
+}
+
+function safeRealpath(pathname: string): string {
+  try {
+    return realpathSync(pathname);
+  } catch {
+    return pathname;
+  }
+}
+
+function isPathInNodeModules(pathname: string): boolean {
+  return pathname.split(sep).includes('node_modules');
+}
+
+export function getSsrExternals(rootDirectory: string): string[] {
+  const externals: string[] = [];
+
+  for (const name of REACT_ROUTER_EXTERNALS) {
+    const resolved = resolvePackageJson(name, rootDirectory);
+    if (!resolved) {
+      continue;
+    }
+
+    const realPath = safeRealpath(resolved);
+    if (!isPathInNodeModules(realPath)) {
+      externals.push(name);
+    }
+  }
+
+  return externals;
+}

package/src/templates/context.ts

@@ -0,0 +1,12 @@
+import { createContext } from 'react';
+import type { Context } from 'react';
+
+export interface Assets {
+  scriptTags: string[];
+  styleTags: string[];
+}
+
+export const AssetsContext: Context<Assets> = createContext<Assets>({
+  scriptTags: [],
+  styleTags: [],
+});

package/src/templates/entry.client.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { HydratedRouter } from 'react-router/dom';
+
+React.startTransition(() => {
+  hydrateRoot(
+    document,
+    <React.StrictMode>
+      <HydratedRouter />
+    </React.StrictMode>
+  );
+});

package/src/templates/entry.server.tsx

@@ -0,0 +1,76 @@
+import { PassThrough } from 'node:stream';
+import { createReadableStreamFromReadable } from '@react-router/node';
+import { isbot } from 'isbot';
+import * as React from 'react';
+import type { RenderToPipeableStreamOptions } from 'react-dom/server';
+import { renderToPipeableStream } from 'react-dom/server';
+import type {
+  // AppLoadContext,
+  EntryContext,
+} from 'react-router';
+import { ServerRouter } from 'react-router';
+
+const ABORT_DELAY = 5_000;
+
+export default function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  routerContext: EntryContext
+  // loadContext: AppLoadContext
+): Promise<Response> {
+  return new Promise<Response>((resolve, reject) => {
+    let shellRendered = false;
+    let statusCode = responseStatusCode;
+    const userAgent = request.headers.get('user-agent');
+
+    // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
+    // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
+    const readyOption: keyof RenderToPipeableStreamOptions =
+      (userAgent && isbot(userAgent)) || routerContext.isSpaMode
+        ? 'onAllReady'
+        : 'onShellReady';
+    let abortDelay: ReturnType<typeof setTimeout> | undefined;
+    let ready = false;
+
+    const { pipe, abort } = renderToPipeableStream(
+      <ServerRouter context={routerContext} url={request.url} />,
+      {
+        [readyOption]() {
+          ready = true;
+          if (readyOption === 'onAllReady' && abortDelay) {
+            clearTimeout(abortDelay);
+          }
+          shellRendered = true;
+          const body = new PassThrough();
+          const stream = createReadableStreamFromReadable(body);
+
+          responseHeaders.set('Content-Type', 'text/html');
+
+          resolve(
+            new Response(stream, {
+              headers: responseHeaders,
+              status: statusCode,
+            })
+          );
+
+          pipe(body);
+        },
+        onShellError(error: unknown) {
+          reject(error);
+        },
+        onError(error: unknown) {
+          statusCode = 500;
+          if (shellRendered) {
+            console.error(error);
+          }
+        },
+      }
+    );
+
+    abortDelay = setTimeout(abort, ABORT_DELAY);
+    if (readyOption === 'onAllReady' && ready) {
+      clearTimeout(abortDelay);
+    }
+  });
+}

package/src/typegen.ts

@@ -0,0 +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';
+
+// 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[];
+};
+
+// 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;
+    }
+    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;
+        }
+      });
+  };
+
+  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}`
+      );
+    },
+  });
+
+  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

@@ -0,0 +1,92 @@
+import type { RsbuildConfig } from '@rsbuild/core';
+
+export type Route = {
+  id: string;
+  parentId?: string;
+  file: string;
+  path?: string;
+  index?: boolean;
+  caseSensitive?: boolean;
+  children?: Route[];
+};
+
+export type PluginOptions = {
+  /**
+   * Whether to disable automatic middleware setup for custom server implementation.
+   * Use this when you want to handle server setup manually.
+   * @default false
+   */
+  customServer?: boolean;
+
+  /**
+   * The output format for server builds.
+   * When omitted, React Router's `serverModuleFormat` selects the emitted
+   * Rsbuild format (`"esm"` -> `"module"`, `"cjs"` -> `"commonjs"`).
+   */
+  serverOutput?: 'module' | 'commonjs';
+
+  /**
+   * Federation mode configuration
+   */
+  federation?: boolean;
+
+  /**
+   * Rsbuild dev-only lazy compilation behavior.
+   *
+   * React Router's browser manifest remains eager so initial dev requests can
+   * discover browser assets without lazy proxy delays.
+   *
+   * 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
+   */
+  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;
+  clientActionModule?: string;
+  clientLoaderModule?: string;
+  clientMiddlewareModule?: string;
+  hydrateFallbackModule?: string;
+  hasAction: boolean;
+  hasLoader: boolean;
+  hasClientAction: boolean;
+  hasClientLoader: boolean;
+  hasClientMiddleware: boolean;
+  hasDefaultExport: boolean;
+  hasErrorBoundary: boolean;
+  imports: string[];
+  css: string[];
+};

package/src/validation/validate-plugin-order.ts

@@ -0,0 +1,76 @@
+import type { RsbuildConfig } from '@rsbuild/core';
+
+function pluginId(name: string) {
+  return `rsbuild:${name}`;
+}
+
+function flattenPlugins(input: unknown): Array<{ name?: string }> {
+  if (!Array.isArray(input)) return [];
+  const out: Array<{ name?: string }> = [];
+  for (const item of input) {
+    if (!item) continue;
+    if (Array.isArray(item)) {
+      out.push(...flattenPlugins(item));
+      continue;
+    }
+    if (typeof (item as any)?.then === 'function') {
+      // Skip promises - normalized config should already be resolved.
+      continue;
+    }
+    if (typeof item === 'object') {
+      out.push(item as any);
+    }
+  }
+  return out;
+}
+
+function indexOfPlugin(plugins: Array<{ name?: string }>, names: string[]) {
+  return plugins.findIndex(p => (p?.name ? names.includes(p.name) : false));
+}
+
+export type PluginOrderIssue =
+  | {
+      kind: 'error';
+      message: string;
+    }
+  | {
+      kind: 'warn';
+      message: string;
+    };
+
+export function validatePluginOrderFromConfig(
+  config: RsbuildConfig
+): PluginOrderIssue[] {
+  const plugins = flattenPlugins(config.plugins);
+  const issues: PluginOrderIssue[] = [];
+
+  // Best-effort port of upstream validate-plugin-order:
+  // - `rsbuild:mdx` must be before `rsbuild:react-router` so that route files
+  //   can be authored in MDX and still have exports parsed correctly.
+  const rrIndex = indexOfPlugin(plugins, ['rsbuild:react-router']);
+  const mdxIndex = indexOfPlugin(plugins, [pluginId('mdx')]);
+  if (rrIndex >= 0 && mdxIndex >= 0 && mdxIndex > rrIndex) {
+    issues.push({
+      kind: 'error',
+      message:
+        `The \"rsbuild:mdx\" plugin should be placed before the React Router plugin ` +
+        `in your Rsbuild config. This ensures route modules authored in MDX are ` +
+        `compiled before React Router inspects route exports.`,
+    });
+  }
+
+  // Rsbuild/React Router expectation: user should also include React support
+  // (JSX transform + refresh). We can only warn since Rsbuild configs may not
+  // use React at all (or may provide a custom JSX pipeline).
+  const hasReact = plugins.some(p => p?.name === pluginId('react'));
+  if (rrIndex >= 0 && !hasReact) {
+    issues.push({
+      kind: 'warn',
+      message:
+        `React Router plugin detected without \"rsbuild:react\". If you are using ` +
+        `JSX/TSX route modules, add \"@rsbuild/plugin-react\" to your plugins list.`,
+    });
+  }
+
+  return issues;
+}

package/src/virtual-modules.ts

@@ -0,0 +1,30 @@
+const VIRTUAL_MODULE_PREFIX = 'virtual/react-router/';
+
+export const getVirtualModuleFilePath = (moduleId: string): string => {
+  if (!moduleId.startsWith(VIRTUAL_MODULE_PREFIX)) {
+    throw new Error(
+      `Virtual module id must start with ${JSON.stringify(VIRTUAL_MODULE_PREFIX)}: ${moduleId}`
+    );
+  }
+
+  const relativeId = moduleId.slice(VIRTUAL_MODULE_PREFIX.length);
+  const segments = relativeId.split('/');
+  if (
+    !relativeId ||
+    segments.some(segment => !segment || segment === '.' || segment === '..')
+  ) {
+    throw new Error(`Invalid virtual module id: ${moduleId}`);
+  }
+
+  return `node_modules/${moduleId}.js`;
+};
+
+export const mapVirtualModules = (
+  modules: Record<string, string>
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(modules).map(([moduleId, contents]) => [
+      getVirtualModuleFilePath(moduleId),
+      contents,
+    ])
+  );

package/src/warnings/warn-on-client-source-maps.ts

@@ -0,0 +1,96 @@
+import type { NormalizedConfig } from '@rsbuild/core';
+
+type Warn = (message: string) => void;
+type ToolsRspackConfig = NonNullable<NormalizedConfig['tools']>['rspack'];
+type SourceMapConfigObject = { js?: unknown };
+
+function isProdBuild(mode?: string): boolean {
+  // Prefer Rsbuild's normalized `mode` (explicit) and fall back to NODE_ENV.
+  return mode === 'production' || process.env.NODE_ENV === 'production';
+}
+
+export function isSourceMapEnabled(value: unknown): boolean {
+  // Rsbuild normalizes `output.sourceMap` into either:
+  //  - boolean
+  //  - { js?: devtool; css: boolean }
+  if (value === true) return true;
+  if (value === false || value == null) return false;
+  if (typeof value === 'string') return true;
+  if (typeof value === 'object') {
+    const js = (value as SourceMapConfigObject).js;
+    // Any truthy devtool string/object means source maps are on for JS.
+    return Boolean(js);
+  }
+  return false;
+}
+
+function isDevtoolSourceMap(value: unknown): boolean {
+  if (value === true) return true;
+  if (value == null || value === false) return false;
+  if (typeof value === 'string') {
+    return value.includes('source-map');
+  }
+  // Unknown object shape - treat as enabled to be safe.
+  return typeof value === 'object';
+}
+
+export function getClientSourceMapSetting(
+  normalized: NormalizedConfig,
+  clientEnvName = 'web'
+): unknown {
+  // Prefer environment setting, fallback to global.
+  return (
+    normalized.environments?.[clientEnvName]?.output?.sourceMap ??
+    normalized.output?.sourceMap
+  );
+}
+
+export function getClientDevtoolSetting(
+  normalized: NormalizedConfig,
+  clientEnvName = 'web'
+): unknown {
+  const envTools = normalized.environments?.[clientEnvName]?.tools?.rspack;
+  const rootTools = normalized.tools?.rspack;
+  return (
+    getDevtoolFromRspackConfig(envTools) ??
+    getDevtoolFromRspackConfig(rootTools)
+  );
+}
+
+function getDevtoolFromRspackConfig(config?: ToolsRspackConfig): unknown {
+  if (!config) return undefined;
+  if (typeof config === 'function') return undefined;
+  if (typeof config !== 'object') return undefined;
+  return (config as { devtool?: unknown }).devtool;
+}
+
+export function warnOnClientSourceMaps(
+  normalized: NormalizedConfig,
+  warn: Warn,
+  clientEnvName = 'web'
+): void {
+  // Only warn on production builds.
+  if (!isProdBuild(normalized.mode)) {
+    return;
+  }
+
+  const sourceMapSetting = getClientSourceMapSetting(normalized, clientEnvName);
+  const devtoolSetting = getClientDevtoolSetting(normalized, clientEnvName);
+  if (
+    !isSourceMapEnabled(sourceMapSetting) &&
+    !isDevtoolSourceMap(devtoolSetting)
+  ) {
+    return;
+  }
+
+  warn(
+    [
+      '',
+      '  WARNING: Source maps are enabled in production',
+      '  This makes your server code publicly visible in the browser.',
+      '  This is highly discouraged! If you insist, ensure that you are using',
+      '  environment variables for secrets and not hard-coding them in your source code.',
+      '',
+    ].join('\n')
+  );
+}

package/src/yuku.ts

@@ -0,0 +1,67 @@
+import {
+  parse as yukuParse,
+  walk,
+  type ParseOptions,
+  type ParseResult,
+} from 'yuku-parser';
+import type { Rspack } from '@rsbuild/core';
+import { print } from 'yuku-codegen';
+
+export const parse = (
+  code: string,
+  options: ParseOptions = {}
+): ParseResult => {
+  const result = yukuParse(code, {
+    ...options,
+    sourceType: options.sourceType ?? 'module',
+    lang: options.lang ?? 'tsx',
+    attachComments: options.attachComments ?? true,
+  });
+  const errors = result.diagnostics.filter(
+    diagnostic => diagnostic.severity === 'error'
+  );
+  if (errors.length > 0) {
+    throw new Error(errors.map(error => error.message).join('\n'));
+  }
+  return result;
+};
+
+export const traverse: typeof walk = walk;
+
+export const generate = (
+  ast: ParseResult | { type: 'Program' },
+  options: {
+    sourceMaps?: boolean;
+    filename?: string;
+    sourceFileName?: string;
+  } = {}
+): { code: string; map: Rspack.RawSourceMap | null } => {
+  const result = 'program' in ast ? ast : { program: ast, lineStarts: [] };
+  const generated = print(result.program as Parameters<typeof print>[0], {
+    comments: true,
+    sourceMaps: options.sourceMaps
+      ? {
+          lineStarts: result.lineStarts,
+          file: options.filename,
+          sourceFileName: options.sourceFileName,
+        }
+      : undefined,
+  });
+  if (generated.errors.length > 0) {
+    throw new Error(generated.errors.map(error => error.message).join('\n'));
+  }
+  const map = generated.map
+    ? {
+        ...generated.map,
+        file: generated.map.file ?? options.filename ?? '',
+        sourceRoot: generated.map.sourceRoot ?? undefined,
+        sourcesContent:
+          generated.map.sourcesContent?.map(source => source ?? '') ??
+          undefined,
+      }
+    : null;
+
+  return { code: generated.code, map };
+};
+
+export type { ParseResult };