rsbuild-plugin-react-router 0.3.1 → 0.4.0

package/src/route-artifacts.ts

@@ -1,5 +1,9 @@
+import { basename } from 'pathe';
+
 import {
+  CLIENT_EXPORTS,
   CLIENT_ROUTE_EXPORTS_SET,
+  SERVER_EXPORTS,
   SERVER_ONLY_ROUTE_EXPORTS_SET,
 } from './constants.js';
 import { getExportNames } from './export-utils.js';
@@ -22,6 +26,10 @@ export type RouteClientEntryArtifactOptions = {
   isBuild: boolean;
   routeChunkCache?: RouteChunkCache;
   routeChunkConfig: RouteChunkConfig;
+  /** React Router route id for this route module, when known. */
+  routeId?: string;
+  /** Emit development HMR/HDR glue into web route client entries. */
+  devHmr?: boolean;
 };
 
 type RouteClientEntryArtifact = {
@@ -42,16 +50,111 @@ type RouteChunkArtifact = {
   map: null;
 };
 
+// Exactly the route-manifest flags the client HMR runtime can patch in place
+// without a full reload. Array order defines the bit layout shared by the
+// encoder below and the decoder emitted in `generateDevHmrRuntimeModule`.
+export const HMR_PATCHABLE_ROUTE_FLAGS = [
+  'hasAction',
+  'hasClientAction',
+  'hasClientLoader',
+  'hasClientMiddleware',
+  'hasErrorBoundary',
+  'hasLoader',
+] as const;
+
+const HMR_FLAG_EXPORT_NAME: Record<
+  (typeof HMR_PATCHABLE_ROUTE_FLAGS)[number],
+  string
+> = {
+  hasAction: SERVER_EXPORTS.action,
+  hasClientAction: CLIENT_EXPORTS.clientAction,
+  hasClientLoader: CLIENT_EXPORTS.clientLoader,
+  hasClientMiddleware: CLIENT_EXPORTS.clientMiddleware,
+  hasErrorBoundary: CLIENT_EXPORTS.ErrorBoundary,
+  hasLoader: SERVER_EXPORTS.loader,
+};
+
+export const buildRouteHmrFlags = (exportNames: readonly string[]): number => {
+  const exports = new Set(exportNames);
+  let flags = 0;
+  HMR_PATCHABLE_ROUTE_FLAGS.forEach((flag, index) => {
+    if (exports.has(HMR_FLAG_EXPORT_NAME[flag])) flags |= 1 << index;
+  });
+  return flags;
+};
+
+/**
+ * Development-only HMR glue for a web route client entry.
+ *
+ * The route client entry is the webpack entry for a route, so it must
+ * self-accept hot updates to stop them from bubbling into a full reload. It
+ * also accepts updates of the underlying route module and forwards fresh
+ * exports plus route metadata (loader/action flags derived from the current
+ * export names) to the shared HMR runtime, which applies the React Router
+ * route-module update contract and revalidates loader data.
+ */
+const buildRouteClientEntryHmrCode = ({
+  routeId,
+  target,
+  acceptTarget,
+  flags,
+}: {
+  routeId: string;
+  target: string;
+  acceptTarget: string;
+  flags: number;
+}): string => {
+  const targetJson = JSON.stringify(target);
+  const acceptTargetJson = JSON.stringify(acceptTarget);
+  return `
+import * as __rrm from ${targetJson};
+import {
+  registerReactRouterRouteExports as __rrr,
+  scheduleReactRouterRouteUpdate as __rru,
+} from "virtual/react-router/hmr-runtime";
+
+const __rrid = ${JSON.stringify(routeId)};
+const __rrf = ${flags};
+const __rrg = () => __rrm;
+const __rru0 = () => {
+  __rrr(__rrid, __rrm);
+  __rru(__rrid, __rrf, __rrg);
+};
+
+__rrr(__rrid, __rrm);
+
+if (import.meta.webpackHot) {
+  const __rrh = import.meta.webpackHot;
+  __rrh.accept(${acceptTargetJson}, __rru0);
+  __rrh.accept();
+  __rrh.dispose(data => { data.__rr = true; });
+  if (__rrh.data && __rrh.data.__rr) __rru0();
+}
+`;
+};
+
+// The accept target is spelled relative (`./name?react-router-route`) while
+// the import above uses the absolute resource path; both resolve to the same
+// module because the client entry replaces the route file in place, so its
+// resolution context is the route's own directory.
+const createRouteHmrAcceptTarget = (resourcePath: string): string => {
+  return `./${basename(resourcePath)}?react-router-route`;
+};
+
 export const buildRouteClientEntryCode = ({
   exportNames,
   chunkedExports,
   isServer,
   resourcePath,
+  routeId,
+  devHmr,
 }: {
   exportNames: readonly string[];
   chunkedExports: readonly string[];
   isServer: boolean;
   resourcePath: string;
+  routeId?: string;
+  devHmr?: boolean;
 }): string => {
   const chunkedExportSet =
     chunkedExports.length > 0 ? new Set<string>(chunkedExports) : undefined;
@@ -67,7 +170,19 @@ export const buildRouteClientEntryCode = ({
     })
     .sort();
   const target = `${resourcePath}?react-router-route`;
-  return `export { ${reexports.join(', ')} } from ${JSON.stringify(target)};`;
+  const reexportCode = `export { ${reexports.join(', ')} } from ${JSON.stringify(target)};`;
+  if (!devHmr || isServer || routeId === undefined) {
+    return reexportCode;
+  }
+  return (
+    reexportCode +
+    buildRouteClientEntryHmrCode({
+      routeId,
+      target,
+      acceptTarget: createRouteHmrAcceptTarget(resourcePath),
+      flags: buildRouteHmrFlags(exportNames),
+    })
+  );
 };
 
 export const createRouteClientEntryArtifact = async ({
@@ -77,6 +192,8 @@ export const createRouteClientEntryArtifact = async ({
   isBuild,
   routeChunkCache,
   routeChunkConfig,
+  routeId,
+  devHmr,
 }: RouteClientEntryArtifactOptions): Promise<RouteClientEntryArtifact> => {
   const isServer = environmentName === 'node';
   const mightHaveRouteChunks =
@@ -100,6 +217,8 @@ export const createRouteClientEntryArtifact = async ({
       chunkedExports,
       isServer,
       resourcePath,
+      routeId,
+      devHmr: devHmr && !isBuild,
     }),
   };
 };

package/src/route-transform-tasks.ts

@@ -24,7 +24,10 @@ import {
   type RouteChunkCache,
   type RouteChunkConfig,
 } from './route-chunks.js';
-import { getProgram } from './route-ast.js';
+import {
+  getProgram,
+  type AnyNode,
+} from './route-ast.js';
 
 export type RouteTransformResult = {
   code: string;
@@ -41,6 +44,8 @@ export type RouteClientEntryTransformTask = BaseRouteTransformTask & {
   environmentName?: string;
   isBuild: boolean;
   routeChunkConfig: RouteChunkConfig;
+  routeId?: string;
+  devHmr?: boolean;
 };
 
 export type RouteChunkTransformTask = BaseRouteTransformTask & {
@@ -69,6 +74,7 @@ export type RouteModuleTransformTask = BaseRouteTransformTask & {
   isBuild: boolean;
   isSpaMode: boolean;
   rootRoutePath: string | null;
+  devHmr?: boolean;
 };
 
 export type RouteTransformTask =
@@ -151,6 +157,158 @@ const createClientOnlyStub = async (
   };
 };
 
+const isComponentishName = (name: string): boolean => /^[A-Z]/.test(name);
+
+/**
+ * Whether an expression that appears as the first argument of a wrapping call
+ * resolves to a component, mirroring react-refresh/babel's
+ * `findInnerComponents` recursion for the node kinds it accepts as arguments.
+ */
+const argumentResolvesToComponent = (node: AnyNode | undefined): boolean => {
+  switch (node?.type) {
+    case 'FunctionExpression':
+      return true;
+    case 'ArrowFunctionExpression':
+      // Babel bails on a curried arrow (an arrow whose body is another arrow):
+      // that is a component factory, not a component.
+      return node.body?.type !== 'ArrowFunctionExpression';
+    case 'Identifier':
+      return !!node.name && isComponentishName(node.name);
+    case 'CallExpression':
+      return callResolvesToComponent(node);
+    default:
+      return false;
+  }
+};
+
+/**
+ * Whether a `CallExpression` resolves to a component: it must have at least one
+ * argument, a callee that is not `Import`/`require*`/`import*`, and a first
+ * argument that itself resolves to a component.
+ */
+const callResolvesToComponent = (node: AnyNode): boolean => {
+  const args = node.arguments ?? [];
+  if (args.length === 0) {
+    return false;
+  }
+  const callee = node.callee;
+  if (!callee || callee.type === 'Import') {
+    return false;
+  }
+  if (callee.type === 'Identifier') {
+    const calleeName = callee.name ?? '';
+    if (calleeName.startsWith('require') || calleeName.startsWith('import')) {
+      return false;
+    }
+  } else if (callee.type !== 'MemberExpression') {
+    return false;
+  }
+  return argumentResolvesToComponent(args[0]);
+};
+
+/**
+ * Whether a `VariableDeclarator` initializer resolves to a component, matching
+ * react-refresh/babel's accepted init kinds: a non-curried arrow, a function
+ * expression, a tagged template, or a qualifying call expression.
+ */
+const initResolvesToComponent = (init: AnyNode): boolean => {
+  switch (init.type) {
+    case 'FunctionExpression':
+    case 'TaggedTemplateExpression':
+      return true;
+    case 'ArrowFunctionExpression':
+      return init.body?.type !== 'ArrowFunctionExpression';
+    case 'CallExpression':
+      return callResolvesToComponent(init);
+    default:
+      return false;
+  }
+};
+
+const collectDeclaredComponentNames = (
+  declaration: AnyNode,
+  names: Set<string>
+): void => {
+  if (
+    declaration.type === 'FunctionDeclaration' &&
+    declaration.id?.name &&
+    isComponentishName(declaration.id.name)
+  ) {
+    names.add(declaration.id.name);
+    return;
+  }
+  if (declaration.type !== 'VariableDeclaration') {
+    return;
+  }
+  const declarators = declaration.declarations ?? [];
+  // Babel's react-refresh visitor only registers a `VariableDeclaration` with
+  // exactly one declarator; multi-declarator declarations are skipped whole.
+  if (declarators.length !== 1) {
+    return;
+  }
+  const [declarator] = declarators;
+  if (
+    declarator?.id?.type === 'Identifier' &&
+    declarator.id.name &&
+    isComponentishName(declarator.id.name) &&
+    declarator.init &&
+    initResolvesToComponent(declarator.init)
+  ) {
+    names.add(declarator.id.name);
+  }
+};
+
+/**
+ * Names of top-level components that still need a React Fast Refresh
+ * registration, following react-refresh/babel's name-based detection.
+ *
+ * SWC's refresh transform registers components in JSX/TSX sources, but
+ * compiled route modules whose JSX was already lowered by an earlier loader
+ * (e.g. MDX routes) reach it without JSX syntax and end up unregistered. An
+ * unregistered component has no refresh family, so hot updates remount its
+ * subtree instead of updating it in place.
+ */
+const collectUnregisteredComponentNames = (program: {
+  body?: AnyNode[];
+}): string[] => {
+  const declared = new Set<string>();
+  const registered = new Set<string>();
+  for (const statement of program.body ?? []) {
+    if (statement.type === 'ExportNamedDeclaration' && statement.declaration) {
+      collectDeclaredComponentNames(statement.declaration, declared);
+      continue;
+    }
+    if (
+      statement.type === 'ExpressionStatement' &&
+      statement.expression?.type === 'CallExpression' &&
+      statement.expression.callee?.type === 'Identifier' &&
+      statement.expression.callee.name === '$RefreshReg$'
+    ) {
+      const nameArgument = statement.expression.arguments?.[1];
+      if (typeof nameArgument?.value === 'string') {
+        registered.add(nameArgument.value);
+      }
+      continue;
+    }
+    collectDeclaredComponentNames(statement, declared);
+  }
+  return [...declared].filter(name => !registered.has(name));
+};
+
+const buildComponentRefreshRegistrations = (names: string[]): string => {
+  const registrations = names
+    .map(
+      name =>
+        // react-refresh's runtime `register()` tags plain functions *and*
+        // non-null exotic objects (memo/forwardRef `$$typeof` wrappers),
+        // ignoring everything else safely -- so mirror that guard here. The
+        // `typeof` short-circuit keeps this safe even for undeclared names.
+        `  if (typeof ${name} === 'function' || (typeof ${name} === 'object' && ${name} !== null)) $RefreshReg$(${name}, ${JSON.stringify(name)});`
+    )
+    .join('\n');
+  return `\nif (typeof $RefreshReg$ === 'function') {\n${registrations}\n}\n`;
+};
+
 const transformRouteModule = async (
   task: RouteModuleTransformTask
 ): Promise<RouteTransformResult> => {
@@ -207,13 +365,24 @@ const transformRouteModule = async (
     removeUnusedImports(ast);
   }
 
-  return generate(ast, {
+  const result = generate(ast, {
     // Rsbuild merges this map with its downstream SWC transform. Only pay the
     // code-generation cost when this environment actually emits JS maps.
     sourceMaps: task.sourceMaps,
     filename: task.resource,
     sourceFileName: task.resourcePath,
   });
+
+  if (task.devHmr && task.environmentName === 'web' && !task.isBuild) {
+    const unregisteredComponents = collectUnregisteredComponentNames(
+      getProgram(ast)
+    );
+    if (unregisteredComponents.length > 0) {
+      result.code += buildComponentRefreshRegistrations(unregisteredComponents);
+    }
+  }
+
+  return result;
 };
 
 export const executeRouteTransformTask = async (
@@ -229,6 +398,8 @@ export const executeRouteTransformTask = async (
         isBuild: task.isBuild,
         routeChunkCache: getRouteChunkCache(options),
         routeChunkConfig: task.routeChunkConfig,
+        routeId: task.routeId,
+        devHmr: task.devHmr,
       });
     case 'routeChunk':
       return createRouteChunkArtifact({