rsbuild-plugin-react-router 0.3.1 → 0.4.0

package/src/dev-hmr.ts

@@ -0,0 +1,431 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+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';
+
+type SwcLoaderOptions = {
+  jsc?: { transform?: { react?: { refresh?: boolean } } };
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object';
+
+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 (isSwcLoader(value.loader)) {
+    return hasReactRefresh(value.options);
+  }
+  return Object.values(value).some(readSwcLoaderRefresh);
+};
+
+const readRuleSwcRefresh = (rule: unknown): boolean => {
+  if (!isObject(rule)) {
+    return false;
+  }
+  if (isSwcLoader(rule.loader)) {
+    return hasReactRefresh(rule.options);
+  }
+  return (
+    readSwcLoaderRefresh(rule.use) ||
+    readRuleSetSwcRefresh(rule.oneOf) ||
+    readRuleSetSwcRefresh(rule.rules)
+  );
+};
+
+const readRuleSetSwcRefresh = (rules: unknown): boolean =>
+  Array.isArray(rules) && rules.some(readRuleSwcRefresh);
+
+export const isRspackSwcReactRefreshEnabled = (
+  rspackConfig: Rspack.Configuration
+): boolean => readRuleSetSwcRefresh(rspackConfig.module?.rules);
+
+/**
+ * Resolves the `react-refresh/runtime` module that
+ * `@rspack/plugin-react-refresh` injects into the web bundle. The resolution
+ * walks the same dependency chain the refresh plugin uses so the returned file
+ * is the exact runtime instance already present in the browser module graph.
+ * Returns `undefined` when React Fast Refresh is unavailable, in which case
+ * dev HMR falls back to full reloads.
+ */
+export const resolveReactRefreshRuntimePath = (
+  rootPath: string
+): string | undefined => {
+  const resolveFrom = (base: string, request: string): string =>
+    createRequire(base).resolve(request);
+  const rootPackageJson = join(rootPath, 'package.json');
+  try {
+    const pluginReactEntry = resolveFrom(
+      rootPackageJson,
+      '@rsbuild/plugin-react'
+    );
+    const refreshPluginEntry = resolveFrom(
+      pluginReactEntry,
+      '@rspack/plugin-react-refresh'
+    );
+    return resolveFrom(refreshPluginEntry, 'react-refresh/runtime');
+  } catch {
+    return undefined;
+  }
+};
+
+const hdrRevisionModuleContent = (revision: number): string =>
+  `export default ${revision};\n`;
+
+/**
+ * The HDR revision module is a real file (not a virtual module) because it
+ * must wake the web compiler through the regular file watcher: the browser
+ * HMR runtime imports it, so bumping the revision produces a web hot update
+ * 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);
+
+export type DevHdrRevisionSignal = {
+  /** Writes the initial revision module so the first compile can resolve it. */
+  ensure: () => void;
+  /** Increments the revision, signaling hot data revalidation to the client. */
+  bump: () => void;
+};
+
+export const createDevHdrRevisionSignal = ({
+  filePath,
+  onError,
+}: {
+  filePath: string;
+  onError?: (error: Error) => void;
+}): DevHdrRevisionSignal => {
+  let revision = 0;
+  let dirEnsured = false;
+  const write = (): void => {
+    try {
+      if (!dirEnsured) {
+        mkdirSync(dirname(filePath), { recursive: true });
+        dirEnsured = true;
+      }
+      writeFileSync(filePath, hdrRevisionModuleContent(revision));
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(String(error)));
+    }
+  };
+  return {
+    ensure: write,
+    bump() {
+      revision += 1;
+      write();
+    },
+  };
+};
+
+/**
+ * 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
+ * `@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),
+ * recreating the client routes with revalidation opt-out, revalidating loader
+ * data, and finally performing a React refresh.
+ */
+export const generateDevHmrRuntimeModule = ({
+  reactRefreshRuntimePath,
+  hdrRevisionFilePath,
+}: {
+  reactRefreshRuntimePath: string;
+  hdrRevisionFilePath: string;
+}): string => `
+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;
+
+const RefreshRuntime =
+  __refreshRuntimeModule && __refreshRuntimeModule.performReactRefresh
+    ? __refreshRuntimeModule
+    : __refreshRuntimeModule.default;
+
+const pendingRouteUpdates = new Map();
+let flushTimeout;
+let pendingRevalidation = false;
+
+function getCurrentRouterPath(router) {
+  const basename = router.basename || '/';
+  let pathname = window.location.pathname;
+  if (basename !== '/' && pathname.startsWith(basename)) {
+    pathname = pathname.slice(basename.length) || '/';
+    // A trailing-slash basename (e.g. "/mybase/") consumes the leading slash,
+    // leaving a relative path that react-router resolves against the current
+    // location and doubles. Force it back to absolute.
+    if (pathname[0] !== '/') pathname = '/' + pathname;
+  }
+  return pathname + window.location.search + window.location.hash;
+}
+
+export function registerReactRouterRouteExports(routeId, moduleExports) {
+  if (
+    typeof window === 'undefined' ||
+    !RefreshRuntime ||
+    typeof RefreshRuntime.register !== 'function'
+  ) {
+    return;
+  }
+  for (const key in moduleExports) {
+    if (key === '__esModule') continue;
+    const exportValue = moduleExports[key];
+    if (RefreshRuntime.isLikelyComponentType(exportValue)) {
+      RefreshRuntime.register(exportValue, routeId + ' export ' + key);
+    }
+  }
+}
+
+export function scheduleReactRouterRouteUpdate(
+  routeId,
+  routeFlags,
+  getRouteModuleExports
+) {
+  pendingRouteUpdates.set(routeId, { routeFlags, getRouteModuleExports });
+  scheduleFlush();
+}
+
+export function scheduleReactRouterRevalidation() {
+  pendingRevalidation = true;
+  scheduleFlush();
+}
+
+function scheduleFlush() {
+  if (typeof window === 'undefined') {
+    return;
+  }
+  clearTimeout(flushTimeout);
+  flushTimeout = setTimeout(flush, 16);
+}
+
+function takePendingRouteUpdates() {
+  const updates = Array.from(pendingRouteUpdates, ([routeId, update]) => ({
+    routeId,
+    update,
+  }));
+  pendingRouteUpdates.clear();
+  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));
+  const imported = update.getRouteModuleExports();
+  registerReactRouterRouteExports(routeId, imported);
+  const current = routeModules[routeId];
+  const preserveIdentity = key =>
+    imported[key] ? (current && current[key]) || imported[key] : imported[key];
+  routeModules[routeId] = {
+    ...imported,
+    default: preserveIdentity('default'),
+    ErrorBoundary: preserveIdentity('ErrorBoundary'),
+    HydrateFallback: preserveIdentity('HydrateFallback'),
+  };
+}
+
+function getRouteById(routes, routeId) {
+  for (const route of routes) {
+    if (route.id === routeId) {
+      return route;
+    }
+    if (route.children) {
+      const child = getRouteById(route.children, routeId);
+      if (child) {
+        return child;
+      }
+    }
+  }
+}
+
+// Deliberate coupling to React Router's private dev API: patching the live
+// match objects is the only way to swap route implementations without a
+// navigation. The typeof guard below degrades to a no-op if RR removes it.
+function patchCurrentRouteMatches(router, routes) {
+  if (
+    !router.state ||
+    !Array.isArray(router.state.matches) ||
+    typeof router._internalSetStateDoNotUseOrYouWillBreakYourApp !== 'function'
+  ) {
+    return;
+  }
+
+  let changed = false;
+  const matches = router.state.matches.map(match => {
+    const route = getRouteById(routes, match.route.id);
+    if (!route || route === match.route) {
+      return match;
+    }
+    changed = true;
+    return { ...match, route };
+  });
+
+  if (changed) {
+    router._internalSetStateDoNotUseOrYouWillBreakYourApp({ matches });
+  }
+}
+
+function applyPendingRouteUpdates(router, routeModules, manifest, context) {
+  if (pendingRouteUpdates.size === 0) {
+    return {
+      nextManifest: undefined,
+      shouldRefreshRouteState: false,
+      routesToRevalidate: new Set(),
+    };
+  }
+
+  // Clone only entries mutated before the manifest is committed in flush().
+  const nextManifest = { ...manifest, routes: { ...manifest.routes } };
+  const routesToRevalidate = new Set();
+  let shouldRefreshRouteState = false;
+  for (const { routeId, update } of takePendingRouteUpdates()) {
+    const existingEntry = nextManifest.routes[routeId];
+    if (!existingEntry) continue;
+
+    // Shallow clone is enough: only top-level flags are mutated below.
+    const routeEntry = { ...existingEntry };
+    nextManifest.routes[routeId] = routeEntry;
+    applyRouteModuleUpdate(routeId, update, routeEntry, routeModules);
+    if (
+      routeEntry.hasLoader ||
+      routeEntry.hasClientLoader ||
+      routeEntry.hasClientMiddleware
+    ) {
+      routesToRevalidate.add(routeId);
+    }
+    if (
+      existingEntry.hasLoader ||
+      existingEntry.hasClientLoader ||
+      existingEntry.hasClientMiddleware ||
+      routeEntry.hasLoader ||
+      routeEntry.hasClientLoader ||
+      routeEntry.hasClientMiddleware
+    ) {
+      shouldRefreshRouteState = true;
+    }
+  }
+
+  if (
+    typeof router.createRoutesForHMR === 'function' &&
+    typeof router._internalSetRoutes === 'function'
+  ) {
+    const routes = router.createRoutesForHMR(
+      routesToRevalidate,
+      nextManifest.routes,
+      routeModules,
+      context.ssr,
+      context.isSpaMode
+    );
+    router._internalSetRoutes(routes);
+    patchCurrentRouteMatches(router, routes);
+  }
+
+  return { nextManifest, shouldRefreshRouteState, routesToRevalidate };
+}
+
+async function withHdrActive(fn) {
+  try {
+    window.__reactRouterHdrActive = true;
+    await fn();
+  } finally {
+    window.__reactRouterHdrActive = false;
+  }
+}
+
+async function revalidateRouter(router) {
+  if (typeof router.revalidate === 'function') {
+    await withHdrActive(() => router.revalidate());
+    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;
+  }
+  return false;
+}
+
+function performReactRefresh() {
+  if (
+    RefreshRuntime &&
+    typeof RefreshRuntime.performReactRefresh === 'function'
+  ) {
+    RefreshRuntime.performReactRefresh();
+  }
+}
+
+async function flush() {
+  const router = window.__reactRouterDataRouter;
+  const routeModules = window.__reactRouterRouteModules;
+  const manifest = window.__reactRouterManifest;
+  const context = window.__reactRouterContext;
+  if (!router || !routeModules || !manifest || !context) {
+    return;
+  }
+
+  let shouldRevalidate = pendingRevalidation;
+  pendingRevalidation = false;
+  const { nextManifest, shouldRefreshRouteState, routesToRevalidate } =
+    applyPendingRouteUpdates(router, routeModules, manifest, context);
+  if (nextManifest) {
+    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;
+    }
+  }
+  if (shouldRevalidate) {
+    await revalidateRouter(router);
+  }
+  performReactRefresh();
+}
+
+if (typeof window !== 'undefined' && import.meta.webpackHot) {
+  import.meta.webpackHot.accept(
+    ${JSON.stringify(hdrRevisionFilePath)},
+    scheduleReactRouterRevalidation
+  );
+}
+`;

package/src/dev-runtime-controller.ts

@@ -27,6 +27,7 @@ import {
   type ReactRouterDevBuildPlan,
   type ReactRouterDevManifestSet,
 } from './dev-runtime-artifacts.js';
+import { DEV_HDR_REVISION_RELATIVE_PATH } from './dev-hmr.js';
 import {
   createDevRuntimeSessionManager,
   type RuntimeBinding,
@@ -55,6 +56,11 @@ type CreateControllerOptions = {
   api: RsbuildPluginAPI;
   isBuild: boolean;
   buildPlan: ReactRouterDevBuildPlan;
+  /**
+   * Invoked after a development attempt commits a re-evaluated node build for
+   * changed server files. Used to signal hot data revalidation to the client.
+   */
+  onNodeRebuildCommitted?: () => void;
 };
 
 const escapeHtml = (value: string): string =>
@@ -65,10 +71,29 @@ const escapeHtml = (value: string): string =>
 
 const CSS_SOURCE_RELOAD_DELAY_MS = 1000;
 
+const isHdrRevisionFile = (file: string): boolean =>
+  file.includes(DEV_HDR_REVISION_RELATIVE_PATH);
+
+const isCssSourceFile = (file: string): boolean =>
+  /\.css(?:\.[cm]?[jt]s)?$/.test(file);
+
+// A change that should bump the HDR revision: anything except the revision
+// file itself (the bump's own echo) and CSS sources (styling never changes
+// loader data).
+const hasHdrTriggeringChange = (files: Iterable<string>): boolean => {
+  for (const file of files) {
+    if (!isHdrRevisionFile(file) && !isCssSourceFile(file)) {
+      return true;
+    }
+  }
+  return false;
+};
+
 export const createReactRouterDevRuntimeController = ({
   api,
   isBuild,
   buildPlan,
+  onNodeRebuildCommitted,
 }: CreateControllerOptions): ReactRouterDevRuntimeController => {
   if (isBuild) {
     return {
@@ -132,6 +157,14 @@ export const createReactRouterDevRuntimeController = ({
   const compilationIdentities = createCompilationIdentityTracker();
   const { getCompilationIdentity } = compilationIdentities;
 
+  // Web-only commits reuse the node compiler's stale `modifiedFiles`
+  // snapshot, and every HDR bump itself triggers a web rebuild — so signal
+  // once per node compilation identity or the bump loop self-sustains.
+  const hdrSignaledNodeIdentity = new WeakMap<
+    DevCompilerPair,
+    NonNullable<DevGraphIdentity['node']>
+  >();
+
   const finishRuntimeAttemptEffect = (
     binding: RuntimeBinding,
     pair: DevCompilerPair,
@@ -144,11 +177,22 @@ export const createReactRouterDevRuntimeController = ({
     ).pipe(
       Effect.flatMap(result =>
         tryPluginSync(() => {
+          if (sessions.getActiveBinding()?.id !== binding.id) {
+            return;
+          }
+          if (result === 'retry-node') {
+            pair.node.watching?.invalidate();
+            return;
+          }
           if (
-            result === 'retry-node' &&
-            sessions.getActiveBinding()?.id === binding.id
+            result === 'committed' &&
+            changes.node.known &&
+            identity.node !== undefined &&
+            hdrSignaledNodeIdentity.get(pair) !== identity.node &&
+            hasHdrTriggeringChange(changes.node.files)
           ) {
-            pair.node.watching?.invalidate();
+            hdrSignaledNodeIdentity.set(pair, identity.node);
+            onNodeRebuildCommitted?.();
           }
         })
       ),

package/src/index.ts

@@ -82,7 +82,16 @@ import {
   createReactRouterRouteWatchFiles,
   registerReactRouterDevBackgroundResources,
 } from './dev-background-resources.js';
+import {
+  createDevHdrRevisionSignal,
+  generateDevHmrRuntimeModule,
+  getDevHdrRevisionFilePath,
+  isRspackSwcReactRefreshEnabled,
+  resolveReactRefreshRuntimePath,
+  DEV_HMR_RUNTIME_MODULE_ID,
+} from './dev-hmr.js';
 
+export type { Config as ReactRouterRsbuildConfig } from './react-router-config.js';
 export { loadReactRouterServerBuild } from './dev-generation.js';
 export { resolveReactRouterServerBuild };
 
@@ -575,10 +584,26 @@ export const pluginReactRouter = (
       defaultEntryName: devServerBuildEntryName,
     });
     const { serverBundleEntries } = serverBuildPlan;
+
+    const devHmrRefreshRuntimePath = isBuild
+      ? undefined
+      : resolveReactRefreshRuntimePath(api.context.rootPath);
+    const devHdrSignal = devHmrRefreshRuntimePath
+      ? createDevHdrRevisionSignal({
+          filePath: getDevHdrRevisionFilePath(api.context.rootPath),
+          onError: error =>
+            api.logger.debug(
+              `[${PLUGIN_NAME}] Failed to signal hot data revalidation: ${error.message}`
+            ),
+        })
+      : undefined;
+    let devHmrEnabled = false;
+
     const devRuntime = createReactRouterDevRuntimeController({
       api,
       isBuild,
       buildPlan: serverBuildPlan,
+      onNodeRebuildCommitted: () => devHdrSignal?.bump(),
     });
 
     let clientStats: ReactRouterManifestStats | undefined;
@@ -702,6 +727,16 @@ export const pluginReactRouter = (
           ...bundleVirtualModules,
           ...bundleManifestModules,
           'virtual/react-router/with-props': generateWithProps(),
+          ...(devHmrRefreshRuntimePath
+            ? {
+                [DEV_HMR_RUNTIME_MODULE_ID]: generateDevHmrRuntimeModule({
+                  reactRefreshRuntimePath: devHmrRefreshRuntimePath,
+                  hdrRevisionFilePath: getDevHdrRevisionFilePath(
+                    api.context.rootPath
+                  ),
+                }),
+              }
+            : {}),
         })
       );
     };
@@ -913,6 +948,18 @@ export const pluginReactRouter = (
                 ensureFederationAsyncStartup(rspackConfig);
               }
 
+              if (name === 'web') {
+                devHmrEnabled =
+                  !isBuild &&
+                  devHmrRefreshRuntimePath !== undefined &&
+                  config.mode === 'development' &&
+                  config.dev?.hmr !== false &&
+                  isRspackSwcReactRefreshEnabled(rspackConfig);
+                if (devHmrEnabled) {
+                  devHdrSignal?.ensure();
+                }
+              }
+
               if (name === 'node') {
                 const output = rspackConfig.output;
                 if (output) {
@@ -985,6 +1032,7 @@ export const pluginReactRouter = (
       ssr,
       isSpaMode,
       rootRoutePath,
+      isDevHmrEnabled: () => devHmrEnabled,
     });
   },
 });

package/src/prerender-build.ts

@@ -179,11 +179,21 @@ const prerenderData = async ({
   api: PrerenderBuildApi;
   requestInit?: RequestInit;
 }): Promise<string> => {
-  const dataRequestPath = createDataRequestPath(
+  const dataOutputPath = createDataRequestPath(
     prerenderPath,
     trailingSlashAwareDataRequests
   );
+  // The handler always serves the root route's data at /_root.data, even when
+  // trailing-slash-aware naming writes the root output to /_.data.
+  const dataRequestPath =
+    trailingSlashAwareDataRequests && prerenderPath === '/'
+      ? '/_root.data'
+      : dataOutputPath;
   const normalizedPath = `${basename}${dataRequestPath}`.replace(/\/\/+/g, '/');
+  const outputNormalizedPath =
+    dataOutputPath === dataRequestPath
+      ? normalizedPath
+      : `${basename}${dataOutputPath}`.replace(/\/\/+/g, '/');
   const url = new URL(`http://localhost${normalizedPath}`);
   if (onlyRoutes?.length) {
     url.searchParams.set('_routes', onlyRoutes.join(','));
@@ -201,7 +211,10 @@ const prerenderData = async ({
       );
     }
 
-    const outputPath = resolve(clientBuildDir, ...normalizedPath.split('/'));
+    const outputPath = resolve(
+      clientBuildDir,
+      ...outputNormalizedPath.split('/')
+    );
     await mkdir(dirname(outputPath), { recursive: true });
     await writeFile(outputPath, data);
     api.logger.info(
@@ -527,17 +540,24 @@ const createPrerenderPathEffect = ({
         clientBuildDir,
         basename,
         api,
-        requestInit: data
-          ? {
-              headers: {
-                'X-React-Router-Prerender-Data': encodeURI(data),
-              },
-            }
-          : undefined,
+        requestInit: data ? createPrerenderDataRequestInit(data) : undefined,
       })
     );
   });
 
+const createPrerenderDataRequestInit = (
+  data: string
+): RequestInit | undefined => {
+  const encodedData = encodeURI(data);
+  return encodedData.length < 8 * 1024
+    ? {
+        headers: {
+          'X-React-Router-Prerender-Data': encodedData,
+        },
+      }
+    : undefined;
+};
+
 const runPrerenderPaths = async ({
   build,
   requestHandler,

package/src/prerender.ts

@@ -249,7 +249,7 @@ export const resolvePrerenderPaths = async (
         [
           'Warning: Paths with dynamic/splat params cannot be prerendered when using `prerender: true`.',
           'You may want to use the `prerender()` API to prerender the following paths:',
-          ...paramRoutes.map(path => `  - ${path}`),
+          ...paramRoutes.map(path => `  - ${path.replace(/^\/(?=[:*])/, '')}`),
         ].join('\n')
       );
     }