rsbuild-plugin-react-router 0.7.0 → 0.7.1

package/README.md

@@ -103,9 +103,17 @@ pluginReactRouter({
 | `federation`                     | `false`     | Enables the plugin's experimental Module Federation integration.                                                                                                                                                                 |
 
 When `federation` is enabled, configure the Module Federation plugin with
-`experiments.asyncStartup: true`. The dev server resolves async server build
+`experiments.asyncStartup: true` on every compiler (the plugin enforces it) and
+keep shared dependencies non-eager. The dev server resolves async server build
 exports automatically; production custom servers or adapters should resolve
-async exports before passing the build to React Router's request handler.
+async exports before passing the build to React Router's request handler
+(`resolveReactRouterServerBuild`). Give remote containers an explicit
+`filename` (for example `static/js/remote.js`); every other browser chunk keeps
+Rsbuild's content hash. Under the hood the plugin gives each container its own
+runtime chunk (so importing a container does not start the app's own share
+consumes), makes browser route-module entries async so their exports resolve
+through the async startup, and keeps server code splitting async-only so the
+`@module-federation/node` chunk loader can satisfy the server build's startup.
 
 ### React Router Config
 
@@ -365,6 +373,16 @@ content-hashed filenames, and `output.filename`, `output.filenameHash`,
 `output.distPath`, and `tools.rspack` output settings you configure govern
 the emitted files and the manifest URLs that reference them.
 
+Supported browser filename forms differ by mode:
+
+- **Classic mode** accepts any scheme, including `.mjs`/`.cjs` and query-hash
+  names such as `[name].js?v=[contenthash:8]`; the browser manifest classifies
+  emitted assets by pathname and keeps the full reference.
+- **RSC mode** requires every browser JavaScript asset to be named `*.js`
+  (hashes are fine, e.g. `[contenthash:8]-[name].js`): rspack's RSC manifest
+  only records `.js` files, so the build fails with a clear error for query
+  hashes or other extensions.
+
 ## Custom Server Setup
 
 The plugin supports two ways to handle server-side rendering:

package/dist/federation.d.ts

@@ -1,2 +1,28 @@
 import type { Rspack } from '@rsbuild/core';
+/**
+ * The Module Federation container name(s) configured on this compiler, i.e.
+ * the entry names of the remote containers it emits.
+ */
+export declare const getFederationContainerNames: (rspackConfig: Rspack.Configuration | undefined) => string[];
+/**
+ * Classic mode shares one runtime chunk across every browser entry so route
+ * module entries share a module registry. A federation container must not
+ * share it: importing the container would run the app entries' async startup
+ * (share-scope consumes) before the host has initialized the share scope,
+ * yielding duplicate singletons (a second React). Give containers their own
+ * runtime chunk.
+ */
+export declare const isolateFederationContainerRuntime: (rspackConfig: Rspack.Configuration | undefined) => void;
 export declare const ensureFederationAsyncStartup: (rspackConfig: Rspack.Configuration | undefined) => void;
+/**
+ * `@module-federation/node` replaces Rspack's `readFileVm` chunk loader with one
+ * that tracks loaded chunks privately, so initial chunks split off a
+ * multi-entry server build never satisfy Rspack's startup gate
+ * (`__webpack_require__.O`) and the async startup resolves to `undefined`
+ * instead of the server build's exports. Keep server code splitting to async
+ * chunks only. Runs at the final `tools.rspack` boundary so a user
+ * `optimization.splitChunks` override or a preset whose cache group selects
+ * `chunks: 'all'` (e.g. Rsbuild's `single-vendor`, `enforce: true`) cannot
+ * reintroduce initial chunk dependencies. A disabled `splitChunks` is kept.
+ */
+export declare const enforceAsyncOnlyServerSplitChunks: (rspackConfig: Rspack.Configuration | undefined) => void;

package/dist/index.cjs

@@ -617,15 +617,29 @@ const resolveEntryWithTemplate = ({ appDirectory, entryName, templateName, templ
         hasServerApp,
         serverAppPath
     };
+}, getModuleFederationOptions = (plugin)=>{
+    if (plugin && 'object' == typeof plugin && ('ModuleFederationPlugin' === plugin.name || 'RspackModuleFederationPlugin' === plugin.name)) return plugin._options ?? plugin.options;
+}, getFederationContainerNames = (rspackConfig)=>(rspackConfig?.plugins ?? []).map(getModuleFederationOptions).map((options)=>options?.name).filter((name)=>'string' == typeof name), isolateFederationContainerRuntime = (rspackConfig)=>{
+    let containers = new Set(getFederationContainerNames(rspackConfig));
+    if (!rspackConfig || 0 === containers.size) return;
+    let current = rspackConfig.optimization?.runtimeChunk, appRuntimeName = 'object' == typeof current && 'string' == typeof current?.name ? current.name : 'runtime';
+    rspackConfig.optimization = {
+        ...rspackConfig.optimization,
+        runtimeChunk: {
+            name: (entrypoint)=>containers.has(entrypoint.name) ? `runtime-${entrypoint.name}` : appRuntimeName
+        }
+    };
 }, ensureFederationAsyncStartup = (rspackConfig)=>{
     if (rspackConfig?.plugins?.length) for (let plugin of rspackConfig.plugins){
-        if (!plugin || 'object' != typeof plugin || 'ModuleFederationPlugin' !== plugin.name && 'RspackModuleFederationPlugin' !== plugin.name) continue;
-        let pluginOptions = plugin._options ?? plugin.options;
+        let pluginOptions = getModuleFederationOptions(plugin);
         pluginOptions && (pluginOptions.experiments = {
             ...pluginOptions.experiments,
             asyncStartup: !0
         });
     }
+}, enforceAsyncOnlyServerSplitChunks = (rspackConfig)=>{
+    let splitChunks = rspackConfig?.optimization?.splitChunks;
+    if (splitChunks) for (let group of (splitChunks.chunks = 'async', Object.values(splitChunks.cacheGroups ?? {})))group && 'object' == typeof group && 'chunks' in group && (group.chunks = 'async');
 }, registerReactRouterEnvironmentOutput = ({ api, federation, resolvedServerOutput, webOutput })=>{
     let nodeChunkLoading = 'module' === resolvedServerOutput ? 'import' : federation ? 'async-node' : 'require';
     api.modifyRspackConfig((rspackConfig, { environment, mergeConfig })=>'web' === environment.name ? mergeConfig(rspackConfig, {
@@ -649,7 +663,7 @@ const resolveEntryWithTemplate = ({ appDirectory, entryName, templateName, templ
         }) : rspackConfig), api.modifyEnvironmentConfig(async (config, { name, mergeEnvironmentConfig })=>'web' !== name && 'node' !== name ? config : mergeEnvironmentConfig(config, {
             tools: {
                 rspack: (rspackConfig)=>{
-                    if (federation && ensureFederationAsyncStartup(rspackConfig), 'node' === name) {
+                    if (federation && (ensureFederationAsyncStartup(rspackConfig), 'web' === name ? isolateFederationContainerRuntime(rspackConfig) : enforceAsyncOnlyServerSplitChunks(rspackConfig)), 'node' === name) {
                         let output = rspackConfig.output;
                         if (output) {
                             let library = output.library, libraryOptions = library && 'object' == typeof library && !Array.isArray(library) ? library : {};
@@ -1470,7 +1484,7 @@ const getCurrentVersion = ()=>moduleVersion, setCurrentVersion = (version)=>{
 }), findLast = null, zip = null, Iterable_zipWith = null, intersperse = null, Iterable_containsWith = (isEquivalent)=>dual(2, (self, a)=>{
         for (let i of self)if (isEquivalent(a, i)) return !0;
         return !1;
-    }), Iterable_equivalence = null, Iterable_contains = null, chunksOf = null, groupWith = null, group = null, groupBy = null, constEmpty = {
+    }), Iterable_equivalence = null, Iterable_contains = null, chunksOf = null, groupWith = null, Iterable_group = null, groupBy = null, constEmpty = {
     [Symbol.iterator]: ()=>constEmptyIterator
 }, constEmptyIterator = {
     next: ()=>({
@@ -11816,7 +11830,25 @@ const createReactRouterManifestOptions = ({ routeChunks, routeModuleAnalysis })=
             routeModuleAnalysis
         } : {}
     };
-}, isManifestJsAsset = (asset)=>/(?<!\.hot-update)\.[cm]?js(?:\?.*)?$/.test(asset), isManifestCssAsset = (asset)=>/\.css(?:\?.*)?$/.test(asset), collectManifestFilesByName = (items, names, getFiles)=>{
+}, isManifestJsAsset = (asset)=>/(?<!\.hot-update)\.[cm]?js(?:\?.*)?$/.test(asset), isManifestCssAsset = (asset)=>/\.css(?:\?.*)?$/.test(asset), hasSome = (iterable)=>{
+    for (let _ of iterable)return !0;
+    return !1;
+}, collectUnsupportedRscScriptAssets = (compilation)=>{
+    let unsupported = new Set();
+    for (let chunk of compilation.chunks){
+        if (!(chunk.contentHash?.javascript !== void 0 || hasSome(compilation.chunkGraph.getChunkModulesIterableBySourceType(chunk, "javascript")))) continue;
+        let pathData = {
+            chunk,
+            contentHashType: "javascript"
+        }, template = chunk.canBeInitial() ? compilation.outputOptions.filename : compilation.outputOptions.chunkFilename, resolvedTemplate = 'function' == typeof template ? template(pathData) : template;
+        if ('string' != typeof resolvedTemplate) continue;
+        let file = compilation.getPath(resolvedTemplate, pathData);
+        file.endsWith('.js') || unsupported.add(file);
+    }
+    return [
+        ...unsupported
+    ];
+}, collectManifestFilesByName = (items, names, getFiles)=>{
     let filesByName = {};
     if (!names) {
         for (let [name, item] of items)null != item && (filesByName[name] = getFiles(name, item));
@@ -14758,11 +14790,19 @@ export {
         'virtual/react-router/unstable_rsc/manifest-prefix': `const manifest = __webpack_require__.rscM;
 const serverPrefix = ${JSON.stringify(serverPublicPath)};
 const appliedPrefix = manifest?.moduleLoading?.prefix;
-if (appliedPrefix && appliedPrefix !== serverPrefix) {
+// An empty applied prefix (web \`assetPrefix: ''\`) yields relative references
+// such as "static/js/index.js"; those are rebased too, while absolute and
+// protocol-relative URLs are left alone.
+const isAbsoluteUrl = url => /^(?:[a-z][a-z\\d+.-]*:|\\/\\/|\\/)/i.test(url);
+if (typeof appliedPrefix === "string" && appliedPrefix !== serverPrefix) {
   const rewrite = url =>
-    typeof url === "string" && url.startsWith(appliedPrefix)
-      ? serverPrefix + url.slice(appliedPrefix.length)
-      : url;
+    typeof url !== "string"
+      ? url
+      : appliedPrefix !== "" && url.startsWith(appliedPrefix)
+        ? serverPrefix + url.slice(appliedPrefix.length)
+        : appliedPrefix === "" && !isAbsoluteUrl(url)
+          ? serverPrefix + url
+          : url;
   const rewriteAll = list => {
     if (Array.isArray(list)) for (let i = 0; i < list.length; i++) list[i] = rewrite(list[i]);
   };
@@ -16084,8 +16124,12 @@ export default entryJsFiles;
                 initialRouteTopology: routeTopology.initialRouteTopology,
                 onRouteTopologyChange: pluginOptions.onRouteTopologyChange
             });
-            api.onAfterEnvironmentCompile(({ stats, environment })=>{
-                if ('web' === environment.name && (clientStats = createReactRouterManifestStats(stats?.compilation, manifestChunkNames)), pluginOptions.federation && ssr) {
+            if (api.onAfterEnvironmentCompile(({ stats, environment })=>{
+                if ('web' === environment.name && (clientStats = createReactRouterManifestStats(stats?.compilation, manifestChunkNames), isRscMode && stats)) {
+                    let unsupported = collectUnsupportedRscScriptAssets(stats.compilation);
+                    if (unsupported.length > 0) throw Error(`[${PLUGIN_NAME}] RSC mode requires every browser JavaScript asset to be named "*.js" (no query, no other extension): rspack's RSC manifest omits ${unsupported.slice(0, 5).map((asset)=>JSON.stringify(asset)).join(', ')}${unsupported.length > 5 ? ` and ${unsupported.length - 5} more` : ''}. Adjust web \`output.filename.js\` / \`chunkFilename\`.`);
+                }
+                if (pluginOptions.federation && ssr) {
                     let serverBuildDir = (0, external_pathe_namespaceObject.resolve)(buildDirectory, 'server'), clientBuildDir = (0, external_pathe_namespaceObject.resolve)(buildDirectory, 'client');
                     if ((0, external_node_fs_namespaceObject.existsSync)(serverBuildDir)) {
                         let ssrDir = (0, external_pathe_namespaceObject.resolve)(clientBuildDir, 'static');
@@ -16128,9 +16172,7 @@ export default entryJsFiles;
                         prerenderPaths: modePlan.prerenderPaths,
                         basename
                     })))), api.modifyRsbuildConfig(async (config, { mergeRsbuildConfig })=>{
-                let publicPath, webConfig = config.environments?.web, webJsFilename = webConfig?.output?.filename?.js ?? config.output?.filename?.js;
-                if (isRscMode && 'string' == typeof webJsFilename && !/\.js$/.test(webJsFilename)) throw Error(`[${PLUGIN_NAME}] RSC mode requires web \`output.filename.js\` to end in ".js" (got ${JSON.stringify(webJsFilename)}): rspack's RSC manifest omits entry files with a query or another extension, so the server could not render bootstrap scripts.`);
-                let vmodPlugin = (publicPath = resolveEffectiveAssetPrefix({
+                let publicPath, webConfig = config.environments?.web, vmodPlugin = (publicPath = resolveEffectiveAssetPrefix({
                     dev: webConfig?.dev,
                     output: webConfig?.output,
                     isBuild
@@ -16257,7 +16299,20 @@ export default entryJsFiles;
                 federation: pluginOptions.federation,
                 resolvedServerOutput,
                 webOutput: modePlan.webOutput
-            }), 'classic' === modePlan.kind && useRouteModuleTransformLoader && api.modifyEnvironmentConfig(async (config, { name, mergeEnvironmentConfig })=>'web' !== name && 'node' !== name ? config : mergeEnvironmentConfig(config, {
+            }), pluginOptions.federation && 'classic' === modePlan.kind) {
+                let browserEntryModules = new Set([
+                    finalEntryClientPath,
+                    ...routeByFilePath.keys()
+                ]);
+                api.transform({
+                    environments: [
+                        'web'
+                    ],
+                    order: 'post',
+                    test: (resourcePath)=>browserEntryModules.has(resourcePath)
+                }, ({ code })=>`${code}\nexport {};\nawait Promise.resolve();\n`);
+            }
+            'classic' === modePlan.kind && useRouteModuleTransformLoader && api.modifyEnvironmentConfig(async (config, { name, mergeEnvironmentConfig })=>'web' !== name && 'node' !== name ? config : mergeEnvironmentConfig(config, {
                     tools: {
                         rspack: (rspackConfig)=>{
                             let environmentDevHmrEnabled = 'web' === name && !isBuild && void 0 !== devHmrRefreshRuntimePath && 'development' === config.mode && config.dev?.hmr !== !1 && isRspackSwcReactRefreshEnabled(rspackConfig);

package/dist/index.js

@@ -38,6 +38,8 @@ let getAvailableCpuCount = ()=>'function' == typeof availableParallelism ? avail
 }, resolveEntryWithTemplate = ({ appDirectory, entryName, templateName, templatesDirectory })=>{
     let userEntryPath = findEntryFile(external_pathe_resolve(appDirectory, entryName));
     return existsSync(userEntryPath) ? userEntryPath : external_pathe_resolve(templatesDirectory, templateName);
+}, getModuleFederationOptions = (plugin)=>{
+    if (plugin && 'object' == typeof plugin && ('ModuleFederationPlugin' === plugin.name || 'RspackModuleFederationPlugin' === plugin.name)) return plugin._options ?? plugin.options;
 }, Function_dual = function(arity, body) {
     if ("function" == typeof arity) return function() {
         return arity(arguments) ? body.apply(this, arguments) : (self)=>body(self, ...arguments);
@@ -7356,7 +7358,10 @@ let createReactRouterManifestOptions = ({ routeChunks, routeModuleAnalysis })=>{
             routeModuleAnalysis
         } : {}
     };
-}, isManifestJsAsset = (asset)=>/(?<!\.hot-update)\.[cm]?js(?:\?.*)?$/.test(asset), isManifestCssAsset = (asset)=>/\.css(?:\?.*)?$/.test(asset), collectManifestFilesByName = (items, names, getFiles)=>{
+}, isManifestJsAsset = (asset)=>/(?<!\.hot-update)\.[cm]?js(?:\?.*)?$/.test(asset), isManifestCssAsset = (asset)=>/\.css(?:\?.*)?$/.test(asset), hasSome = (iterable)=>{
+    for (let _ of iterable)return !0;
+    return !1;
+}, collectManifestFilesByName = (items, names, getFiles)=>{
     let filesByName = {};
     if (!names) {
         for (let [name, item] of items)null != item && (filesByName[name] = getFiles(name, item));
@@ -9623,11 +9628,19 @@ export default [`;
                     'virtual/react-router/unstable_rsc/manifest-prefix': `const manifest = __webpack_require__.rscM;
 const serverPrefix = ${JSON.stringify(serverPublicPath)};
 const appliedPrefix = manifest?.moduleLoading?.prefix;
-if (appliedPrefix && appliedPrefix !== serverPrefix) {
+// An empty applied prefix (web \`assetPrefix: ''\`) yields relative references
+// such as "static/js/index.js"; those are rebased too, while absolute and
+// protocol-relative URLs are left alone.
+const isAbsoluteUrl = url => /^(?:[a-z][a-z\\d+.-]*:|\\/\\/|\\/)/i.test(url);
+if (typeof appliedPrefix === "string" && appliedPrefix !== serverPrefix) {
   const rewrite = url =>
-    typeof url === "string" && url.startsWith(appliedPrefix)
-      ? serverPrefix + url.slice(appliedPrefix.length)
-      : url;
+    typeof url !== "string"
+      ? url
+      : appliedPrefix !== "" && url.startsWith(appliedPrefix)
+        ? serverPrefix + url.slice(appliedPrefix.length)
+        : appliedPrefix === "" && !isAbsoluteUrl(url)
+          ? serverPrefix + url
+          : url;
   const rewriteAll = list => {
     if (Array.isArray(list)) for (let i = 0; i < list.length; i++) list[i] = rewrite(list[i]);
   };
@@ -10907,8 +10920,27 @@ if (typeof window !== 'undefined' && import.meta.webpackHot) {
                 initialRouteTopology: routeTopology.initialRouteTopology,
                 onRouteTopologyChange: pluginOptions.onRouteTopologyChange
             });
-            api.onAfterEnvironmentCompile(({ stats, environment })=>{
-                if ('web' === environment.name && (clientStats = createReactRouterManifestStats(stats?.compilation, manifestChunkNames)), pluginOptions.federation && ssr) {
+            if (api.onAfterEnvironmentCompile(({ stats, environment })=>{
+                if ('web' === environment.name && (clientStats = createReactRouterManifestStats(stats?.compilation, manifestChunkNames), isRscMode && stats)) {
+                    let unsupported = ((compilation)=>{
+                        let unsupported = new Set();
+                        for (let chunk of compilation.chunks){
+                            if (!(chunk.contentHash?.javascript !== void 0 || hasSome(compilation.chunkGraph.getChunkModulesIterableBySourceType(chunk, "javascript")))) continue;
+                            let pathData = {
+                                chunk,
+                                contentHashType: "javascript"
+                            }, template = chunk.canBeInitial() ? compilation.outputOptions.filename : compilation.outputOptions.chunkFilename, resolvedTemplate = 'function' == typeof template ? template(pathData) : template;
+                            if ('string' != typeof resolvedTemplate) continue;
+                            let file = compilation.getPath(resolvedTemplate, pathData);
+                            file.endsWith('.js') || unsupported.add(file);
+                        }
+                        return [
+                            ...unsupported
+                        ];
+                    })(stats.compilation);
+                    if (unsupported.length > 0) throw Error(`[${PLUGIN_NAME}] RSC mode requires every browser JavaScript asset to be named "*.js" (no query, no other extension): rspack's RSC manifest omits ${unsupported.slice(0, 5).map((asset)=>JSON.stringify(asset)).join(', ')}${unsupported.length > 5 ? ` and ${unsupported.length - 5} more` : ''}. Adjust web \`output.filename.js\` / \`chunkFilename\`.`);
+                }
+                if (pluginOptions.federation && ssr) {
                     let serverBuildDir = external_pathe_resolve(buildDirectory, 'server'), clientBuildDir = external_pathe_resolve(buildDirectory, 'client');
                     if (existsSync(serverBuildDir)) {
                         let ssrDir = external_pathe_resolve(clientBuildDir, 'static');
@@ -10952,9 +10984,7 @@ if (typeof window !== 'undefined' && import.meta.webpackHot) {
                         basename
                     })))), api.modifyRsbuildConfig(async (config, { mergeRsbuildConfig })=>{
                 var existing;
-                let publicPath, webConfig = config.environments?.web, webJsFilename = webConfig?.output?.filename?.js ?? config.output?.filename?.js;
-                if (isRscMode && 'string' == typeof webJsFilename && !/\.js$/.test(webJsFilename)) throw Error(`[${PLUGIN_NAME}] RSC mode requires web \`output.filename.js\` to end in ".js" (got ${JSON.stringify(webJsFilename)}): rspack's RSC manifest omits entry files with a query or another extension, so the server could not render bootstrap scripts.`);
-                let vmodPlugin = (publicPath = resolveEffectiveAssetPrefix({
+                let publicPath, webConfig = config.environments?.web, vmodPlugin = (publicPath = resolveEffectiveAssetPrefix({
                     dev: webConfig?.dev,
                     output: webConfig?.output,
                     isBuild
@@ -11140,16 +11170,31 @@ if (typeof window !== 'undefined' && import.meta.webpackHot) {
                     }) : rspackConfig), api.modifyEnvironmentConfig(async (config, { name, mergeEnvironmentConfig })=>'web' !== name && 'node' !== name ? config : mergeEnvironmentConfig(config, {
                         tools: {
                             rspack: (rspackConfig)=>{
-                                if (federation && ((rspackConfig)=>{
+                                if (federation) {
                                     if (rspackConfig?.plugins?.length) for (let plugin of rspackConfig.plugins){
-                                        if (!plugin || 'object' != typeof plugin || 'ModuleFederationPlugin' !== plugin.name && 'RspackModuleFederationPlugin' !== plugin.name) continue;
-                                        let pluginOptions = plugin._options ?? plugin.options;
+                                        let pluginOptions = getModuleFederationOptions(plugin);
                                         pluginOptions && (pluginOptions.experiments = {
                                             ...pluginOptions.experiments,
                                             asyncStartup: !0
                                         });
                                     }
-                                })(rspackConfig), 'node' === name) {
+                                    if ('web' === name) ((rspackConfig)=>{
+                                        let containers = new Set((rspackConfig?.plugins ?? []).map(getModuleFederationOptions).map((options)=>options?.name).filter((name)=>'string' == typeof name));
+                                        if (!rspackConfig || 0 === containers.size) return;
+                                        let current = rspackConfig.optimization?.runtimeChunk, appRuntimeName = 'object' == typeof current && 'string' == typeof current?.name ? current.name : 'runtime';
+                                        rspackConfig.optimization = {
+                                            ...rspackConfig.optimization,
+                                            runtimeChunk: {
+                                                name: (entrypoint)=>containers.has(entrypoint.name) ? `runtime-${entrypoint.name}` : appRuntimeName
+                                            }
+                                        };
+                                    })(rspackConfig);
+                                    else {
+                                        let splitChunks = rspackConfig?.optimization?.splitChunks;
+                                        if (splitChunks) for (let group of (splitChunks.chunks = 'async', Object.values(splitChunks.cacheGroups ?? {})))group && 'object' == typeof group && 'chunks' in group && (group.chunks = 'async');
+                                    }
+                                }
+                                if ('node' === name) {
                                     let output = rspackConfig.output;
                                     if (output) {
                                         let library = output.library, libraryOptions = library && 'object' == typeof library && !Array.isArray(library) ? library : {};
@@ -11171,7 +11216,20 @@ if (typeof window !== 'undefined' && import.meta.webpackHot) {
                 federation: pluginOptions.federation,
                 resolvedServerOutput,
                 webOutput: modePlan.webOutput
-            }), 'classic' === modePlan.kind && useRouteModuleTransformLoader && api.modifyEnvironmentConfig(async (config, { name, mergeEnvironmentConfig })=>'web' !== name && 'node' !== name ? config : mergeEnvironmentConfig(config, {
+            }), pluginOptions.federation && 'classic' === modePlan.kind) {
+                let browserEntryModules = new Set([
+                    finalEntryClientPath,
+                    ...routeByFilePath.keys()
+                ]);
+                api.transform({
+                    environments: [
+                        'web'
+                    ],
+                    order: 'post',
+                    test: (resourcePath)=>browserEntryModules.has(resourcePath)
+                }, ({ code })=>`${code}\nexport {};\nawait Promise.resolve();\n`);
+            }
+            'classic' === modePlan.kind && useRouteModuleTransformLoader && api.modifyEnvironmentConfig(async (config, { name, mergeEnvironmentConfig })=>'web' !== name && 'node' !== name ? config : mergeEnvironmentConfig(config, {
                     tools: {
                         rspack: (rspackConfig)=>{
                             let environmentDevHmrEnabled = 'web' === name && !isBuild && void 0 !== devHmrRefreshRuntimePath && 'development' === config.mode && config.dev?.hmr !== !1 && isRspackSwcReactRefreshEnabled(rspackConfig);

package/dist/manifest.d.ts

@@ -66,6 +66,35 @@ type ReactRouterManifestStatsCompilation = {
 };
 export declare const isManifestJsAsset: (asset: string) => boolean;
 export declare const isManifestCssAsset: (asset: string) => boolean;
+/**
+ * The minimal compilation surface for `collectUnsupportedRscScriptAssets`.
+ * Chunks are classified as JavaScript-emitting from compilation metadata (their
+ * `javascript` content hash / modules), never from a filename.
+ */
+export type RscScriptAssetCompilation = {
+    chunks: Iterable<RscScriptAssetChunk>;
+    chunkGraph: {
+        getChunkModulesIterableBySourceType(chunk: RscScriptAssetChunk, sourceType: string): Iterable<unknown>;
+    };
+    outputOptions: {
+        filename?: unknown;
+        chunkFilename?: unknown;
+    };
+    getPath(filename: string, data: Record<string, unknown>): string;
+};
+export type RscScriptAssetChunk = {
+    contentHash?: Record<string, string>;
+    canBeInitial(): boolean;
+};
+/**
+ * Browser JavaScript assets rspack's RSC manifest would drop: it only records
+ * chunk files whose emitted name ends in ".js", so `.mjs` names, query-hash
+ * names (`[name].js?v=...`), or any other extension vanish from
+ * `entryJsFiles` and the client manifest. The emitted script name is derived
+ * from the chunk's own filename template (entry or async) the same way rspack
+ * emits it, so function templates and `tools.rspack` overrides are covered.
+ */
+export declare const collectUnsupportedRscScriptAssets: (compilation: RscScriptAssetCompilation) => string[];
 export declare const createReactRouterManifestStats: (compilation: ReactRouterManifestStatsCompilation | undefined, chunkNames?: ReadonlySet<string>) => ReactRouterManifestStats | undefined;
 export type RouteManifestModuleExports = Record<string, readonly string[]>;
 export type ReactRouterManifestGenerationResult = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsbuild-plugin-react-router",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "React Router plugin for Rsbuild",
   "repository": {
     "type": "git",

package/src/environment-output.ts

@@ -1,5 +1,9 @@
 import type { RsbuildPluginAPI, Rspack } from '@rsbuild/core';
-import { ensureFederationAsyncStartup } from './federation.js';
+import {
+  enforceAsyncOnlyServerSplitChunks,
+  ensureFederationAsyncStartup,
+  isolateFederationContainerRuntime,
+} from './federation.js';
 
 /**
  * Rspack `output` policy for the web and node environments, in two tiers:
@@ -70,6 +74,11 @@ export const registerReactRouterEnvironmentOutput = ({
           rspack: rspackConfig => {
             if (federation) {
               ensureFederationAsyncStartup(rspackConfig);
+              if (name === 'web') {
+                isolateFederationContainerRuntime(rspackConfig);
+              } else {
+                enforceAsyncOnlyServerSplitChunks(rspackConfig);
+              }
             }
 
             if (name === 'node') {

package/src/federation.ts

@@ -1,9 +1,73 @@
 import type { Rspack } from '@rsbuild/core';
 
+type ModuleFederationPluginOptionsLike = {
+  name?: string;
+  experiments?: { asyncStartup?: boolean };
+};
+
 type ModuleFederationPluginLike = {
   name?: string;
-  _options?: { experiments?: { asyncStartup?: boolean } };
-  options?: { experiments?: { asyncStartup?: boolean } };
+  _options?: ModuleFederationPluginOptionsLike;
+  options?: ModuleFederationPluginOptionsLike;
+};
+
+const getModuleFederationOptions = (
+  plugin: unknown
+): ModuleFederationPluginOptionsLike | undefined => {
+  if (!plugin || typeof plugin !== 'object') {
+    return undefined;
+  }
+  const federationPlugin = plugin as ModuleFederationPluginLike;
+  if (
+    federationPlugin.name !== 'ModuleFederationPlugin' &&
+    federationPlugin.name !== 'RspackModuleFederationPlugin'
+  ) {
+    return undefined;
+  }
+  return federationPlugin._options ?? federationPlugin.options;
+};
+
+/**
+ * The Module Federation container name(s) configured on this compiler, i.e.
+ * the entry names of the remote containers it emits.
+ */
+export const getFederationContainerNames = (
+  rspackConfig: Rspack.Configuration | undefined
+): string[] =>
+  (rspackConfig?.plugins ?? [])
+    .map(getModuleFederationOptions)
+    .map(options => options?.name)
+    .filter((name): name is string => typeof name === 'string');
+
+/**
+ * Classic mode shares one runtime chunk across every browser entry so route
+ * module entries share a module registry. A federation container must not
+ * share it: importing the container would run the app entries' async startup
+ * (share-scope consumes) before the host has initialized the share scope,
+ * yielding duplicate singletons (a second React). Give containers their own
+ * runtime chunk.
+ */
+export const isolateFederationContainerRuntime = (
+  rspackConfig: Rspack.Configuration | undefined
+): void => {
+  const containers = new Set(getFederationContainerNames(rspackConfig));
+  if (!rspackConfig || containers.size === 0) {
+    return;
+  }
+  const current = rspackConfig.optimization?.runtimeChunk;
+  const appRuntimeName =
+    typeof current === 'object' && typeof current?.name === 'string'
+      ? current.name
+      : 'runtime';
+  rspackConfig.optimization = {
+    ...rspackConfig.optimization,
+    runtimeChunk: {
+      name: (entrypoint: { name: string }) =>
+        containers.has(entrypoint.name)
+          ? `runtime-${entrypoint.name}`
+          : appRuntimeName,
+    },
+  };
 };
 
 export const ensureFederationAsyncStartup = (
@@ -14,18 +78,7 @@ export const ensureFederationAsyncStartup = (
   }
 
   for (const plugin of rspackConfig.plugins) {
-    if (!plugin || typeof plugin !== 'object') {
-      continue;
-    }
-    const federationPlugin = plugin as ModuleFederationPluginLike;
-    if (
-      federationPlugin.name !== 'ModuleFederationPlugin' &&
-      federationPlugin.name !== 'RspackModuleFederationPlugin'
-    ) {
-      continue;
-    }
-
-    const pluginOptions = federationPlugin._options ?? federationPlugin.options;
+    const pluginOptions = getModuleFederationOptions(plugin);
     if (!pluginOptions) {
       continue;
     }
@@ -36,3 +89,29 @@ export const ensureFederationAsyncStartup = (
     };
   }
 };
+
+/**
+ * `@module-federation/node` replaces Rspack's `readFileVm` chunk loader with one
+ * that tracks loaded chunks privately, so initial chunks split off a
+ * multi-entry server build never satisfy Rspack's startup gate
+ * (`__webpack_require__.O`) and the async startup resolves to `undefined`
+ * instead of the server build's exports. Keep server code splitting to async
+ * chunks only. Runs at the final `tools.rspack` boundary so a user
+ * `optimization.splitChunks` override or a preset whose cache group selects
+ * `chunks: 'all'` (e.g. Rsbuild's `single-vendor`, `enforce: true`) cannot
+ * reintroduce initial chunk dependencies. A disabled `splitChunks` is kept.
+ */
+export const enforceAsyncOnlyServerSplitChunks = (
+  rspackConfig: Rspack.Configuration | undefined
+): void => {
+  const splitChunks = rspackConfig?.optimization?.splitChunks;
+  if (!splitChunks) {
+    return;
+  }
+  splitChunks.chunks = 'async';
+  for (const group of Object.values(splitChunks.cacheGroups ?? {})) {
+    if (group && typeof group === 'object' && 'chunks' in group) {
+      group.chunks = 'async';
+    }
+  }
+};

package/src/index.ts

@@ -26,6 +26,7 @@ import {
   type ResolvedReactRouterConfig,
 } from './react-router-config.js';
 import {
+  collectUnsupportedRscScriptAssets,
   configRoutesToRouteManifest,
   createReactRouterManifestStats,
   type ReactRouterManifestForDev as ReactRouterManifest,
@@ -773,6 +774,27 @@ export const pluginReactRouter = (
           stats?.compilation,
           manifestChunkNames
         );
+        if (isRscMode && stats) {
+          // Rspack's RSC manifest only records browser scripts whose emitted
+          // name ends in ".js" (entry files and client-reference chunks
+          // alike); anything else silently disappears from `entryJsFiles` and
+          // the client manifest, and the server cannot bootstrap or preload
+          // it. Check the emitted output, which is what the manifest saw, so
+          // function filenames and `tools.rspack` overrides are covered too.
+          const unsupported = collectUnsupportedRscScriptAssets(
+            stats.compilation
+          );
+          if (unsupported.length > 0) {
+            throw new Error(
+              `[${PLUGIN_NAME}] RSC mode requires every browser JavaScript asset to be named "*.js" (no query, no other extension): rspack's RSC manifest omits ${unsupported
+                .slice(0, 5)
+                .map(asset => JSON.stringify(asset))
+                .join(
+                  ', '
+                )}${unsupported.length > 5 ? ` and ${unsupported.length - 5} more` : ''}. Adjust web \`output.filename.js\` / \`chunkFilename\`.`
+            );
+          }
+        }
       }
       if (pluginOptions.federation && ssr) {
         const serverBuildDir = resolve(buildDirectory, 'server');
@@ -848,22 +870,6 @@ export const pluginReactRouter = (
 
     api.modifyRsbuildConfig(async (config, { mergeRsbuildConfig }) => {
       const webConfig = config.environments?.web;
-      const webJsFilename =
-        webConfig?.output?.filename?.js ?? config.output?.filename?.js;
-      // Rspack's RSC manifest only records browser entry files named `*.js`
-      // (`entryJsFiles`), and the server renders its bootstrap scripts from
-      // that list. Reject filename schemes it would silently drop up front.
-      if (
-        isRscMode &&
-        typeof webJsFilename === 'string' &&
-        !/\.js$/.test(webJsFilename)
-      ) {
-        throw new Error(
-          `[${PLUGIN_NAME}] RSC mode requires web \`output.filename.js\` to end in ".js" (got ${JSON.stringify(
-            webJsFilename
-          )}): rspack's RSC manifest omits entry files with a query or another extension, so the server could not render bootstrap scripts.`
-        );
-      }
       const assetPrefix = resolveEffectiveAssetPrefix(
         { dev: webConfig?.dev, output: webConfig?.output, isBuild },
         { dev: config.dev, output: config.output }
@@ -1044,6 +1050,31 @@ export const pluginReactRouter = (
       webOutput: modePlan.webOutput,
     });
 
+    if (pluginOptions.federation && modePlan.kind === 'classic') {
+      // Module Federation's async startup makes every entry's startup a
+      // promise. React Router imports each browser route-module entry
+      // synchronously (`import * as route0 from ".../root.js"`) and reads its
+      // exports right away, and `import()`s split route chunks the same way.
+      // Making those entry modules async (top-level await) turns Rspack's
+      // module-library export into `(await startup).default`, so importers
+      // wait for the awaited startup instead of reading a snapshot of the
+      // promise (#132). Runs after SWC so it applies to the final module code.
+      const browserEntryModules = new Set([
+        finalEntryClientPath,
+        ...routeByFilePath.keys(),
+      ]);
+      api.transform(
+        {
+          environments: ['web'],
+          order: 'post',
+          test: (resourcePath: string) => browserEntryModules.has(resourcePath),
+        },
+        // `export {}` keeps an otherwise-empty client module (a route with only
+        // server exports) parsed as ESM, which top-level await requires.
+        ({ code }) => `${code}\nexport {};\nawait Promise.resolve();\n`
+      );
+    }
+
     if (modePlan.kind === 'classic' && useRouteModuleTransformLoader) {
       api.modifyEnvironmentConfig(
         async (config, { name, mergeEnvironmentConfig }) => {

package/src/manifest.ts

@@ -179,6 +179,79 @@ export const isManifestJsAsset = (asset: string): boolean =>
 export const isManifestCssAsset = (asset: string): boolean =>
   /\.css(?:\?.*)?$/.test(asset);
 
+/**
+ * The minimal compilation surface for `collectUnsupportedRscScriptAssets`.
+ * Chunks are classified as JavaScript-emitting from compilation metadata (their
+ * `javascript` content hash / modules), never from a filename.
+ */
+export type RscScriptAssetCompilation = {
+  chunks: Iterable<RscScriptAssetChunk>;
+  chunkGraph: {
+    getChunkModulesIterableBySourceType(
+      chunk: RscScriptAssetChunk,
+      sourceType: string
+    ): Iterable<unknown>;
+  };
+  outputOptions: {
+    filename?: unknown;
+    chunkFilename?: unknown;
+  };
+  getPath(filename: string, data: Record<string, unknown>): string;
+};
+
+export type RscScriptAssetChunk = {
+  contentHash?: Record<string, string>;
+  canBeInitial(): boolean;
+};
+
+const hasSome = (iterable: Iterable<unknown>): boolean => {
+  for (const _ of iterable) {
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Browser JavaScript assets rspack's RSC manifest would drop: it only records
+ * chunk files whose emitted name ends in ".js", so `.mjs` names, query-hash
+ * names (`[name].js?v=...`), or any other extension vanish from
+ * `entryJsFiles` and the client manifest. The emitted script name is derived
+ * from the chunk's own filename template (entry or async) the same way rspack
+ * emits it, so function templates and `tools.rspack` overrides are covered.
+ */
+export const collectUnsupportedRscScriptAssets = (
+  compilation: RscScriptAssetCompilation
+): string[] => {
+  const unsupported = new Set<string>();
+  for (const chunk of compilation.chunks) {
+    const emitsJavaScript =
+      chunk.contentHash?.javascript !== undefined ||
+      hasSome(
+        compilation.chunkGraph.getChunkModulesIterableBySourceType(
+          chunk,
+          'javascript'
+        )
+      );
+    if (!emitsJavaScript) {
+      continue;
+    }
+    const pathData = { chunk, contentHashType: 'javascript' };
+    const template = chunk.canBeInitial()
+      ? compilation.outputOptions.filename
+      : compilation.outputOptions.chunkFilename;
+    const resolvedTemplate =
+      typeof template === 'function' ? template(pathData) : template;
+    if (typeof resolvedTemplate !== 'string') {
+      continue;
+    }
+    const file = compilation.getPath(resolvedTemplate, pathData);
+    if (!file.endsWith('.js')) {
+      unsupported.add(file);
+    }
+  }
+  return [...unsupported];
+};
+
 const collectManifestFilesByName = <T>(
   items: ReactRouterManifestStatsLookup<T>,
   names: ReadonlySet<string> | undefined,

package/src/rsc-virtual-modules.ts

@@ -127,11 +127,19 @@ export const createReactRouterRscVirtualModules = ({
     'virtual/react-router/unstable_rsc/manifest-prefix': `const manifest = __webpack_require__.rscM;
 const serverPrefix = ${JSON.stringify(serverPublicPath)};
 const appliedPrefix = manifest?.moduleLoading?.prefix;
-if (appliedPrefix && appliedPrefix !== serverPrefix) {
+// An empty applied prefix (web \`assetPrefix: ''\`) yields relative references
+// such as "static/js/index.js"; those are rebased too, while absolute and
+// protocol-relative URLs are left alone.
+const isAbsoluteUrl = url => /^(?:[a-z][a-z\\d+.-]*:|\\/\\/|\\/)/i.test(url);
+if (typeof appliedPrefix === "string" && appliedPrefix !== serverPrefix) {
   const rewrite = url =>
-    typeof url === "string" && url.startsWith(appliedPrefix)
-      ? serverPrefix + url.slice(appliedPrefix.length)
-      : url;
+    typeof url !== "string"
+      ? url
+      : appliedPrefix !== "" && url.startsWith(appliedPrefix)
+        ? serverPrefix + url.slice(appliedPrefix.length)
+        : appliedPrefix === "" && !isAbsoluteUrl(url)
+          ? serverPrefix + url
+          : url;
   const rewriteAll = list => {
     if (Array.isArray(list)) for (let i = 0; i < list.length; i++) list[i] = rewrite(list[i]);
   };