rsbuild-plugin-react-router 0.3.1 → 0.4.0

package/README.md

@@ -98,7 +98,7 @@ async exports before passing the build to React Router's request handler.
 Put React Router framework settings in `react-router.config.*`:
 
 ```ts
-import type { Config } from '@react-router/dev/config';
+import type { ReactRouterRsbuildConfig } from 'rsbuild-plugin-react-router';
 
 export default {
   ssr: true,
@@ -107,9 +107,15 @@ export default {
   basename: '/',
   splitRouteModules: true,
   subResourceIntegrity: false,
-} satisfies Config;
+} satisfies ReactRouterRsbuildConfig;
 ```
 
+Use `ReactRouterRsbuildConfig` for Rsbuild projects so plugin-supported
+configuration such as `splitRouteModules` stays typed. The underlying route
+and config types come from `@react-router/dev`, which framework-mode apps
+already install for `routes.ts` helpers and typegen; it is declared as an
+optional peer dependency.
+
 Commonly used options:
 
 | Option                 | Default      | Notes                                                                                                                     |
@@ -178,7 +184,7 @@ For static sites with multiple pages, you can prerender specific routes at build
 
 ```ts
 // react-router.config.ts
-import type { Config } from '@react-router/dev/config';
+import type { ReactRouterRsbuildConfig } from 'rsbuild-plugin-react-router';
 
 export default {
   ssr: false,
@@ -190,7 +196,7 @@ export default {
     '/docs/advanced',
     '/projects',
   ],
-} satisfies Config;
+} satisfies ReactRouterRsbuildConfig;
 ```
 
 When `prerender` is specified:
@@ -209,7 +215,7 @@ export default {
   ssr: false,
   prerender: ({ getStaticPaths }) =>
     getStaticPaths().filter(path => path !== '/admin'),
-} satisfies Config;
+} satisfies ReactRouterRsbuildConfig;
 ```
 
 Prerendering defaults to one path at a time, matching React Router. Use
@@ -223,7 +229,7 @@ export default {
     paths: ['/', '/about'],
     concurrency: 4,
   },
-} satisfies Config;
+} satisfies ReactRouterRsbuildConfig;
 ```
 
 For builds with 256+ routes, detailed file-size reporting is compacted to totals
@@ -584,14 +590,14 @@ export default {
 ```json
 {
   "dependencies": {
-    "@react-router/node": "^7.1.3",
-    "@react-router/serve": "^7.1.3",
-    "react-router": "^7.1.3"
+    "@react-router/node": "^7.13.0",
+    "@react-router/serve": "^7.13.0",
+    "react-router": "^7.13.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20241112.0",
-    "@react-router/cloudflare": "^7.1.3",
-    "@react-router/dev": "^7.1.3",
+    "@react-router/cloudflare": "^7.13.0",
+    "@react-router/dev": "^7.13.0",
     "wrangler": "^3.106.0"
   }
 }
@@ -661,7 +667,23 @@ pnpm bench:synthetic-app -- --profile all --runs 2
 ```
 
 The PR benchmark workflow reports production build, dev route-load, HMR/update,
-and embedded synthetic app timings in the same benchmark comment.
+and embedded synthetic app timings in the same benchmark comment. It measures
+the PR and its base on the same runner instead of reusing cached timing data,
+counterbalances which side runs first, and excludes one warmup iteration. Small
+fixtures use five measured iterations; expensive large fixtures use three.
+
+Every raw median delta remains visible. The comment also reports each side's
+relative median absolute deviation (rMAD), a conservative noise band, and a
+signal label:
+
+- `regression` or `improvement` means the median delta exceeds the observed
+  run-to-run noise band.
+- `inconclusive` means the raw delta is not clearly separated from that noise.
+- `insufficient data` means either side has fewer than three finite samples.
+
+The labels are triage aids, not pass/fail gates. Use the uploaded diagnostics
+and raw per-run samples to investigate important changes, and rerun an
+inconclusive comparison before treating it as a performance result.
 
 ## React Router Framework Mode
 

package/dist/451.js

@@ -757,17 +757,67 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
     }
     if (unresolvedExportAll.size > 0) throw Error(`[${PLUGIN_NAME}] Client-only module uses \`export * from\` with unresolvable specifier(s): ${Array.from(unresolvedExportAll).map((spec)=>`\`${spec}\``).join(', ')}. Please explicitly re-export named bindings in \`${relative(process.cwd(), resourcePath)}\`.`);
     return exportNames;
-}, createRouteClientEntryArtifact = async ({ code, resourcePath, environmentName, isBuild, routeChunkCache, routeChunkConfig })=>{
+}, HMR_PATCHABLE_ROUTE_FLAGS = [
+    'hasAction',
+    'hasClientAction',
+    'hasClientLoader',
+    'hasClientMiddleware',
+    'hasErrorBoundary',
+    'hasLoader'
+], HMR_FLAG_EXPORT_NAME = {
+    hasAction: SERVER_EXPORTS.action,
+    hasClientAction: CLIENT_EXPORTS.clientAction,
+    hasClientLoader: CLIENT_EXPORTS.clientLoader,
+    hasClientMiddleware: CLIENT_EXPORTS.clientMiddleware,
+    hasErrorBoundary: CLIENT_EXPORTS.ErrorBoundary,
+    hasLoader: SERVER_EXPORTS.loader
+}, createRouteClientEntryArtifact = async ({ code, resourcePath, environmentName, isBuild, routeChunkCache, routeChunkConfig, routeId, devHmr })=>{
     let isServer = 'node' === environmentName, routeChunkInfo = !isServer && isBuild && shouldAnalyzeRouteChunks(routeChunkConfig, resourcePath, code) ? await detectRouteChunksIfEnabled(routeChunkCache, routeChunkConfig, resourcePath, code) : null;
     return {
-        code: (({ exportNames, chunkedExports, isServer, resourcePath })=>{
-            let chunkedExportSet = chunkedExports.length > 0 ? new Set(chunkedExports) : void 0, reexports = exportNames.filter((exp)=>!chunkedExportSet?.has(exp) && (CLIENT_ROUTE_EXPORTS_SET.has(exp) || isServer && SERVER_ONLY_ROUTE_EXPORTS_SET.has(exp))).sort(), target = `${resourcePath}?react-router-route`;
-            return `export { ${reexports.join(', ')} } from ${JSON.stringify(target)};`;
+        code: (({ exportNames, chunkedExports, isServer, resourcePath, routeId, devHmr })=>{
+            let exports, flags, chunkedExportSet = chunkedExports.length > 0 ? new Set(chunkedExports) : void 0, reexports = exportNames.filter((exp)=>!chunkedExportSet?.has(exp) && (CLIENT_ROUTE_EXPORTS_SET.has(exp) || isServer && SERVER_ONLY_ROUTE_EXPORTS_SET.has(exp))).sort(), target = `${resourcePath}?react-router-route`, reexportCode = `export { ${reexports.join(', ')} } from ${JSON.stringify(target)};`;
+            return !devHmr || isServer || void 0 === routeId ? reexportCode : reexportCode + (({ routeId, target, acceptTarget, flags })=>{
+                let targetJson = JSON.stringify(target), 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();
+}
+`;
+            })({
+                routeId,
+                target,
+                acceptTarget: `./${basename(resourcePath)}?react-router-route`,
+                flags: (exports = new Set(exportNames), flags = 0, HMR_PATCHABLE_ROUTE_FLAGS.forEach((flag, index)=>{
+                    exports.has(HMR_FLAG_EXPORT_NAME[flag]) && (flags |= 1 << index);
+                }), flags)
+            });
         })({
             exportNames: routeChunkInfo?.exportNames ?? await getExportNames(code, resourcePath),
             chunkedExports: routeChunkInfo?.chunkedExports ?? [],
             isServer,
-            resourcePath
+            resourcePath,
+            routeId,
+            devHmr: devHmr && !isBuild
         })
     };
 }, createRouteChunkArtifact = async ({ code, resource, resourcePath, isBuild, routeChunkCache, routeChunkConfig })=>{
@@ -817,7 +867,50 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
 }, createClientOnlyStub = async (task)=>({
         code: Array.from(await collectClientOnlyStubExportNames(task.code, task.resourcePath, task.resolveExportAllModule)).map((name)=>'default' === name ? 'export default undefined;' : `export const ${name} = undefined;`).join('\n'),
         map: null
-    }), transformRouteModule = async (task)=>{
+    }), callResolvesToComponent = (node)=>{
+    let args = node.arguments ?? [];
+    if (0 === args.length) return !1;
+    let callee = node.callee;
+    if (!callee || 'Import' === callee.type) return !1;
+    if ('Identifier' === callee.type) {
+        let calleeName = callee.name ?? '';
+        if (calleeName.startsWith('require') || calleeName.startsWith('import')) return !1;
+    } else if ('MemberExpression' !== callee.type) return !1;
+    var node1 = args[0];
+    switch(node1?.type){
+        case 'FunctionExpression':
+            return !0;
+        case 'ArrowFunctionExpression':
+            return node1.body?.type !== 'ArrowFunctionExpression';
+        case 'Identifier':
+            let name;
+            return !!node1.name && (name = node1.name, /^[A-Z]/.test(name));
+        case 'CallExpression':
+            return callResolvesToComponent(node1);
+        default:
+            return !1;
+    }
+}, collectDeclaredComponentNames = (declaration, names)=>{
+    let name, name1;
+    if ('FunctionDeclaration' === declaration.type && declaration.id?.name && (name = declaration.id.name, /^[A-Z]/.test(name))) return void names.add(declaration.id.name);
+    if ('VariableDeclaration' !== declaration.type) return;
+    let declarators = declaration.declarations ?? [];
+    if (1 !== declarators.length) return;
+    let [declarator] = declarators;
+    declarator?.id?.type === 'Identifier' && declarator.id.name && (name1 = declarator.id.name, /^[A-Z]/.test(name1)) && declarator.init && ((init)=>{
+        switch(init.type){
+            case 'FunctionExpression':
+            case 'TaggedTemplateExpression':
+                return !0;
+            case 'ArrowFunctionExpression':
+                return init.body?.type !== 'ArrowFunctionExpression';
+            case 'CallExpression':
+                return callResolvesToComponent(init);
+            default:
+                return !1;
+        }
+    })(declarator.init) && names.add(declarator.id.name);
+}, transformRouteModule = async (task)=>{
     let code = task.code, defaultExportMatch = code.match(/\n\s{0,}([\w\d_]+)\sas default,?/);
     defaultExportMatch && 'number' == typeof defaultExportMatch.index && (code = code.slice(0, defaultExportMatch.index) + code.slice(defaultExportMatch.index + defaultExportMatch[0].length) + `\nexport default ${defaultExportMatch[1]};`);
     let ast = ((code, options = {})=>{
@@ -940,7 +1033,7 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
             return !(!declaration || currentlyLive.has(declaration)) && (previouslyLive.has(declaration) || declarationReferencesName(declaration, removedExportReferencedNames, declarationGraph, removedReferenceCache));
         }, program.body = program.body.filter((statement)=>'VariableDeclaration' === statement.type ? (statement.declarations = (statement.declarations ?? []).filter((declarator)=>!isRemovableDeadDeclaration(declarator)), statement.declarations.length > 0) : !isRemovableDeadDeclaration(statement))), exportsChanged;
     })(ast, SERVER_ONLY_ROUTE_EXPORTS, SERVER_ONLY_ROUTE_EXPORTS_SET);
-    return ((ast)=>{
+    ((ast)=>{
         let program = ast.program ?? ast, usedNames = new Set(), hocs = [], componentWrapperDeclarations = [];
         function getUid(name) {
             let uid = `_${name}`, index = 2;
@@ -1044,7 +1137,8 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
         for (let statement of [
             ...program.body
         ])'ImportDeclaration' === statement.type && 0 !== (statement.specifiers ?? []).length && (statement.specifiers = (statement.specifiers ?? []).filter((specifier)=>'type' !== specifier.importKind && (!specifier.local?.name || referenced.has(specifier.local.name))), 0 === statement.specifiers.length && removeFromArray(program.body, statement));
-    })(ast), ((ast, options = {})=>{
+    })(ast);
+    let result = ((ast, options = {})=>{
         let result = 'program' in ast ? ast : {
             program: ast,
             lineStarts: []
@@ -1072,6 +1166,28 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
         filename: task.resource,
         sourceFileName: task.resourcePath
     });
+    if (task.devHmr && 'web' === task.environmentName && !task.isBuild) {
+        let registrations, unregisteredComponents = ((program)=>{
+            let declared = new Set(), registered = new Set();
+            for (let statement of program.body ?? []){
+                if ('ExportNamedDeclaration' === statement.type && statement.declaration) {
+                    collectDeclaredComponentNames(statement.declaration, declared);
+                    continue;
+                }
+                if ('ExpressionStatement' === statement.type && statement.expression?.type === 'CallExpression' && statement.expression.callee?.type === 'Identifier' && '$RefreshReg$' === statement.expression.callee.name) {
+                    let nameArgument = statement.expression.arguments?.[1];
+                    'string' == typeof nameArgument?.value && registered.add(nameArgument.value);
+                    continue;
+                }
+                collectDeclaredComponentNames(statement, declared);
+            }
+            return [
+                ...declared
+            ].filter((name)=>!registered.has(name));
+        })(ast.program ?? ast);
+        unregisteredComponents.length > 0 && (result.code += (registrations = unregisteredComponents.map((name)=>`  if (typeof ${name} === 'function' || (typeof ${name} === 'object' && ${name} !== null)) $RefreshReg$(${name}, ${JSON.stringify(name)});`).join('\n'), `\nif (typeof $RefreshReg$ === 'function') {\n${registrations}\n}\n`));
+    }
+    return result;
 }, executeRouteTransformTask = async (task, options)=>{
     switch(task.kind){
         case 'routeClientEntry':
@@ -1081,7 +1197,9 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
                 environmentName: task.environmentName,
                 isBuild: task.isBuild,
                 routeChunkCache: getRouteChunkCache(options),
-                routeChunkConfig: task.routeChunkConfig
+                routeChunkConfig: task.routeChunkConfig,
+                routeId: task.routeId,
+                devHmr: task.devHmr
             });
         case 'routeChunk':
             return createRouteChunkArtifact({
@@ -1100,4 +1218,4 @@ let mightContainRouteChunkExportName = (source)=>routeChunkExportNames.some((exp
             return transformRouteModule(task);
     }
 };
-export { BUILD_CLIENT_ROUTE_QUERY_STRING, CLIENT_EXPORTS, JS_EXTENSIONS, PLUGIN_NAME, SERVER_EXPORTS, buildManifestChunkValidity, combineURLs, createBundlerRouteExportResolver, createEmptyRouteChunkByExportName, createRouteId, detectRouteChunksIfEnabled, executeRouteTransformTask, findEntryFile, generateWithProps, getRouteChunkEntryName, getRouteChunkModuleId, getRouteModuleAnalysis, normalizeAssetPrefix, routeChunkExportNames, setBoundedCacheEntry, validateRouteChunks };
+export { BUILD_CLIENT_ROUTE_QUERY_STRING, CLIENT_EXPORTS, HMR_PATCHABLE_ROUTE_FLAGS, JS_EXTENSIONS, PLUGIN_NAME, SERVER_EXPORTS, buildManifestChunkValidity, combineURLs, createBundlerRouteExportResolver, createEmptyRouteChunkByExportName, createRouteId, detectRouteChunksIfEnabled, executeRouteTransformTask, findEntryFile, generateWithProps, getRouteChunkEntryName, getRouteChunkModuleId, getRouteModuleAnalysis, normalizeAssetPrefix, routeChunkExportNames, setBoundedCacheEntry, validateRouteChunks };

package/dist/build-output-transforms.d.ts

@@ -25,6 +25,7 @@ type RegisterBuildOutputTransformsOptions = {
     ssr: boolean;
     isSpaMode: boolean;
     rootRoutePath: string;
+    isDevHmrEnabled?: () => boolean;
 };
-export declare const registerBuildOutputTransforms: ({ api, resolvedServerOutput, performanceProfiler, getLatestServerManifest, getLatestServerManifestByBundleId, routes, pluginOptions, getClientStats, appDirectory, getAssetPrefix, routeChunkOptions, routeTransformExecutor, routeByFilePath, routeChunkConfig, isBuild, splitRouteModules, ssr, isSpaMode, rootRoutePath, }: RegisterBuildOutputTransformsOptions) => void;
+export declare const registerBuildOutputTransforms: ({ api, resolvedServerOutput, performanceProfiler, getLatestServerManifest, getLatestServerManifestByBundleId, routes, pluginOptions, getClientStats, appDirectory, getAssetPrefix, routeChunkOptions, routeTransformExecutor, routeByFilePath, routeChunkConfig, isBuild, splitRouteModules, ssr, isSpaMode, rootRoutePath, isDevHmrEnabled, }: RegisterBuildOutputTransformsOptions) => void;
 export {};

package/dist/dev-hmr.d.ts

@@ -0,0 +1,45 @@
+import type { Rspack } from '@rsbuild/core';
+export declare const DEV_HMR_RUNTIME_MODULE_ID = "virtual/react-router/hmr-runtime";
+export declare const isRspackSwcReactRefreshEnabled: (rspackConfig: Rspack.Configuration) => boolean;
+/**
+ * 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 declare const resolveReactRefreshRuntimePath: (rootPath: string) => string | undefined;
+/**
+ * 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 declare const DEV_HDR_REVISION_RELATIVE_PATH = ".react-router/hdr-revision.mjs";
+export declare const getDevHdrRevisionFilePath: (rootPath: string) => string;
+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 declare const createDevHdrRevisionSignal: ({ filePath, onError, }: {
+    filePath: string;
+    onError?: (error: Error) => void;
+}) => DevHdrRevisionSignal;
+/**
+ * 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 declare const generateDevHmrRuntimeModule: ({ reactRefreshRuntimePath, hdrRevisionFilePath, }: {
+    reactRefreshRuntimePath: string;
+    hdrRevisionFilePath: string;
+}) => string;

package/dist/dev-runtime-controller.d.ts

@@ -9,6 +9,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;
 };
-export declare const createReactRouterDevRuntimeController: ({ api, isBuild, buildPlan, }: CreateControllerOptions) => ReactRouterDevRuntimeController;
+export declare const createReactRouterDevRuntimeController: ({ api, isBuild, buildPlan, onNodeRebuildCommitted, }: CreateControllerOptions) => ReactRouterDevRuntimeController;
 export {};