rsbuild-plugin-react-router 0.3.0 → 0.3.1

package/src/dev-background-resources.ts

@@ -0,0 +1,255 @@
+import type { RsbuildPluginAPI } from '@rsbuild/core';
+import type { RouteConfigEntry } from '@react-router/dev/routes';
+import * as Effect from 'effect/Effect';
+import { relative } from 'pathe';
+import { PLUGIN_NAME } from './constants.js';
+import {
+  createDelayedPluginTask,
+  DEV_BACKGROUND_STARTUP_DELAY_MS,
+  normalizeEffectError,
+  runPluginEffect,
+  tryPluginPromise,
+} from './effect-runtime.js';
+import {
+  createLazyCompilationPrewarmController,
+  normalizeLazyCompilationPrewarmOptions,
+} from './lazy-compilation-prewarm.js';
+import {
+  configRoutesToRouteManifestEntries,
+  type ReactRouterManifestForDev,
+} from './manifest.js';
+import type { RouteTransformExecutor } from './parallel-route-transforms.js';
+import {
+  createRouteManifestSnapshot,
+  createRouteTopologyWatcher,
+  ensureDevRestartMarker,
+  type WatchFileConfig,
+} from './route-watch.js';
+import type { PluginOptions } from './types.js';
+
+type RegisterReactRouterDevBackgroundResourcesOptions = {
+  api: RsbuildPluginAPI;
+  isBuild: boolean;
+  lazyCompilationPrewarm: PluginOptions['unstableLazyCompilationPrewarm'];
+  routeTransformExecutor: RouteTransformExecutor;
+  routeRestartMarkerPath: string;
+  watchDirectory: string;
+  getRouteTopology: () => Promise<Set<string>>;
+  initialRouteTopology: Set<string>;
+  onRouteTopologyChange: PluginOptions['onRouteTopologyChange'];
+};
+
+type ReactRouterDevBackgroundResources = {
+  setManifest(manifest: ReactRouterManifestForDev): void;
+};
+
+export const createReactRouterRouteTopology = ({
+  appDirectory,
+  rootRouteFile,
+  routeConfig,
+  loadRouteConfig,
+  getRootRoutePath,
+}: {
+  appDirectory: string;
+  rootRouteFile: string;
+  routeConfig: RouteConfigEntry[];
+  loadRouteConfig: () => Promise<RouteConfigEntry[]>;
+  getRootRoutePath: () => string;
+}): {
+  initialRouteTopology: Set<string>;
+  getRouteTopology: () => Promise<Set<string>>;
+} => {
+  const createSnapshot = (
+    routeFile: string,
+    routeConfigEntries: RouteConfigEntry[]
+  ): Set<string> =>
+    createRouteManifestSnapshot([
+      ['root', { path: '', id: 'root', file: routeFile }],
+      ...configRoutesToRouteManifestEntries(appDirectory, routeConfigEntries),
+    ]);
+
+  return {
+    initialRouteTopology: createSnapshot(rootRouteFile, routeConfig),
+    async getRouteTopology() {
+      const latestRouteConfig = await loadRouteConfig();
+      const latestRootRouteFile = relative(appDirectory, getRootRoutePath());
+      return createSnapshot(latestRootRouteFile, latestRouteConfig);
+    },
+  };
+};
+
+export const createReactRouterRouteWatchFiles = ({
+  configWatchPaths,
+  routeConfigWatchPaths,
+  routeRestartMarkerPath,
+  onRouteTopologyChange,
+}: {
+  configWatchPaths: string | string[];
+  routeConfigWatchPaths: string | string[];
+  routeRestartMarkerPath: string;
+  onRouteTopologyChange: PluginOptions['onRouteTopologyChange'];
+}): WatchFileConfig[] => {
+  const watchFiles: WatchFileConfig[] = [
+    {
+      paths: configWatchPaths,
+      type: 'reload-server',
+    },
+  ];
+
+  if (!onRouteTopologyChange) {
+    watchFiles.push(
+      {
+        paths: routeConfigWatchPaths,
+        type: 'reload-server',
+      },
+      {
+        paths: routeRestartMarkerPath,
+        type: 'reload-server',
+      }
+    );
+  }
+
+  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 = ({
+  api,
+  isBuild,
+  lazyCompilationPrewarm,
+  routeTransformExecutor,
+  routeRestartMarkerPath,
+  watchDirectory,
+  getRouteTopology,
+  initialRouteTopology,
+  onRouteTopologyChange,
+}: RegisterReactRouterDevBackgroundResourcesOptions): ReactRouterDevBackgroundResources => {
+  let closeActiveRouteTopologyWatcher: (() => Promise<void>) | undefined;
+  let routeTopologyWatcherClosed = false;
+
+  const reportRouteTopologyWatcherError = (error: unknown): void => {
+    api.logger.warn(
+      `[${PLUGIN_NAME}] Failed to watch route topology changes: ${String(normalizeEffectError(error))}`
+    );
+  };
+
+  const routeTopologyWatcherTask = createDelayedPluginTask({
+    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;
+      }),
+    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}`
+          ),
+      })
+    : null;
+
+  if (!isBuild) {
+    api.onBeforeStartDevServer(() => {
+      routeTopologyWatcherClosed = false;
+    });
+
+    api.onAfterStartDevServer(({ port }) => {
+      lazyCompilationPrewarmController?.setServerOrigin(
+        `http://localhost:${port}`
+      );
+      lazyCompilationPrewarmController?.schedule();
+    });
+
+    api.onAfterDevCompile(() => {
+      scheduleRouteTopologyWatcher();
+      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);
+    },
+  };
+};

package/src/dev-generation.ts

@@ -1,4 +1,6 @@
 import type { RsbuildDevServer, Rspack } from '@rsbuild/core';
+import * as EffectDeferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
 import type { ServerBuild } from 'react-router';
 import {
   evaluateServerBuilds,
@@ -10,11 +12,13 @@ import {
   type DevCompilationIdentity,
   type DevGraphChanges,
   type DevGraphIdentity,
+  type DevRuntimeStats,
   type ReactRouterDevBuildPlan,
   type ReactRouterDevManifestSet,
   type ReactRouterServerBuilds,
   type WebArtifact,
 } from './dev-runtime-artifacts.js';
+import { normalizeEffectError, runPluginEffect } from './effect-runtime.js';
 
 export { snapshotDevChangedFiles } from './dev-runtime-artifacts.js';
 export type {
@@ -26,12 +30,6 @@ export type {
   ReactRouterDevManifestSet,
 } from './dev-runtime-artifacts.js';
 
-type Deferred<T> = {
-  promise: Promise<T>;
-  resolve: (value: T) => void;
-  reject: (error: Error) => void;
-};
-
 type CommittedGeneration = {
   buildsByEntryName: ReactRouterServerBuilds;
   webIdentity: DevCompilationIdentity;
@@ -44,7 +42,7 @@ type RuntimeState =
   | {
       kind: 'starting';
       attemptId: number;
-      readiness: Deferred<CommittedGeneration>;
+      readiness: EffectDeferred.Deferred<CommittedGeneration, Error>;
     }
   | { kind: 'failed'; attemptId: number; error: Error }
   | {
@@ -61,10 +59,10 @@ export type ReactRouterDevRuntime = {
     manifestsByEntryName: ReactRouterDevManifestSet
   ) => void;
   finishAttempt: (
-    stats: Rspack.Stats | Rspack.MultiStats,
+    stats: DevRuntimeStats,
     changes: DevGraphChanges,
     identity: DevGraphIdentity
-  ) => Promise<void>;
+  ) => Promise<'committed' | 'ignored' | 'retry-node'>;
   failAttempt: (error: Error) => void;
   load: (entryName?: string) => Promise<ServerBuild>;
   close: (error?: Error) => void;
@@ -250,18 +248,10 @@ const hasRouteManifestMetadataChanges = (
   return false;
 };
 
-const createDeferred = <T>(): Deferred<T> => {
-  let resolve!: (value: T) => void;
-  let reject!: (error: Error) => void;
-  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
-    resolve = resolvePromise;
-    reject = rejectPromise;
-  });
-  // Compilation can fail before a request asks for the build. Observe the
-  // rejection now while returning the same promise to future callers.
-  void promise.catch(() => undefined);
-  return { promise, resolve, reject };
-};
+const createReadinessDeferred = (): EffectDeferred.Deferred<
+  CommittedGeneration,
+  Error
+> => Effect.runSync(EffectDeferred.make<CommittedGeneration, Error>());
 
 export const createReactRouterDevRuntime = ({
   server,
@@ -276,7 +266,7 @@ export const createReactRouterDevRuntime = ({
   let state: RuntimeState = {
     kind: 'starting',
     attemptId: 0,
-    readiness: createDeferred(),
+    readiness: createReadinessDeferred(),
   };
   const manifestsByCompilation = new WeakMap<
     Rspack.Compilation,
@@ -289,9 +279,8 @@ export const createReactRouterDevRuntime = ({
     try {
       onCssAssetOwnershipChanged(change);
     } catch (cause) {
-      const reason = cause instanceof Error ? cause.message : String(cause);
       onWarning(
-        `[rsbuild-plugin-react-router] Failed to notify the browser after CSS asset ownership changed: ${reason}`
+        `[rsbuild-plugin-react-router] Failed to notify the browser after CSS asset ownership changed: ${normalizeEffectError(cause).message}`
       );
     }
   };
@@ -300,9 +289,8 @@ export const createReactRouterDevRuntime = ({
     try {
       onRouteManifestChanged();
     } catch (cause) {
-      const reason = cause instanceof Error ? cause.message : String(cause);
       onWarning(
-        `[rsbuild-plugin-react-router] Failed to notify the browser after route manifest metadata changed: ${reason}`
+        `[rsbuild-plugin-react-router] Failed to notify the browser after route manifest metadata changed: ${normalizeEffectError(cause).message}`
       );
     }
   };
@@ -352,7 +340,7 @@ export const createReactRouterDevRuntime = ({
     if (state.kind === 'starting') {
       const { readiness } = state;
       state = { kind: 'failed', attemptId, error };
-      readiness.reject(error);
+      Effect.runSync(EffectDeferred.fail(readiness, error));
     } else if (state.kind === 'ready') {
       state = { ...state, pendingAttemptId: null };
     }
@@ -371,7 +359,7 @@ export const createReactRouterDevRuntime = ({
     if (state.kind === 'starting') {
       const { readiness } = state;
       state = { kind: 'ready', committed, pendingAttemptId: null };
-      readiness.resolve(committed);
+      Effect.runSync(EffectDeferred.succeed(readiness, committed));
     } else if (state.kind === 'ready') {
       state = { kind: 'ready', committed, pendingAttemptId: null };
     }
@@ -413,7 +401,7 @@ export const createReactRouterDevRuntime = ({
         state = {
           kind: 'starting',
           attemptId,
-          readiness: createDeferred(),
+          readiness: createReadinessDeferred(),
         };
       } else if (state.kind === 'starting') {
         state = { ...state, attemptId };
@@ -431,10 +419,10 @@ export const createReactRouterDevRuntime = ({
       }
     },
 
-    async finishAttempt(stats, changes, identity): Promise<void> {
+    async finishAttempt(stats, changes, identity) {
       const attemptId = getCurrentAttemptId();
       if (attemptId === null) {
-        return;
+        return 'ignored';
       }
       const webStats = getEnvironmentStats(stats, 'web');
       const nodeStats = getEnvironmentStats(stats, 'node');
@@ -446,13 +434,13 @@ export const createReactRouterDevRuntime = ({
           ),
           true
         );
-        return;
+        return 'ignored';
       }
       if (
         webStats.compilation.needAdditionalPass ||
         nodeStats.compilation.needAdditionalPass
       ) {
-        return;
+        return 'ignored';
       }
       if (webStats.hasErrors() || nodeStats.hasErrors()) {
         rejectAttempt(
@@ -462,7 +450,7 @@ export const createReactRouterDevRuntime = ({
           ),
           false
         );
-        return;
+        return 'ignored';
       }
 
       const webCompilation = webStats.compilation;
@@ -477,14 +465,14 @@ export const createReactRouterDevRuntime = ({
           ),
           true
         );
-        return;
+        return 'ignored';
       }
       const previous = state.kind === 'ready' ? state.committed : undefined;
       const webChanged = !previous || previous.webIdentity !== webIdentity;
       const nodeChanged = !previous || previous.nodeIdentity !== nodeIdentity;
 
       if (!webChanged && !nodeChanged) {
-        return;
+        return 'ignored';
       }
 
       const manifestsByEntryName = webChanged
@@ -498,7 +486,7 @@ export const createReactRouterDevRuntime = ({
           ),
           true
         );
-        return;
+        return 'ignored';
       }
       const cssAssetsRemoved =
         !!previous &&
@@ -527,21 +515,25 @@ export const createReactRouterDevRuntime = ({
           previous.web.manifestsByEntryName,
           manifestsByEntryName
         );
-      const reusePreviousNodeBuild = !!previous && cssOnlyWebManifestChange;
+      const reusePreviousNodeBuild =
+        !!previous &&
+        cssOnlyWebManifestChange &&
+        (!nodeChanged || identity.nodeWeb !== webIdentity);
 
       if (
         nodeChanged &&
         identity.nodeWeb !== webIdentity &&
+        !identity.attempt &&
         !reusePreviousNodeBuild
       ) {
         const message =
           '[rsbuild-plugin-react-router] Discarded web and node results from different compiler cycles and kept the last-good build.';
         if (!previous) {
-          return;
+          return 'retry-node';
         }
         onWarning(message);
         rejectAttempt(attemptId, new Error(message), false);
-        return;
+        return 'retry-node';
       }
 
       const shouldEvaluateNode = nodeChanged && !reusePreviousNodeBuild;
@@ -551,7 +543,7 @@ export const createReactRouterDevRuntime = ({
         !cssOnlyWebManifestChange &&
         discardUnsafeOneSidedResult(attemptId, previous, webChanged, changes)
       ) {
-        return;
+        return 'ignored';
       }
 
       try {
@@ -559,7 +551,7 @@ export const createReactRouterDevRuntime = ({
           ? await evaluateServerBuilds(server, buildPlan.entryNames)
           : previous!.buildsByEntryName;
         if (!isCurrentAttempt(attemptId)) {
-          return;
+          return 'ignored';
         }
         const web = webChanged
           ? {
@@ -583,7 +575,7 @@ export const createReactRouterDevRuntime = ({
             : previous!.nodeDependencies,
         });
         if (!committed) {
-          return;
+          return 'ignored';
         }
         if (cssAssetsRemoved) {
           reloadAfterCssRemoval = !cssAssetsAdded;
@@ -597,12 +589,10 @@ export const createReactRouterDevRuntime = ({
         if (routeManifestMetadataChanged) {
           notifyRouteManifestChanged();
         }
+        return 'committed';
       } catch (cause) {
-        rejectAttempt(
-          attemptId,
-          cause instanceof Error ? cause : new Error(String(cause)),
-          true
-        );
+        rejectAttempt(attemptId, normalizeEffectError(cause), true);
+        return 'ignored';
       }
     },
 
@@ -625,11 +615,11 @@ export const createReactRouterDevRuntime = ({
         return Promise.resolve(selectBuild(state.committed, entryName));
       }
       if (state.kind === 'starting') {
-        const selected = state.readiness.promise.then(generation =>
-          selectBuild(generation, entryName)
+        const selected = runPluginEffect(
+          EffectDeferred.await(state.readiness).pipe(
+            Effect.map(generation => selectBuild(generation, entryName))
+          )
         );
-        // Compilation may fail before the request awaiting this selection has
-        // a chance to attach its own rejection handler.
         void selected.catch(() => undefined);
         return selected;
       }
@@ -646,7 +636,7 @@ export const createReactRouterDevRuntime = ({
           '[rsbuild-plugin-react-router] The development server closed before a React Router build was ready.'
         );
       if (state.kind === 'starting') {
-        state.readiness.reject(closeError);
+        Effect.runSync(EffectDeferred.fail(state.readiness, closeError));
       }
       state = { kind: 'closed', error: closeError };
     },

package/src/dev-runtime-artifacts.ts

@@ -1,8 +1,11 @@
 import { isAbsolute, relative } from 'node:path';
 import type { RsbuildDevServer, Rspack } from '@rsbuild/core';
+import * as Effect from 'effect/Effect';
 import type { ServerBuild } from 'react-router';
 import type { ReactRouterManifestForDev } from './manifest.js';
-import { resolveServerBuildModule } from './server-utils.js';
+import { getCappedPluginConcurrency } from './concurrency.js';
+import { runPluginEffect, tryPluginPromise } from './effect-runtime.js';
+import { resolveServerBuildModuleEffect } from './server-build-resolution.js';
 
 export type ReactRouterDevManifest = ReactRouterManifestForDev;
 
@@ -17,6 +20,13 @@ export type ReactRouterDevManifestSet = Readonly<
 
 export type ReactRouterServerBuilds = Readonly<Record<string, ServerBuild>>;
 
+export type PairedDevStats = {
+  web: Rspack.Stats;
+  node: Rspack.Stats;
+};
+
+export type DevRuntimeStats = Rspack.Stats | Rspack.MultiStats | PairedDevStats;
+
 export type DependencySnapshot = {
   files: ReadonlySet<string>;
   contexts: ReadonlySet<string>;
@@ -34,11 +44,13 @@ export type DevGraphChanges = {
 };
 
 export type DevCompilationIdentity = symbol;
+export type DevCompileAttemptIdentity = symbol;
 
 export type DevGraphIdentity = {
   web: DevCompilationIdentity | undefined;
   node: DevCompilationIdentity | undefined;
   nodeWeb: DevCompilationIdentity | undefined;
+  attempt: DevCompileAttemptIdentity | undefined;
 };
 
 export type WebArtifact = {
@@ -102,10 +114,17 @@ export const isSafeOneSidedChange = (
   return true;
 };
 
+export const isPairedDevStats = (
+  stats: DevRuntimeStats
+): stats is PairedDevStats => 'web' in stats && 'node' in stats;
+
 export const getEnvironmentStats = (
-  stats: Rspack.Stats | Rspack.MultiStats,
+  stats: DevRuntimeStats,
   name: 'web' | 'node'
 ): Rspack.Stats | undefined => {
+  if (isPairedDevStats(stats)) {
+    return stats[name];
+  }
   const children = Array.isArray((stats as Rspack.MultiStats).stats)
     ? (stats as Rspack.MultiStats).stats
     : [stats as Rspack.Stats];
@@ -115,29 +134,42 @@ export const getEnvironmentStats = (
   });
 };
 
-const evaluateServerBuild = async (
+const startServerBuildEvaluationEffect = (
   server: RsbuildDevServer,
   entryName: string
-): Promise<ServerBuild> => {
-  const loaded = await server.environments.node.loadBundle(entryName);
-  return resolveServerBuildModule(
-    loaded,
-    `Server entry ${JSON.stringify(entryName)}`
+): Effect.Effect<ServerBuild, Error, never> =>
+  tryPluginPromise(() => server.environments.node.loadBundle(entryName)).pipe(
+    Effect.flatMap(buildModule =>
+      resolveServerBuildModuleEffect(
+        buildModule,
+        `Server entry ${JSON.stringify(entryName)}`
+      )
+    )
   );
-};
 
-export const evaluateServerBuilds = async (
+const evaluateServerBuildsEffect = (
   server: RsbuildDevServer,
   entryNames: readonly string[]
-): Promise<ReactRouterServerBuilds> => {
-  const evaluated = await Promise.all(
-    entryNames.map(async entryName => [
-      entryName,
-      await evaluateServerBuild(server, entryName),
-    ])
+): Effect.Effect<ReactRouterServerBuilds, Error, never> =>
+  Effect.forEach(
+    entryNames.map(entryName =>
+      startServerBuildEvaluationEffect(server, entryName).pipe(
+        Effect.map(build => [entryName, build] as const)
+      )
+    ),
+    evaluation => evaluation,
+    { concurrency: getCappedPluginConcurrency() }
+  ).pipe(
+    Effect.map(
+      evaluated => Object.fromEntries(evaluated) as Record<string, ServerBuild>
+    )
   );
-  return Object.fromEntries(evaluated) as Record<string, ServerBuild>;
-};
+
+export const evaluateServerBuilds = (
+  server: RsbuildDevServer,
+  entryNames: readonly string[]
+): Promise<ReactRouterServerBuilds> =>
+  runPluginEffect(evaluateServerBuildsEffect(server, entryNames));
 
 const assertBuildMatchesManifest = (
   entryName: string,