rsbuild-plugin-react-router 0.6.6 → 0.7.1

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

@@ -6,11 +6,7 @@ import { rspack, type RsbuildPlugin, type Rspack } from '@rsbuild/core';
 import { relative, resolve } from 'pathe';
 
 import { getDefaultConcurrency } from './concurrency.js';
-import {
-  DEFAULT_JS_DIST_PATH,
-  JS_EXTENSIONS,
-  PLUGIN_NAME,
-} from './constants.js';
+import { JS_EXTENSIONS, PLUGIN_NAME } from './constants.js';
 import { guardReactRouterLazyCompilation } from './lazy-compilation.js';
 import {
   findEntryFile,
@@ -30,6 +26,7 @@ import {
   type ResolvedReactRouterConfig,
 } from './react-router-config.js';
 import {
+  collectUnsupportedRscScriptAssets,
   configRoutesToRouteManifest,
   createReactRouterManifestStats,
   type ReactRouterManifestForDev as ReactRouterManifest,
@@ -222,13 +219,25 @@ export const pluginReactRouter = (
       warnOnClientSourceMaps(normalized, msg => api.logger.warn(msg), 'web');
     });
 
+    // The manifest / server `publicPath` follows the web environment's asset
+    // prefix because that is where the browser assets are served from. A web
+    // prefix the server cannot use (`'auto'`) falls back to the root prefix,
+    // so `output.assetPrefix: 'https://cdn/'` + web `'auto'` still emits CDN
+    // URLs from the server.
     api.onBeforeCreateCompiler(() => {
-      const normalized = api.getNormalizedConfig();
-      assetPrefix = resolveEffectiveAssetPrefix({
-        dev: normalized.dev,
-        output: normalized.output,
-        isBuild: api.context.action === 'build',
-      });
+      const root = api.getNormalizedConfig();
+      // `getNormalizedConfig({ environment: 'web' })` throws when the build was
+      // narrowed to other environments (`--environment node`), so look the web
+      // environment up on the root config instead.
+      const web = root.environments.web;
+      assetPrefix = resolveEffectiveAssetPrefix(
+        {
+          dev: web?.dev,
+          output: web?.output,
+          isBuild: api.context.action === 'build',
+        },
+        { dev: root.dev, output: root.output }
+      );
     });
 
     const configPath = findEntryFile(resolve('react-router.config'));
@@ -765,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');
@@ -832,39 +862,19 @@ export const pluginReactRouter = (
     }
 
     // Public requests stay bare while Rspack resolves seeded virtual files.
-    const createVirtualModulePlugin = (
-      publicPath: string,
-      jsDistPath: string
-    ) => {
+    const createVirtualModulePlugin = (publicPath: string) => {
       return new rspack.experiments.VirtualModulesPlugin(
-        mapVirtualModules(modePlan.createVirtualModules(publicPath, jsDistPath))
+        mapVirtualModules(modePlan.createVirtualModules(publicPath))
       );
     };
 
     api.modifyRsbuildConfig(async (config, { mergeRsbuildConfig }) => {
-      // The RSC bootstrap script URL must reflect the user's web js distPath;
-      // the entry filename itself is deterministic because the plugin forces
-      // web `output.filename.js` to '[name].js' below.
-      const webDistPath = config.environments?.web?.output?.distPath;
-      const rootDistPath = config.output?.distPath;
-      const jsDistPath =
-        (typeof webDistPath === 'object' ? webDistPath.js : undefined) ??
-        (typeof rootDistPath === 'object' ? rootDistPath.js : undefined) ??
-        DEFAULT_JS_DIST_PATH;
-      const assetPrefix = resolveEffectiveAssetPrefix({
-        dev: config.dev,
-        output: config.output,
-        isBuild,
-      });
-      const vmodPlugin = createVirtualModulePlugin(assetPrefix, jsDistPath);
-      const useAsyncNodeChunkLoading =
-        options.federation && resolvedServerOutput === 'commonjs';
-      let nodeChunkLoading: 'import' | 'async-node' | 'require' = 'require';
-      if (resolvedServerOutput === 'module') {
-        nodeChunkLoading = 'import';
-      } else if (useAsyncNodeChunkLoading) {
-        nodeChunkLoading = 'async-node';
-      }
+      const webConfig = config.environments?.web;
+      const assetPrefix = resolveEffectiveAssetPrefix(
+        { dev: webConfig?.dev, output: webConfig?.output, isBuild },
+        { dev: config.dev, output: config.output }
+      );
+      const vmodPlugin = createVirtualModulePlugin(assetPrefix);
       const configuredLazyCompilation = Object.prototype.hasOwnProperty.call(
         options,
         'lazyCompilation'
@@ -964,9 +974,6 @@ export const pluginReactRouter = (
                   }),
             },
             output: {
-              filename: {
-                js: '[name].js',
-              },
               distPath: {
                 root: outputClientPath,
               },
@@ -985,15 +992,6 @@ export const pluginReactRouter = (
                   ],
                 },
                 externalsType: modePlan.webExternalsType,
-                output: {
-                  ...modePlan.webOutput,
-                  publicPath: assetPrefix,
-                  ...(options.federation
-                    ? {
-                        chunkLoading: 'import',
-                      }
-                    : {}),
-                },
                 optimization: modePlan.webOptimization,
               },
             },
@@ -1038,17 +1036,6 @@ export const pluginReactRouter = (
                 externals: modePlan.nodeExternals,
                 ...modePlan.nodeDependencies,
                 externalsType: resolvedServerOutput,
-                output: {
-                  chunkFormat: resolvedServerOutput,
-                  chunkLoading: nodeChunkLoading,
-                  devtoolModuleFilenameTemplate: '[absolute-resource-path]',
-                  devtoolFallbackModuleFilenameTemplate:
-                    '[absolute-resource-path]?[hash]',
-                  workerChunkLoading: nodeChunkLoading,
-                  wasmLoading: 'fetch',
-                  module: resolvedServerOutput === 'module',
-                  chunkFilename: 'static/js/async/[name].js',
-                },
               },
             },
           },
@@ -1060,8 +1047,34 @@ export const pluginReactRouter = (
       api,
       federation: pluginOptions.federation,
       resolvedServerOutput,
+      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

@@ -167,18 +167,89 @@ type ReactRouterManifestStatsCompilation = {
   entrypoints?: ReactRouterManifestStatsLookup<ReactRouterManifestStatsEntrypoint>;
 };
 
-const orderChunkFiles = (chunkName: string, files: string[]): string[] => {
-  const ownChunkAsset = `${chunkName}.js`;
-  const ownFileIndex = files.findIndex(file => file.endsWith(ownChunkAsset));
-  if (ownFileIndex <= 0) {
-    return files;
+// Emitted asset names may carry a query (`output.filename.js:
+// '[name].js?v=[contenthash:8]'`); classify on the pathname but keep the full
+// reference, since the query is part of the URL the browser must request.
+// A chunk's own script is whatever JavaScript the compilation rendered for it,
+// regardless of `output.filename` scheme. In development, HMR update files are
+// also recorded on `chunk.files`; they are never the module to load.
+export const isManifestJsAsset = (asset: string): boolean =>
+  /(?<!\.hot-update)\.[cm]?js(?:\?.*)?$/.test(asset);
+
+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;
+};
 
-  return [
-    files[ownFileIndex],
-    ...files.slice(0, ownFileIndex),
-    ...files.slice(ownFileIndex + 1),
-  ];
+/**
+ * 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>(
@@ -241,8 +312,7 @@ export const createReactRouterManifestStats = (
   const assetsByChunkName = collectManifestFilesByName(
     compilation.namedChunks,
     chunkNames,
-    (chunkName, chunk) =>
-      orderChunkFiles(chunkName, Array.from(chunk.files ?? []))
+    (_chunkName, chunk) => Array.from(chunk.files ?? [])
   );
   const entrypointFilesByName = compilation.entrypoints
     ? collectManifestFilesByName(
@@ -303,22 +373,31 @@ const createChunkAssetResolver = (
 
     const cssAssets = new Set<string>();
     const jsAssets = new Set<string>();
+    // The chunk's own files come first so `js[0]` is the route module itself;
+    // entrypoint files (runtime, shared vendor chunks) follow as `imports`.
     for (const asset of assets) {
-      if (asset.endsWith('.css')) {
+      if (isManifestCssAsset(asset)) {
         cssAssets.add(asset);
-      } else if (asset.endsWith('.js')) {
+      } else if (isManifestJsAsset(asset)) {
         jsAssets.add(asset);
       }
     }
     for (const asset of clientStats?.entrypointFilesByName?.[chunkName] ?? []) {
-      if (asset.endsWith('.css')) {
+      if (isManifestCssAsset(asset)) {
         cssAssets.add(asset);
-      } else if (includeEntrypointJs && asset.endsWith('.js')) {
+      } else if (includeEntrypointJs && isManifestJsAsset(asset)) {
         jsAssets.add(asset);
       }
     }
     if (jsAssets.size === 0) {
-      jsAssets.add(`${DEFAULT_MANIFEST_DIR}/${chunkName}.js`);
+      // Compilation metadata exists for this chunk but names no module script.
+      // Guessing `<dir>/<chunk>.js` here would turn an identifiable build
+      // problem into a browser 404, so surface it at build time instead.
+      throw new Error(
+        `[react-router] Chunk "${chunkName}" emitted no JavaScript asset the browser manifest can reference (files: ${
+          assets.join(', ') || 'none'
+        }). Check the web \`output.filename.js\` scheme.`
+      );
     }
 
     const result = { js: [...jsAssets], css: [...cssAssets] };

package/src/mode-plan.ts

@@ -36,10 +36,7 @@ type CommonModePlan = {
   manifestChunkNames: Set<string>;
   webEntries: Record<string, string | RsbuildEntryDescription>;
   nodeEntries: Record<string, string | RsbuildEntryDescription>;
-  createVirtualModules(
-    publicPath: string,
-    jsDistPath: string
-  ): Record<string, string>;
+  createVirtualModules(publicPath: string): Record<string, string>;
   createResolveConfig(rootPath: string): Rspack.Configuration['resolve'];
   server: RsbuildConfig['server'] | undefined;
   webExternalsType: 'module' | undefined;
@@ -183,14 +180,13 @@ const createRscModePlan = async ({
         layer: RSC_LAYERS.rsc,
       },
     },
-    createVirtualModules: (publicPath: string, jsDistPath: string) =>
+    createVirtualModules: (publicPath: string) =>
       createReactRouterRscVirtualModules({
         allowedActionOrigins: allowedActionOriginsForBuild,
         appDirectory,
         basename,
         buildDirectory,
         isBuild,
-        jsDistPath,
         outputClientPath,
         publicPath,
         routeDiscovery,
@@ -314,7 +310,7 @@ const createClassicModePlan = async ({
       defaultEntryName,
       serverBundleEntries: artifacts.serverBundleEntries,
     }),
-    createVirtualModules: (publicPath: string, _jsDistPath: string) =>
+    createVirtualModules: (publicPath: string) =>
       createClassicVirtualModules({
         allowedActionOrigins: allowedActionOriginsForBuild,
         appDirectory,
@@ -349,11 +345,9 @@ const createClassicModePlan = async ({
       wasmLoading: 'fetch',
       library: { type: 'module' },
       module: true,
-      // Async chunks are addressed by id at runtime, so the chunk name only
-      // adds bytes to the filename and to every place that references it.
-      ...(isBuild
-        ? { chunkFilename: 'static/js/async/[id]-[contenthash:16].js' }
-        : {}),
+      // Async chunk filenames are left to Rsbuild, which derives them from
+      // `output.filename.js`, `output.filenameHash`, and `distPath.jsAsync`,
+      // so user configuration governs every JavaScript filename (#129).
     },
     webOptimization: {
       avoidEntryIife: true,

package/src/modify-browser-manifest.ts

@@ -7,6 +7,7 @@ import {
   generateReactRouterManifestForDev,
   getReactRouterManifestChunkNames,
   getReactRouterManifestPath,
+  isManifestJsAsset,
   type ReactRouterManifestForDev as ReactRouterManifest,
   type RouteChunkManifestOptions,
   type RouteManifestModuleExports,
@@ -83,7 +84,7 @@ const addIntegrity = (
 ) => {
   if (
     typeof assetName !== 'string' ||
-    !assetName.endsWith('.js') ||
+    !isManifestJsAsset(assetName) ||
     typeof integrity !== 'string'
   ) {
     return;
@@ -117,7 +118,7 @@ export const collectSubresourceIntegrity = (
     const assets =
       compilation.getAssets() as readonly CompilationAssetWithIntegrity[];
     for (const asset of assets) {
-      if (!asset.name.endsWith('.js')) {
+      if (!isManifestJsAsset(asset.name)) {
         continue;
       }
       addIntegrity(
@@ -200,8 +201,7 @@ export function registerModifyBrowserManifestAssets(
 
     if (isBuild) {
       const entryAssets = stats?.assetsByChunkName?.['entry.client'];
-      const entryJsAssets =
-        entryAssets?.filter(asset => asset.endsWith('.js')) || [];
+      const entryJsAssets = entryAssets?.filter(isManifestJsAsset) || [];
       const manifestPath = getReactRouterManifestPath({
         version: manifest.version,
         isBuild: true,

package/src/plugin-utils.ts

@@ -79,34 +79,48 @@ export function normalizeAssetPrefix(assetPrefix?: string): string {
   return assetPrefix.endsWith('/') ? assetPrefix : `${assetPrefix}/`;
 }
 
+type AssetPrefixConfig = {
+  dev?: { assetPrefix?: unknown };
+  output?: { assetPrefix?: unknown };
+};
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined;
+
+const pickConfiguredAssetPrefix = (
+  { dev, output }: AssetPrefixConfig,
+  isBuild: boolean
+): string | undefined =>
+  isBuild
+    ? asString(output?.assetPrefix)
+    : (asString(dev?.assetPrefix) ?? asString(output?.assetPrefix));
+
 /**
- * Resolve the asset prefix Rsbuild applies to emitted asset URLs for the given
- * mode. In development the effective prefix is `dev.assetPrefix` (which Rsbuild
- * defaults from `server.base`, falling back to `output.assetPrefix`); in a
- * production build it is `output.assetPrefix`. Both fields are already resolved
- * on the normalized config, so this mirrors Rsbuild's own precedence rather than
- * re-deriving it from `server.base`.
+ * Resolve the absolute asset prefix the server build and browser manifest use
+ * for asset URLs. In development the effective prefix is `dev.assetPrefix`
+ * (which Rsbuild defaults from `server.base`, falling back to
+ * `output.assetPrefix`); in a production build it is `output.assetPrefix`.
+ *
+ * `fallbacks` are consulted in order (e.g. the root config after the web
+ * environment) when the preceding config only offers a prefix the server
+ * cannot use: `'auto'` and empty values are browser-runtime-only, so a root
+ * CDN prefix must survive a web `'auto'`. The choice happens before
+ * normalization so that `'auto'` is not first folded into `'/'`.
  *
  * `dev.assetPrefix` may be a boolean on the raw config (`false` disables it);
- * boolean/`'auto'`/empty values normalize to the root prefix `'/'`.
+ * boolean/`'auto'`/empty values ultimately normalize to the root prefix `'/'`.
  */
-export function resolveEffectiveAssetPrefix(config: {
-  dev?: { assetPrefix?: unknown };
-  output?: { assetPrefix?: unknown };
-  isBuild: boolean;
-}): string {
-  const outputPrefix =
-    typeof config.output?.assetPrefix === 'string'
-      ? config.output.assetPrefix
-      : undefined;
-  if (config.isBuild) {
-    return normalizeAssetPrefix(outputPrefix);
+export function resolveEffectiveAssetPrefix(
+  config: AssetPrefixConfig & { isBuild: boolean },
+  ...fallbacks: AssetPrefixConfig[]
+): string {
+  for (const candidate of [config, ...fallbacks]) {
+    const prefix = pickConfiguredAssetPrefix(candidate, config.isBuild);
+    if (prefix && prefix !== 'auto') {
+      return normalizeAssetPrefix(prefix);
+    }
   }
-  const devPrefix =
-    typeof config.dev?.assetPrefix === 'string'
-      ? config.dev.assetPrefix
-      : undefined;
-  return normalizeAssetPrefix(devPrefix ?? outputPrefix);
+  return '/';
 }
 
 export function createRouteId(file: string): string {

package/src/rsc-route-transforms.ts

@@ -623,6 +623,12 @@ const createServerRouteEntry = async (
   let needsReactImport = false;
   let needsEnsureHmrImport = false;
   let needsStyleEntryImport = false;
+  const pushStylesheetLinks = (entryCssFilesExpression: string): void => {
+    lines.push(`    ...(${entryCssFilesExpression} ?? []).map(href =>`);
+    lines.push(
+      '      React.createElement("link", { key: href, rel: "stylesheet", href: href, precedence: "default" })),'
+    );
+  };
 
   // A client route whose default component is a client reference: its bundled
   // (non-vanilla) side-effect CSS is orphaned in the initial browser entry
@@ -651,12 +657,7 @@ const createServerRouteEntry = async (
         'export default function RscClientRouteWithStyles___(props) {'
       );
       lines.push('  return React.createElement(React.Fragment, null,');
-      lines.push(
-        `    ...(${RSC_ROUTE_STYLE_ENTRY_EXPORT}.entryCssFiles ?? []).map(href =>`
-      );
-      lines.push(
-        '      React.createElement("link", { key: href, rel: "stylesheet", href: href, precedence: "default" })),'
-      );
+      pushStylesheetLinks(`${RSC_ROUTE_STYLE_ENTRY_EXPORT}.entryCssFiles`);
       lines.push('    React.createElement(RscClientRouteDefault___, props),');
       lines.push('  );');
       lines.push('}');
@@ -682,12 +683,7 @@ const createServerRouteEntry = async (
       // graph contributes. Render those as stylesheet links at the top of the
       // stream (mirrors upstream's `import.meta.viteRsc.loadCss()`); React's
       // float support hoists them into `<head>`.
-      lines.push(
-        `    ...(${exportName}WithoutClientChunk.entryCssFiles ?? []).map(href =>`
-      );
-      lines.push(
-        '      React.createElement("link", { key: href, rel: "stylesheet", href: href, precedence: "default" })),'
-      );
+      pushStylesheetLinks(`${exportName}WithoutClientChunk.entryCssFiles`);
       lines.push(
         '    React.createElement(EnsureClientRouteModuleForHMR___, null),'
       );