rsbuild-plugin-react-router 0.4.1 → 0.6.0

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 };
     },

package/src/dev-hmr.ts

@@ -3,9 +3,14 @@ import { createRequire } from 'node:module';
 import type { Rspack } from '@rsbuild/core';
 import { dirname, join } from 'pathe';
 
-import { HMR_PATCHABLE_ROUTE_FLAGS } from './route-artifacts.js';
-
 export const DEV_HMR_RUNTIME_MODULE_ID = 'virtual/react-router/hmr-runtime';
+export const DEV_MANIFEST_UPDATE_EVENT = 'react-router:manifest-update';
+
+export type DevHmrPlanOptions = {
+  isEnabled: () => boolean;
+  runtimeModule: string;
+  onNodeRebuildCommitted: () => void;
+};
 
 type SwcLoaderOptions = {
   jsc?: { transform?: { react?: { refresh?: boolean } } };
@@ -17,30 +22,21 @@ const isObject = (value: unknown): value is Record<string, unknown> =>
 const isSwcLoader = (loader: unknown): boolean =>
   typeof loader === 'string' && loader.includes('builtin:swc-loader');
 
-const hasReactRefresh = (options: unknown): boolean =>
-  (options as SwcLoaderOptions | undefined)?.jsc?.transform?.react?.refresh ===
-  true;
-
 const readSwcLoaderRefresh = (value: unknown): boolean => {
-  if (Array.isArray(value)) {
-    return value.some(readSwcLoaderRefresh);
-  }
-  if (!isObject(value)) {
-    return false;
-  }
+  if (Array.isArray(value)) return value.some(readSwcLoaderRefresh);
+  if (!isObject(value)) return false;
   if (isSwcLoader(value.loader)) {
-    return hasReactRefresh(value.options);
+    return (
+      (value.options as SwcLoaderOptions | undefined)?.jsc?.transform?.react
+        ?.refresh === true
+    );
   }
   return Object.values(value).some(readSwcLoaderRefresh);
 };
 
 const readRuleSwcRefresh = (rule: unknown): boolean => {
-  if (!isObject(rule)) {
-    return false;
-  }
-  if (isSwcLoader(rule.loader)) {
-    return hasReactRefresh(rule.options);
-  }
+  if (!isObject(rule)) return false;
+  if (isSwcLoader(rule.loader)) return readSwcLoaderRefresh(rule);
   return (
     readSwcLoaderRefresh(rule.use) ||
     readRuleSetSwcRefresh(rule.oneOf) ||
@@ -94,12 +90,11 @@ const hdrRevisionModuleContent = (revision: number): string =>
  * whenever server code changes, which the client answers by revalidating
  * React Router loader data.
  */
-export const DEV_HDR_REVISION_RELATIVE_PATH = '.react-router/hdr-revision.mjs';
-
 export const getDevHdrRevisionFilePath = (rootPath: string): string =>
-  join(rootPath, DEV_HDR_REVISION_RELATIVE_PATH);
+  join(rootPath, '.react-router', 'hdr-revision.mjs');
 
 export type DevHdrRevisionSignal = {
+  filePath: string;
   /** Writes the initial revision module so the first compile can resolve it. */
   ensure: () => void;
   /** Increments the revision, signaling hot data revalidation to the client. */
@@ -127,6 +122,7 @@ export const createDevHdrRevisionSignal = ({
     }
   };
   return {
+    filePath,
     ensure: write,
     bump() {
       revision += 1;
@@ -138,7 +134,7 @@ export const createDevHdrRevisionSignal = ({
 /**
  * Browser-side HMR runtime shared by all route client entries in development.
  *
- * This mirrors React Router's Vite HMR contract (see `refresh-utils.mjs` in
+ * This mirrors React Router framework HMR contract (see `refresh-utils.mjs` in
  * `@react-router/dev`): route module updates are applied by patching
  * `window.__reactRouterRouteModules` while preserving the previous component
  * identities (React Fast Refresh swaps their implementations in place),
@@ -156,7 +152,11 @@ import * as __refreshRuntimeModule from ${JSON.stringify(reactRefreshRuntimePath
 // Read revision so the import survives sideEffects: false tree-shaking.
 import __hdrRevision from ${JSON.stringify(hdrRevisionFilePath)};
 
-void __hdrRevision;
+let latestHdrRevision = __hdrRevision;
+
+export function getReactRouterHdrRevision() {
+  return latestHdrRevision;
+}
 
 const RefreshRuntime =
   __refreshRuntimeModule && __refreshRuntimeModule.performReactRefresh
@@ -166,6 +166,7 @@ const RefreshRuntime =
 const pendingRouteUpdates = new Map();
 let flushTimeout;
 let pendingRevalidation = false;
+let pendingComponentRouteRevalidation = false;
 
 function getCurrentRouterPath(router) {
   const basename = router.basename || '/';
@@ -199,10 +200,10 @@ export function registerReactRouterRouteExports(routeId, moduleExports) {
 
 export function scheduleReactRouterRouteUpdate(
   routeId,
-  routeFlags,
+  routeMetadata,
   getRouteModuleExports
 ) {
-  pendingRouteUpdates.set(routeId, { routeFlags, getRouteModuleExports });
+  pendingRouteUpdates.set(routeId, { routeMetadata, getRouteModuleExports });
   scheduleFlush();
 }
 
@@ -228,16 +229,8 @@ function takePendingRouteUpdates() {
   return updates;
 }
 
-function getRouteMetadata(routeFlags) {
-  return {
-${HMR_PATCHABLE_ROUTE_FLAGS.map(
-  (flag, index) => `    ${flag}: Boolean(routeFlags & ${1 << index}),`
-).join('\n')}
-  };
-}
-
 function applyRouteModuleUpdate(routeId, update, routeEntry, routeModules) {
-  Object.assign(routeEntry, getRouteMetadata(update.routeFlags));
+  Object.assign(routeEntry, update.routeMetadata);
   const imported = update.getRouteModuleExports();
   registerReactRouterRouteExports(routeId, imported);
   const current = routeModules[routeId];
@@ -294,11 +287,7 @@ function patchCurrentRouteMatches(router, routes) {
 
 function applyPendingRouteUpdates(router, routeModules, manifest, context) {
   if (pendingRouteUpdates.size === 0) {
-    return {
-      nextManifest: undefined,
-      shouldRefreshRouteState: false,
-      routesToRevalidate: new Set(),
-    };
+    return { nextManifest: undefined, hmrRoutes: undefined };
   }
 
   // Clone only entries mutated before the manifest is committed in flush().
@@ -309,8 +298,7 @@ function applyPendingRouteUpdates(router, routeModules, manifest, context) {
     const existingEntry = nextManifest.routes[routeId];
     if (!existingEntry) continue;
 
-    // Shallow clone is enough: only top-level flags are mutated below.
-    const routeEntry = { ...existingEntry };
+    const routeEntry = JSON.parse(JSON.stringify(existingEntry));
     nextManifest.routes[routeId] = routeEntry;
     applyRouteModuleUpdate(routeId, update, routeEntry, routeModules);
     if (
@@ -332,54 +320,52 @@ function applyPendingRouteUpdates(router, routeModules, manifest, context) {
     }
   }
 
+  let hmrRoutes;
   if (
     typeof router.createRoutesForHMR === 'function' &&
     typeof router._internalSetRoutes === 'function'
   ) {
-    const routes = router.createRoutesForHMR(
+    hmrRoutes = router.createRoutesForHMR(
       routesToRevalidate,
       nextManifest.routes,
       routeModules,
       context.ssr,
       context.isSpaMode
     );
-    router._internalSetRoutes(routes);
-    patchCurrentRouteMatches(router, routes);
+    router._internalSetRoutes(hmrRoutes);
   }
 
-  return { nextManifest, shouldRefreshRouteState, routesToRevalidate };
+  return { nextManifest, hmrRoutes, shouldRefreshRouteState };
 }
 
-async function withHdrActive(fn) {
+async function revalidateRouter(router) {
   try {
     window.__reactRouterHdrActive = true;
-    await fn();
+    if (typeof router.revalidate === 'function') {
+      await router.revalidate();
+      return;
+    }
+    if (typeof router.navigate === 'function') {
+      await router.navigate(getCurrentRouterPath(router), {
+        replace: true,
+        preventScrollReset: true,
+      });
+    }
   } finally {
     window.__reactRouterHdrActive = false;
   }
 }
 
-async function revalidateRouter(router) {
-  if (typeof router.revalidate === 'function') {
-    await withHdrActive(() => router.revalidate());
+async function refreshRouteState(router) {
+  if (typeof router.revalidate !== 'function') {
     return;
   }
-  if (typeof router.navigate === 'function') {
-    await withHdrActive(() =>
-      router.navigate(getCurrentRouterPath(router), {
-        replace: true,
-        preventScrollReset: true,
-      })
-    );
-  }
-}
-
-async function refreshRouteState(router) {
-  if (typeof router.revalidate === 'function') {
-    await withHdrActive(() => router.revalidate());
-    return true;
+  try {
+    window.__reactRouterHdrActive = true;
+    await router.revalidate();
+  } finally {
+    window.__reactRouterHdrActive = false;
   }
-  return false;
 }
 
 function performReactRefresh() {
@@ -391,6 +377,34 @@ function performReactRefresh() {
   }
 }
 
+function applyManifestUpdate(nextRoutes) {
+  const router = window.__reactRouterDataRouter;
+  const routeModules = window.__reactRouterRouteModules;
+  const manifest = window.__reactRouterManifest;
+  const context = window.__reactRouterContext;
+  if (
+    !router ||
+    !routeModules ||
+    !manifest ||
+    !context ||
+    !nextRoutes ||
+    typeof router.createRoutesForHMR !== 'function' ||
+    typeof router._internalSetRoutes !== 'function'
+  ) {
+    return;
+  }
+  const routes = router.createRoutesForHMR(
+    new Set(Object.keys(nextRoutes)),
+    nextRoutes,
+    routeModules,
+    context.ssr,
+    context.isSpaMode
+  );
+  manifest.routes = nextRoutes;
+  router._internalSetRoutes(routes);
+  patchCurrentRouteMatches(router, routes);
+}
+
 async function flush() {
   const router = window.__reactRouterDataRouter;
   const routeModules = window.__reactRouterRouteModules;
@@ -402,30 +416,48 @@ async function flush() {
 
   let shouldRevalidate = pendingRevalidation;
   pendingRevalidation = false;
-  const { nextManifest, shouldRefreshRouteState, routesToRevalidate } =
+  const { nextManifest, hmrRoutes, shouldRefreshRouteState } =
     applyPendingRouteUpdates(router, routeModules, manifest, context);
-  if (nextManifest) {
+  // Loader updates must be visible during revalidation. Component-only routes
+  // stay staged until revalidation completes, matching React Router's HMR flow.
+  if (nextManifest && shouldRefreshRouteState) {
+    pendingComponentRouteRevalidation = false;
+    if (hmrRoutes) {
+      patchCurrentRouteMatches(router, hmrRoutes);
+    }
     Object.assign(manifest, nextManifest);
-  }
-  // Component-only updates do not need a full loader revalidation.
-  if (
-    shouldRefreshRouteState &&
-    (routesToRevalidate.size > 0 || shouldRevalidate)
-  ) {
-    if (await refreshRouteState(router)) {
-      shouldRevalidate = false;
+    await refreshRouteState(router);
+    shouldRevalidate = false;
+  } else if (nextManifest) {
+    if (hmrRoutes) {
+      patchCurrentRouteMatches(router, hmrRoutes);
+    }
+    Object.assign(manifest, nextManifest);
+    // The node compiler also emits an HDR revision for this route edit. If it
+    // did not arrive in this flush, consume that redundant revalidation later.
+    pendingComponentRouteRevalidation = !shouldRevalidate;
+    shouldRevalidate = false;
+  } else if (shouldRevalidate) {
+    if (pendingComponentRouteRevalidation) {
+      pendingComponentRouteRevalidation = false;
+    } else {
+      await revalidateRouter(router);
     }
-  }
-  if (shouldRevalidate) {
-    await revalidateRouter(router);
   }
   performReactRefresh();
 }
 
 if (typeof window !== 'undefined' && import.meta.webpackHot) {
+  import.meta.webpackHot.on(
+    ${JSON.stringify(DEV_MANIFEST_UPDATE_EVENT)},
+    applyManifestUpdate
+  );
   import.meta.webpackHot.accept(
     ${JSON.stringify(hdrRevisionFilePath)},
-    scheduleReactRouterRevalidation
+    () => {
+      latestHdrRevision = __hdrRevision;
+      scheduleReactRouterRevalidation();
+    }
   );
 }
 `;

package/src/dev-runtime-artifacts.ts

@@ -5,7 +5,7 @@ import type { ServerBuild } from 'react-router';
 import type { ReactRouterManifestForDev } from './manifest.js';
 import { getCappedPluginConcurrency } from './concurrency.js';
 import { runPluginEffect, tryPluginPromise } from './effect-runtime.js';
-import { resolveServerBuildModuleEffect } from './server-build-resolution.js';
+import { resolveServerBuildModule } from './server-build-resolution.js';
 
 export type ReactRouterDevManifest = ReactRouterManifestForDev;
 
@@ -137,14 +137,17 @@ export const getEnvironmentStats = (
 const startServerBuildEvaluationEffect = (
   server: RsbuildDevServer,
   entryName: string
-): Effect.Effect<ServerBuild, Error, never> =>
+): Effect.Effect<readonly [string, ServerBuild], Error, never> =>
   tryPluginPromise(() => server.environments.node.loadBundle(entryName)).pipe(
     Effect.flatMap(buildModule =>
-      resolveServerBuildModuleEffect(
-        buildModule,
-        `Server entry ${JSON.stringify(entryName)}`
+      tryPluginPromise(() =>
+        resolveServerBuildModule(
+          buildModule,
+          `Server entry ${JSON.stringify(entryName)}`
+        )
       )
-    )
+    ),
+    Effect.map(build => [entryName, build] as const)
   );
 
 const evaluateServerBuildsEffect = (
@@ -152,12 +155,8 @@ const evaluateServerBuildsEffect = (
   entryNames: readonly string[]
 ): Effect.Effect<ReactRouterServerBuilds, Error, never> =>
   Effect.forEach(
-    entryNames.map(entryName =>
-      startServerBuildEvaluationEffect(server, entryName).pipe(
-        Effect.map(build => [entryName, build] as const)
-      )
-    ),
-    evaluation => evaluation,
+    entryNames,
+    entryName => startServerBuildEvaluationEffect(server, entryName),
     { concurrency: getCappedPluginConcurrency() }
   ).pipe(
     Effect.map(