rsbuild-plugin-react-router 0.4.1 → 0.6.0

package/src/classic-mode.ts

@@ -0,0 +1,253 @@
+import { readFileSync } from 'node:fs';
+import type { RsbuildEntryDescription, RsbuildPluginAPI } from '@rsbuild/core';
+import type { RouteConfigEntry } from '@react-router/dev/routes';
+import { resolve } from 'pathe';
+import {
+  getBuildManifest,
+  getRoutesByServerBundleId,
+} from './build-manifest.js';
+import { BUILD_CLIENT_ROUTE_QUERY_STRING } from './constants.js';
+import {
+  DEV_HMR_RUNTIME_MODULE_ID,
+  type DevHmrPlanOptions,
+} from './dev-hmr.js';
+import {
+  createReactRouterDevRuntimeController,
+  type ReactRouterDevRuntimeController,
+} from './dev-runtime-controller.js';
+import { generateWithProps } from './plugin-utils.js';
+import { resolvePrerenderPaths } from './prerender.js';
+import { generateServerBuild } from './server-utils.js';
+import {
+  createReactRouterServerBuildPlan,
+  type ReactRouterServerBundleEntry,
+} from './server-build-plan.js';
+import {
+  getRouteChunkEntryName,
+  getRouteChunkModuleId,
+  routeChunkExportNames,
+} from './route-chunks.js';
+import type { Config } from './react-router-config.js';
+import type { Route } from './types.js';
+
+type CreateClassicWebRouteEntriesOptions = {
+  appDirectory: string;
+  isBuild: boolean;
+  routes: Record<string, Route>;
+  splitRouteModules: boolean;
+};
+
+type CreateClassicVirtualModulesOptions = {
+  allowedActionOrigins: string[] | undefined;
+  appDirectory: string;
+  assetsBuildDirectory: string;
+  basename: string;
+  devHmrRuntimeModule?: string;
+  entryServerPath: string;
+  future: Config['future'];
+  isSpaMode: boolean;
+  prerenderPaths: string[];
+  publicPath: string;
+  routeDiscovery: Config['routeDiscovery'];
+  routes: Record<string, Route>;
+  routesByServerBundleId: Record<string, Record<string, Route>>;
+  ssr: boolean;
+};
+
+type CreateClassicBuildArtifactsOptions = {
+  api: RsbuildPluginAPI;
+  defaultEntryName: string;
+  isBuild: boolean;
+  prerenderConfig: Config['prerender'];
+  reactRouterConfig: Required<
+    Pick<
+      Config,
+      'appDirectory' | 'buildDirectory' | 'serverBuildFile' | 'future'
+    >
+  > &
+    Pick<Config, 'serverBundles'>;
+  routeConfig: RouteConfigEntry[];
+  routes: Record<string, Route>;
+  rootDirectory: string;
+  ssr: boolean;
+  devHmr?: DevHmrPlanOptions;
+};
+
+export type ClassicBuildArtifacts = {
+  buildManifest: Awaited<ReturnType<typeof getBuildManifest>>;
+  devRuntime: ReactRouterDevRuntimeController;
+  prerenderPaths: string[];
+  routesByServerBundleId: Record<string, Record<string, Route>>;
+  serverBundleEntries: ReactRouterServerBundleEntry[];
+};
+
+export const createClassicBuildArtifacts = async ({
+  api,
+  defaultEntryName,
+  isBuild,
+  prerenderConfig,
+  reactRouterConfig,
+  routeConfig,
+  routes,
+  rootDirectory,
+  ssr,
+  devHmr,
+}: CreateClassicBuildArtifactsOptions): Promise<ClassicBuildArtifacts> => {
+  const buildManifest = await getBuildManifest({
+    reactRouterConfig,
+    routes,
+    rootDirectory,
+  });
+  const routesByServerBundleId = getRoutesByServerBundleId(
+    buildManifest,
+    routes
+  );
+  const serverBuildPlan = createReactRouterServerBuildPlan({
+    routesByServerBundleId,
+    serverBuildFile: reactRouterConfig.serverBuildFile,
+    defaultEntryName,
+  });
+  const prerenderPaths = await resolvePrerenderPaths(
+    prerenderConfig,
+    ssr,
+    routeConfig,
+    {
+      logWarning: true,
+      warn: message => api.logger.warn(message),
+    }
+  );
+
+  return {
+    buildManifest,
+    devRuntime: createReactRouterDevRuntimeController({
+      api,
+      isBuild,
+      buildPlan: serverBuildPlan,
+      clientPatchesRouteMetadata: devHmr?.isEnabled,
+      onNodeRebuildCommitted: devHmr?.onNodeRebuildCommitted,
+    }),
+    prerenderPaths,
+    routesByServerBundleId,
+    serverBundleEntries: serverBuildPlan.serverBundleEntries,
+  };
+};
+
+export const createClassicWebRouteEntries = ({
+  appDirectory,
+  isBuild,
+  routes,
+  splitRouteModules,
+}: CreateClassicWebRouteEntriesOptions): {
+  manifestChunkNames: Set<string>;
+  webRouteEntries: Record<string, RsbuildEntryDescription>;
+} => {
+  const manifestChunkNames = new Set<string>(['entry.client']);
+  const webRouteEntries = Object.values(routes).reduce(
+    (acc, route) => {
+      const entryName = route.file.slice(0, route.file.lastIndexOf('.'));
+      const routeFilePath = resolve(appDirectory, route.file);
+      manifestChunkNames.add(entryName);
+      acc[entryName] = {
+        import: `${routeFilePath}${BUILD_CLIENT_ROUTE_QUERY_STRING}`,
+        html: false,
+      };
+
+      if (isBuild && splitRouteModules && route.id !== 'root') {
+        let source: string;
+        try {
+          source = readFileSync(routeFilePath, 'utf8');
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return acc;
+          }
+          throw error;
+        }
+        for (const exportName of routeChunkExportNames) {
+          if (!source.includes(exportName)) {
+            continue;
+          }
+          const chunkEntryName = getRouteChunkEntryName(route.id, exportName);
+          manifestChunkNames.add(chunkEntryName);
+          acc[chunkEntryName] = {
+            import: getRouteChunkModuleId(routeFilePath, exportName),
+            html: false,
+          };
+        }
+      }
+
+      return acc;
+    },
+    {} as Record<string, RsbuildEntryDescription>
+  );
+
+  return {
+    manifestChunkNames,
+    webRouteEntries,
+  };
+};
+
+export const createClassicVirtualModules = ({
+  allowedActionOrigins,
+  appDirectory,
+  assetsBuildDirectory,
+  basename,
+  devHmrRuntimeModule,
+  entryServerPath,
+  future,
+  isSpaMode,
+  prerenderPaths,
+  publicPath,
+  routeDiscovery,
+  routes,
+  routesByServerBundleId,
+  ssr,
+}: CreateClassicVirtualModulesOptions): Record<string, string> => {
+  const serverBuildOptions = {
+    entryServerPath,
+    assetsBuildDirectory,
+    basename,
+    appDirectory,
+    ssr,
+    isSpaMode,
+    future,
+    allowedActionOrigins,
+    prerender: prerenderPaths,
+    routeDiscovery,
+    publicPath,
+  };
+  const bundleVirtualModules = Object.fromEntries(
+    Object.entries(routesByServerBundleId).map(([bundleId, bundleRoutes]) => [
+      `virtual/react-router/server-build-${bundleId}`,
+      generateServerBuild(bundleRoutes, {
+        ...serverBuildOptions,
+        serverManifestId: `virtual/react-router/server-manifest-${bundleId}`,
+      }),
+    ])
+  );
+  const bundleManifestModules = Object.fromEntries(
+    Object.entries(routesByServerBundleId)
+      .filter(
+        ([, bundleRoutes]) =>
+          bundleRoutes && Object.keys(bundleRoutes).length > 0
+      )
+      .map(([bundleId]) => [
+        `virtual/react-router/server-manifest-${bundleId}`,
+        'export default {};',
+      ])
+  );
+
+  return {
+    'virtual/react-router/browser-manifest': 'export default {};',
+    'virtual/react-router/server-manifest': 'export default {};',
+    'virtual/react-router/server-build': generateServerBuild(
+      routes,
+      serverBuildOptions
+    ),
+    ...bundleVirtualModules,
+    ...bundleManifestModules,
+    'virtual/react-router/with-props': generateWithProps(),
+    ...(devHmrRuntimeModule !== undefined
+      ? { [DEV_HMR_RUNTIME_MODULE_ID]: devHmrRuntimeModule }
+      : {}),
+  };
+};

package/src/config-imports.ts

@@ -1,14 +1,162 @@
-import type { ModuleCache } from 'jiti';
+import type { JitiOptions, ModuleCache, TransformOptions } from 'jiti';
 import { createJiti } from 'jiti';
 import { resolve } from 'pathe';
+import { parse } from './yuku.js';
 
-type ConfigImporter = Pick<ReturnType<typeof createJiti>, 'import'>;
+export type ConfigImporter = Pick<ReturnType<typeof createJiti>, 'import'>;
+
+type ConfigImportOptions = {
+  define?: Record<string, unknown>;
+  moduleCache?: boolean;
+};
 
 const normalizePath = (filePath: string): string => resolve(filePath);
 
 const isNodeModulePath = (filePath: string): boolean =>
   filePath.split(/[\\/]/).includes('node_modules');
 
+type AstNode = {
+  type?: string;
+  start?: number;
+  end?: number;
+  object?: AstNode;
+  property?: AstNode;
+  meta?: AstNode;
+  name?: string;
+  value?: unknown;
+  computed?: boolean;
+};
+
+const normalizeDefineValue = (value: unknown): string | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  return JSON.stringify(value);
+};
+
+const getMemberExpressionName = (node: AstNode | undefined): string | null => {
+  if (!node) {
+    return null;
+  }
+  if (node.type === 'Identifier') {
+    return node.name ?? null;
+  }
+  if (node.type === 'MetaProperty') {
+    const meta = getMemberExpressionName(node.meta);
+    const property = getMemberExpressionName(node.property);
+    return meta && property ? `${meta}.${property}` : null;
+  }
+  if (node.type !== 'MemberExpression') {
+    return null;
+  }
+  const object = getMemberExpressionName(node.object);
+  const property =
+    node.computed && typeof node.property?.value === 'string'
+      ? node.property.value
+      : getMemberExpressionName(node.property);
+  return object && property ? `${object}.${property}` : null;
+};
+
+const collectDefineReplacements = (
+  node: unknown,
+  define: ReadonlyMap<string, string>,
+  replacements: Array<{ start: number; end: number; value: string }>
+): void => {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+
+  const astNode = node as AstNode;
+  const memberName = getMemberExpressionName(astNode);
+  const value = memberName ? define.get(memberName) : undefined;
+  if (
+    value !== undefined &&
+    typeof astNode.start === 'number' &&
+    typeof astNode.end === 'number'
+  ) {
+    replacements.push({
+      start: astNode.start,
+      end: astNode.end,
+      value,
+    });
+    return;
+  }
+
+  for (const child of Object.values(node)) {
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        collectDefineReplacements(item, define, replacements);
+      }
+      continue;
+    }
+    collectDefineReplacements(child, define, replacements);
+  }
+};
+
+export const applyConfigDefines = (
+  source: string,
+  define: Record<string, unknown> | undefined
+): string => {
+  if (!define) {
+    return source;
+  }
+
+  const normalizedDefine = new Map(
+    Object.entries(define).flatMap(([key, value]) => {
+      const normalized = normalizeDefineValue(value);
+      return normalized === undefined ? [] : [[key, normalized]];
+    })
+  );
+  if (normalizedDefine.size === 0) {
+    return source;
+  }
+
+  const replacements: Array<{ start: number; end: number; value: string }> = [];
+  collectDefineReplacements(
+    parse(source, { sourceType: 'module' }),
+    normalizedDefine,
+    replacements
+  );
+
+  return replacements
+    .sort((left, right) => right.start - left.start)
+    .reduce(
+      (contents, replacement) =>
+        `${contents.slice(0, replacement.start)}${replacement.value}${contents.slice(
+          replacement.end
+        )}`,
+      source
+    );
+};
+
+export const createConfigImporter = ({
+  define,
+  moduleCache = true,
+}: ConfigImportOptions = {}): ReturnType<typeof createJiti> => {
+  const defaultJiti = createJiti(process.cwd(), { moduleCache });
+  if (!define || Object.keys(define).length === 0) {
+    return defaultJiti;
+  }
+
+  const defaultTransform = defaultJiti.transform;
+  const options = {
+    moduleCache,
+    transform(transformOptions: TransformOptions) {
+      return {
+        code: defaultTransform({
+          ...transformOptions,
+          source: applyConfigDefines(transformOptions.source, define),
+        }),
+      };
+    },
+  } satisfies JitiOptions;
+
+  return createJiti(process.cwd(), options);
+};
+
 export const collectConfigImportWatchPaths = (
   configPath: string,
   moduleCache: ModuleCache,
@@ -50,11 +198,10 @@ export const clearConfigImportCache = (
 export const importConfigWithWatchPaths = async <T>(
   configPath: string,
   load: (importer: ConfigImporter) => PromiseLike<T> | T = async importer =>
-    importer.import<T>(configPath, { default: true })
+    importer.import<T>(configPath, { default: true }),
+  options?: ConfigImportOptions
 ): Promise<{ value: Awaited<T>; watchPaths: string | string[] }> => {
-  const jiti = createJiti(process.cwd(), {
-    moduleCache: true,
-  });
+  const jiti = createConfigImporter({ moduleCache: true, ...options });
   const previousCacheKeys = new Set(Object.keys(jiti.cache));
   let importPaths: string[] = [];
 

package/src/constants.ts

@@ -1,5 +1,8 @@
 export const PLUGIN_NAME = 'rsbuild:react-router';
 
+/** Default web `output.distPath.js` segment when the user has not customized it. */
+export const DEFAULT_JS_DIST_PATH = 'static/js';
+
 export const JS_EXTENSIONS = [
   '.tsx',
   '.ts',
@@ -32,8 +35,6 @@ export const SERVER_ONLY_ROUTE_EXPORTS_SET: ReadonlySet<string> = new Set(
   SERVER_ONLY_ROUTE_EXPORTS
 );
 
-// Client route exports are split into non-component exports and component exports.
-// This mirrors upstream React Router Vite plugin intent and is used for export filtering.
 export const CLIENT_NON_COMPONENT_EXPORTS = [
   'clientAction',
   'clientLoader',
@@ -89,3 +90,6 @@ export const CLIENT_EXPORTS = {
   meta: 'meta',
   shouldRevalidate: 'shouldRevalidate',
 } as const;
+
+// SPA-mode prerender fallback document, served when no prerendered page matches.
+export const SPA_FALLBACK_HTML_FILE = '__spa-fallback.html';

package/src/dev-background-resources.ts

@@ -7,21 +7,19 @@ import {
   createDelayedPluginTask,
   DEV_BACKGROUND_STARTUP_DELAY_MS,
   normalizeEffectError,
-  runPluginEffect,
-  tryPluginPromise,
+  type PluginEffectRuntime,
 } from './effect-runtime.js';
 import {
-  createLazyCompilationPrewarmController,
+  acquireLazyCompilationPrewarm,
   normalizeLazyCompilationPrewarmOptions,
 } from './lazy-compilation-prewarm.js';
 import {
   configRoutesToRouteManifestEntries,
   type ReactRouterManifestForDev,
 } from './manifest.js';
-import type { RouteTransformExecutor } from './parallel-route-transforms.js';
 import {
+  acquireRouteTopologyWatcher,
   createRouteManifestSnapshot,
-  createRouteTopologyWatcher,
   ensureDevRestartMarker,
   type WatchFileConfig,
 } from './route-watch.js';
@@ -29,9 +27,9 @@ import type { PluginOptions } from './types.js';
 
 type RegisterReactRouterDevBackgroundResourcesOptions = {
   api: RsbuildPluginAPI;
+  runtime: PluginEffectRuntime;
   isBuild: boolean;
   lazyCompilationPrewarm: PluginOptions['unstableLazyCompilationPrewarm'];
-  routeTransformExecutor: RouteTransformExecutor;
   routeRestartMarkerPath: string;
   watchDirectory: string;
   getRouteTopology: () => Promise<Set<string>>;
@@ -100,7 +98,10 @@ export const createReactRouterRouteWatchFiles = ({
     watchFiles.push(
       {
         paths: routeConfigWatchPaths,
-        type: 'reload-server',
+        // Keep the current compiler alive while a route config is temporarily
+        // invalid. The topology watcher touches the dedicated restart marker
+        // once a valid edit actually changes the route graph.
+        type: 'reload-page',
       },
       {
         paths: routeRestartMarkerPath,
@@ -112,38 +113,18 @@ export const createReactRouterRouteWatchFiles = ({
   return watchFiles;
 };
 
-const closeAll = async (
-  message: string,
-  closers: Array<() => Promise<void>>
-): Promise<void> => {
-  const results = await Promise.allSettled(closers.map(closer => closer()));
-  const errors = results
-    .filter(
-      (result): result is PromiseRejectedResult => result.status === 'rejected'
-    )
-    .map(result => normalizeEffectError(result.reason));
-
-  if (errors.length === 1) {
-    throw errors[0];
-  }
-  if (errors.length > 1) {
-    throw new AggregateError(errors, message);
-  }
-};
-
-export const registerReactRouterDevBackgroundResources = ({
+export const registerReactRouterDevBackgroundResources = async ({
   api,
+  runtime,
   isBuild,
   lazyCompilationPrewarm,
-  routeTransformExecutor,
   routeRestartMarkerPath,
   watchDirectory,
   getRouteTopology,
   initialRouteTopology,
   onRouteTopologyChange,
-}: RegisterReactRouterDevBackgroundResourcesOptions): ReactRouterDevBackgroundResources => {
-  let closeActiveRouteTopologyWatcher: (() => Promise<void>) | undefined;
-  let routeTopologyWatcherClosed = false;
+}: RegisterReactRouterDevBackgroundResourcesOptions): Promise<ReactRouterDevBackgroundResources> => {
+  let routeTopologyWatcherStarted = false;
 
   const reportRouteTopologyWatcherError = (error: unknown): void => {
     api.logger.warn(
@@ -152,54 +133,49 @@ export const registerReactRouterDevBackgroundResources = ({
   };
 
   const routeTopologyWatcherTask = createDelayedPluginTask({
+    runtime,
     delayMs: DEV_BACKGROUND_STARTUP_DELAY_MS,
     run: () =>
-      Effect.gen(function* () {
-        yield* tryPluginPromise(() =>
-          ensureDevRestartMarker(routeRestartMarkerPath)
-        );
-        const closeWatcher = yield* tryPluginPromise(() =>
-          createRouteTopologyWatcher({
-            watchDirectory,
-            getRouteTopology,
-            initialRouteTopology,
-            restartMarkerPath: routeRestartMarkerPath,
-            onRouteTopologyChange,
-            onError: reportRouteTopologyWatcherError,
-          })
-        );
-        if (routeTopologyWatcherClosed) {
-          yield* tryPluginPromise(() => closeWatcher());
-          return;
-        }
-        closeActiveRouteTopologyWatcher = closeWatcher;
-      }),
+      acquireRouteTopologyWatcher({
+        runtime,
+        watchDirectory,
+        getRouteTopology,
+        initialRouteTopology,
+        restartMarkerPath: routeRestartMarkerPath,
+        onRouteTopologyChange,
+        onError: reportRouteTopologyWatcherError,
+      }).pipe(
+        Effect.tap(() =>
+          Effect.sync(() => (routeTopologyWatcherStarted = true))
+        ),
+        Effect.asVoid
+      ),
     onError: reportRouteTopologyWatcherError,
   });
 
-  const scheduleRouteTopologyWatcher = (): void => {
-    if (routeTopologyWatcherClosed || closeActiveRouteTopologyWatcher) {
-      return;
-    }
-    routeTopologyWatcherTask.schedule();
-  };
-
   const lazyCompilationPrewarmConfig = normalizeLazyCompilationPrewarmOptions(
     lazyCompilationPrewarm
   );
   const lazyCompilationPrewarmController = lazyCompilationPrewarmConfig
-    ? createLazyCompilationPrewarmController({
-        config: lazyCompilationPrewarmConfig,
-        onError: error =>
-          api.logger.warn(
-            `[${PLUGIN_NAME}] Lazy compilation prewarm skipped: ${error.message}`
-          ),
-      })
+    ? await runtime.runPromise(
+        acquireLazyCompilationPrewarm({
+          runtime,
+          config: lazyCompilationPrewarmConfig,
+          onError: error =>
+            api.logger.warn(
+              `[${PLUGIN_NAME}] Lazy compilation prewarm skipped: ${error.message}`
+            ),
+        })
+      )
     : null;
 
   if (!isBuild) {
-    api.onBeforeStartDevServer(() => {
-      routeTopologyWatcherClosed = false;
+    await runtime.runPromise(
+      Effect.acquireRelease(Effect.void, routeTopologyWatcherTask.cancelEffect)
+    );
+
+    api.onBeforeStartDevServer(async () => {
+      await ensureDevRestartMarker(routeRestartMarkerPath);
     });
 
     api.onAfterStartDevServer(({ port }) => {
@@ -210,43 +186,13 @@ export const registerReactRouterDevBackgroundResources = ({
     });
 
     api.onAfterDevCompile(() => {
-      scheduleRouteTopologyWatcher();
+      if (!routeTopologyWatcherStarted) {
+        routeTopologyWatcherTask.schedule();
+      }
       lazyCompilationPrewarmController?.schedule();
     });
-
-    // Spawn transform workers now so thread startup overlaps Rsbuild's own
-    // compiler creation instead of delaying the first route transform.
-    routeTransformExecutor.prewarm();
   }
 
-  const closeRouteTopologyWatcher = async (): Promise<void> => {
-    routeTopologyWatcherClosed = true;
-    await runPluginEffect(routeTopologyWatcherTask.cancelEffect());
-    await closeActiveRouteTopologyWatcher?.();
-    closeActiveRouteTopologyWatcher = undefined;
-  };
-
-  const closeLazyCompilationPrewarm = async (): Promise<void> => {
-    await runPluginEffect(
-      lazyCompilationPrewarmController?.cancelEffect() ?? Effect.void
-    );
-  };
-
-  const closeRouteTransformExecutor = (): Promise<void> =>
-    routeTransformExecutor.close();
-
-  api.onCloseDevServer(() =>
-    closeAll(
-      '[rsbuild-plugin-react-router] Failed to close dev server resources.',
-      [
-        closeRouteTopologyWatcher,
-        closeLazyCompilationPrewarm,
-        closeRouteTransformExecutor,
-      ]
-    )
-  );
-  api.onCloseBuild(closeRouteTransformExecutor);
-
   return {
     setManifest(manifest) {
       lazyCompilationPrewarmController?.setManifest(manifest);