rsbuild-plugin-react-router 0.5.0 → 0.6.0

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,11 +7,10 @@ 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 {
@@ -19,8 +18,8 @@ import {
   type ReactRouterManifestForDev,
 } from './manifest.js';
 import {
+  acquireRouteTopologyWatcher,
   createRouteManifestSnapshot,
-  createRouteTopologyWatcher,
   ensureDevRestartMarker,
   type WatchFileConfig,
 } from './route-watch.js';
@@ -28,6 +27,7 @@ import type { PluginOptions } from './types.js';
 
 type RegisterReactRouterDevBackgroundResourcesOptions = {
   api: RsbuildPluginAPI;
+  runtime: PluginEffectRuntime;
   isBuild: boolean;
   lazyCompilationPrewarm: PluginOptions['unstableLazyCompilationPrewarm'];
   routeRestartMarkerPath: string;
@@ -98,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,
@@ -110,27 +113,9 @@ 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,
   routeRestartMarkerPath,
@@ -138,9 +123,8 @@ export const registerReactRouterDevBackgroundResources = ({
   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(
@@ -149,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 }) => {
@@ -207,31 +186,13 @@ export const registerReactRouterDevBackgroundResources = ({
     });
 
     api.onAfterDevCompile(() => {
-      scheduleRouteTopologyWatcher();
+      if (!routeTopologyWatcherStarted) {
+        routeTopologyWatcherTask.schedule();
+      }
       lazyCompilationPrewarmController?.schedule();
     });
   }
 
-  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
-    );
-  };
-
-  api.onCloseDevServer(() =>
-    closeAll(
-      '[rsbuild-plugin-react-router] Failed to close dev server resources.',
-      [closeRouteTopologyWatcher, closeLazyCompilationPrewarm]
-    )
-  );
-
   return {
     setManifest(manifest) {
       lazyCompilationPrewarmController?.setManifest(manifest);

package/src/dev-generation.ts

@@ -1,7 +1,9 @@
 import type { RsbuildDevServer, Rspack } from '@rsbuild/core';
 import * as EffectDeferred from 'effect/Deferred';
 import * as Effect from 'effect/Effect';
+import * as FiberId from 'effect/FiberId';
 import type { ServerBuild } from 'react-router';
+import { HMR_PATCHABLE_ROUTE_FLAGS } from './route-artifacts.js';
 import {
   evaluateServerBuilds,
   getEnvironmentStats,
@@ -20,14 +22,10 @@ import {
 } from './dev-runtime-artifacts.js';
 import { normalizeEffectError, runPluginEffect } from './effect-runtime.js';
 
-export { snapshotDevChangedFiles } from './dev-runtime-artifacts.js';
 export type {
-  DevChangedFiles,
   DevGraphChanges,
   DevGraphIdentity,
-  ReactRouterDevBuildPlan,
   ReactRouterDevManifest,
-  ReactRouterDevManifestSet,
 } from './dev-runtime-artifacts.js';
 
 type CommittedGeneration = {
@@ -73,7 +71,9 @@ type CreateReactRouterDevRuntimeOptions = {
   buildPlan: ReactRouterDevBuildPlan;
   onEvaluationError: (error: Error) => void;
   onCssAssetOwnershipChanged?: (change: 'removed' | 'restored') => void;
-  onRouteManifestChanged?: () => void;
+  onRouteManifestChanged?: (
+    manifest: ReactRouterDevManifestSet[string]
+  ) => void;
   onWarning?: (message: string) => void;
 };
 
@@ -199,28 +199,35 @@ type DevRouteManifestEntry = NonNullable<
 
 const hasSameRouteMetadata = (
   previous: DevRouteManifestEntry,
-  next: DevRouteManifestEntry
-): boolean =>
-  previous.caseSensitive === next.caseSensitive &&
-  previous.clientActionModule === next.clientActionModule &&
-  previous.clientLoaderModule === next.clientLoaderModule &&
-  previous.clientMiddlewareModule === next.clientMiddlewareModule &&
-  previous.hasErrorBoundary === next.hasErrorBoundary &&
-  previous.hasAction === next.hasAction &&
-  previous.hasClientAction === next.hasClientAction &&
-  previous.hasClientLoader === next.hasClientLoader &&
-  previous.hasClientMiddleware === next.hasClientMiddleware &&
-  previous.hasDefaultExport === next.hasDefaultExport &&
-  previous.hasLoader === next.hasLoader &&
-  previous.hydrateFallbackModule === next.hydrateFallbackModule &&
-  previous.id === next.id &&
-  previous.index === next.index &&
-  previous.parentId === next.parentId &&
-  previous.path === next.path;
+  next: DevRouteManifestEntry,
+  includeHmrPatchableFlags: boolean
+): boolean => {
+  const structuralEqual =
+    previous.caseSensitive === next.caseSensitive &&
+    previous.clientActionModule === next.clientActionModule &&
+    previous.clientLoaderModule === next.clientLoaderModule &&
+    previous.clientMiddlewareModule === next.clientMiddlewareModule &&
+    previous.hasDefaultExport === next.hasDefaultExport &&
+    previous.hydrateFallbackModule === next.hydrateFallbackModule &&
+    previous.id === next.id &&
+    previous.index === next.index &&
+    previous.parentId === next.parentId &&
+    previous.path === next.path;
+  if (!structuralEqual) {
+    return false;
+  }
+  if (!includeHmrPatchableFlags) {
+    return true;
+  }
+  // Without a client-side HMR runtime these flags can only reach the browser
+  // through a full reload.
+  return HMR_PATCHABLE_ROUTE_FLAGS.every(flag => previous[flag] === next[flag]);
+};
 
 const hasRouteManifestMetadataChanges = (
   previous: ReactRouterDevManifestSet,
-  next: ReactRouterDevManifestSet
+  next: ReactRouterDevManifestSet,
+  includeHmrPatchableFlags: boolean
 ): boolean => {
   const previousEntryNames = Object.keys(previous);
   if (previousEntryNames.length !== Object.keys(next).length) {
@@ -240,7 +247,14 @@ const hasRouteManifestMetadataChanges = (
     for (const routeId of previousRouteIds) {
       const previousRoute = previousRoutes[routeId];
       const nextRoute = nextRoutes[routeId];
-      if (!nextRoute || !hasSameRouteMetadata(previousRoute, nextRoute)) {
+      if (
+        !nextRoute ||
+        !hasSameRouteMetadata(
+          previousRoute,
+          nextRoute,
+          includeHmrPatchableFlags
+        )
+      ) {
         return true;
       }
     }
@@ -251,7 +265,7 @@ const hasRouteManifestMetadataChanges = (
 const createReadinessDeferred = (): EffectDeferred.Deferred<
   CommittedGeneration,
   Error
-> => Effect.runSync(EffectDeferred.make<CommittedGeneration, Error>());
+> => EffectDeferred.unsafeMake<CommittedGeneration, Error>(FiberId.none);
 
 export const createReactRouterDevRuntime = ({
   server,
@@ -285,9 +299,11 @@ export const createReactRouterDevRuntime = ({
     }
   };
 
-  const notifyRouteManifestChanged = (): void => {
+  const notifyRouteManifestChanged = (
+    manifest: ReactRouterDevManifestSet[string]
+  ): void => {
     try {
-      onRouteManifestChanged();
+      onRouteManifestChanged(manifest);
     } catch (cause) {
       onWarning(
         `[rsbuild-plugin-react-router] Failed to notify the browser after route manifest metadata changed: ${normalizeEffectError(cause).message}`
@@ -340,7 +356,7 @@ export const createReactRouterDevRuntime = ({
     if (state.kind === 'starting') {
       const { readiness } = state;
       state = { kind: 'failed', attemptId, error };
-      Effect.runSync(EffectDeferred.fail(readiness, error));
+      EffectDeferred.unsafeDone(readiness, Effect.fail(error));
     } else if (state.kind === 'ready') {
       state = { ...state, pendingAttemptId: null };
     }
@@ -359,7 +375,7 @@ export const createReactRouterDevRuntime = ({
     if (state.kind === 'starting') {
       const { readiness } = state;
       state = { kind: 'ready', committed, pendingAttemptId: null };
-      Effect.runSync(EffectDeferred.succeed(readiness, committed));
+      EffectDeferred.unsafeDone(readiness, Effect.succeed(committed));
     } else if (state.kind === 'ready') {
       state = { kind: 'ready', committed, pendingAttemptId: null };
     }
@@ -513,7 +529,8 @@ export const createReactRouterDevRuntime = ({
         webChanged &&
         hasRouteManifestMetadataChanges(
           previous.web.manifestsByEntryName,
-          manifestsByEntryName
+          manifestsByEntryName,
+          true
         );
       const reusePreviousNodeBuild =
         !!previous &&
@@ -587,7 +604,9 @@ export const createReactRouterDevRuntime = ({
           reloadAfterCssRemoval = false;
         }
         if (routeManifestMetadataChanged) {
-          notifyRouteManifestChanged();
+          notifyRouteManifestChanged(
+            web.manifestsByEntryName[buildPlan.defaultEntryName]
+          );
         }
         return 'committed';
       } catch (cause) {
@@ -636,7 +655,7 @@ export const createReactRouterDevRuntime = ({
           '[rsbuild-plugin-react-router] The development server closed before a React Router build was ready.'
         );
       if (state.kind === 'starting') {
-        Effect.runSync(EffectDeferred.fail(state.readiness, closeError));
+        EffectDeferred.unsafeDone(state.readiness, Effect.fail(closeError));
       }
       state = { kind: 'closed', error: closeError };
     },