rsbuild-plugin-react-router 0.5.0 → 0.6.0

package/src/build-output-transforms.ts

@@ -3,19 +3,77 @@ import jsesc from 'jsesc';
 import { relative } from 'pathe';
 import { PLUGIN_NAME } from './constants.js';
 import {
+  createReactRouterManifestOptions,
   getReactRouterManifestForDev,
+  type ReactRouterManifestForDev as ReactRouterManifest,
+  type RouteChunkManifestOptions,
+  type RouteModuleAnalysisProvider,
   type ReactRouterManifestStats,
 } from './manifest.js';
 import type { ReactRouterPerformanceProfiler } from './performance.js';
+import {
+  validateSpaModeRouteExports,
+  type RouteTransformRunner,
+} from './route-transform-tasks.js';
 import { createBundlerRouteExportResolver } from './route-export-resolution.js';
-import type { RouteChunkConfig } from './route-chunks.js';
-import type { RouteTransformRunner } from './route-transform-tasks.js';
+import {
+  getRouteChunkNameFromModuleId,
+  type RouteChunkConfig,
+} from './route-chunks.js';
 import type { PluginOptions, Route } from './types.js';
 import { isSourceMapEnabled } from './warnings/warn-on-client-source-maps.js';
+import {
+  analyzeRouteModuleCode,
+  type RouteModuleAnalysis,
+} from './export-utils.js';
+import {
+  relocateServerAssetsToClient,
+  type RelocatableAssetCompilation,
+} from './ssr-asset-relocation.js';
 
-type ReactRouterManifest = Awaited<
-  ReturnType<typeof getReactRouterManifestForDev>
->;
+/**
+ * Register the node-compilation hook that relocates server-only static assets
+ * (`?url` imports, `.css?url` files, and other `asset/resource` outputs
+ * referenced only by loaders or `.server` modules) into the client build. The
+ * loader/`links()` export returns the asset URL to the client, which fetches it
+ * from `build/client` at runtime, so the file must exist there even though only
+ * the node compilation referenced it. The assets are also stripped from the
+ * server build to avoid shipping duplicate static files, mirroring upstream
+ * React Router's Vite plugin. This runs for every node compilation, so it also
+ * covers `serverBundles` (multiple node outputs) and dev mode (where
+ * `writeToDisk` is enabled).
+ *
+ * Registered by both the classic build-output transforms and the RSC branch so
+ * `.css?url`/`?url` assets referenced from `links()` resolve in RSC framework
+ * mode too.
+ */
+export const registerSsrAssetRelocation = ({
+  api,
+  outputClientPath,
+  performanceProfiler,
+}: {
+  api: RsbuildPluginAPI;
+  outputClientPath: string;
+  performanceProfiler: ReactRouterPerformanceProfiler;
+}): void => {
+  const relocatedDestinations = new Map<string, string>();
+  api.processAssets(
+    { stage: 'report', targets: ['node'] },
+    async ({ compilation }) => {
+      await performanceProfiler.record(
+        'node',
+        'assets:relocate-ssr-only',
+        'ssr-only-assets',
+        () =>
+          relocateServerAssetsToClient({
+            compilation: compilation as unknown as RelocatableAssetCompilation,
+            outputClientPath,
+            relocatedDestinations,
+          })
+      );
+    }
+  );
+};
 
 type RegisterBuildOutputTransformsOptions = {
   api: RsbuildPluginAPI;
@@ -30,7 +88,8 @@ type RegisterBuildOutputTransformsOptions = {
   getClientStats: () => ReactRouterManifestStats | undefined;
   appDirectory: string;
   getAssetPrefix: () => string;
-  routeChunkOptions: Parameters<typeof getReactRouterManifestForDev>[5];
+  routeChunkOptions: RouteChunkManifestOptions | undefined;
+  routeModuleAnalysis?: RouteModuleAnalysisProvider;
   routeTransformRunner: RouteTransformRunner;
   routeByFilePath: Map<string, Route>;
   routeChunkConfig: RouteChunkConfig;
@@ -40,7 +99,12 @@ type RegisterBuildOutputTransformsOptions = {
   ssr: boolean;
   isSpaMode: boolean;
   rootRoutePath: string;
+  outputClientPath: string;
   isDevHmrEnabled?: () => boolean;
+  onRouteModuleAnalysis?: (
+    resourcePath: string,
+    analysis: RouteModuleAnalysis
+  ) => void;
 };
 
 export const registerBuildOutputTransforms = ({
@@ -55,6 +119,7 @@ export const registerBuildOutputTransforms = ({
   appDirectory,
   getAssetPrefix,
   routeChunkOptions,
+  routeModuleAnalysis,
   routeTransformRunner,
   routeByFilePath,
   routeChunkConfig,
@@ -64,10 +129,26 @@ export const registerBuildOutputTransforms = ({
   ssr,
   isSpaMode,
   rootRoutePath,
+  outputClientPath,
   isDevHmrEnabled = () => false,
+  onRouteModuleAnalysis,
 }: RegisterBuildOutputTransformsOptions): void => {
-  const transformRouteModule = async (args: Parameters<TransformHandler>[0]) =>
-    performanceProfiler.record(
+  const rememberRouteModuleAnalysis = (
+    args: Parameters<TransformHandler>[0]
+  ): void => {
+    if (!routeByFilePath.has(args.resourcePath)) {
+      return;
+    }
+    onRouteModuleAnalysis?.(
+      args.resourcePath,
+      analyzeRouteModuleCode(args.code)
+    );
+  };
+
+  const transformRouteModule = async (
+    args: Parameters<TransformHandler>[0]
+  ) => {
+    return performanceProfiler.record(
       args.environment?.name,
       'route:module',
       args.resource,
@@ -88,6 +169,7 @@ export const registerBuildOutputTransforms = ({
           devHmr: isDevHmrEnabled(),
         })
     );
+  };
 
   api.processAssets(
     { stage: 'additional', targets: ['node'] },
@@ -105,6 +187,8 @@ export const registerBuildOutputTransforms = ({
     }
   );
 
+  registerSsrAssetRelocation({ api, outputClientPath, performanceProfiler });
+
   api.transform(
     {
       test: /virtual\/react-router\/(browser|server)-manifest/,
@@ -137,7 +221,10 @@ export const registerBuildOutputTransforms = ({
               getClientStats(),
               appDirectory,
               getAssetPrefix(),
-              routeChunkOptions
+              createReactRouterManifestOptions({
+                routeChunks: routeChunkOptions,
+                routeModuleAnalysis,
+              })
             ));
           return {
             code: `export default ${jsesc(manifest, { es6: true })};`,
@@ -149,9 +236,11 @@ export const registerBuildOutputTransforms = ({
   api.transform(
     {
       resourceQuery: /__react-router-build-client-route/,
+      order: 'post',
     },
-    async args =>
-      performanceProfiler.record(
+    async args => {
+      rememberRouteModuleAnalysis(args);
+      return performanceProfiler.record(
         args.environment?.name,
         'route:client-entry',
         args.resource,
@@ -166,29 +255,67 @@ export const registerBuildOutputTransforms = ({
             routeId: routeByFilePath.get(args.resourcePath)?.id,
             devHmr: isDevHmrEnabled(),
           })
-      )
+      );
+    }
   );
 
   api.transform(
     {
       resourceQuery: /route-chunk=/,
       environments: ['web'],
+      order: 'post',
     },
-    async args =>
-      performanceProfiler.record(
+    async args => {
+      return performanceProfiler.record(
         args.environment?.name,
         'route:chunk',
         args.resource,
-        async () =>
-          routeTransformRunner({
+        async () => {
+          const routeChunkName = getRouteChunkNameFromModuleId(args.resource);
+          if (isBuild && isSpaMode && routeChunkName === 'main') {
+            validateSpaModeRouteExports({
+              exportNames: analyzeRouteModuleCode(args.code, args.resourcePath)
+                .exports,
+              resourcePath: args.resourcePath,
+              rootRoutePath,
+            });
+          }
+
+          const routeChunkArtifact = await routeTransformRunner({
             kind: 'routeChunk',
             code: args.code,
             resource: args.resource,
             resourcePath: args.resourcePath,
             isBuild,
             routeChunkConfig,
-          })
-      )
+          });
+
+          // Invariant with the transformRouteModule registration below: in
+          // split-chunk production builds, web route modules are transformed
+          // HERE (on the main chunk) and the shared registration is scoped to
+          // ['node']. If either gate changes, web modules get transformed
+          // twice or not at all.
+          if (!isBuild || routeChunkName !== 'main') {
+            return routeChunkArtifact;
+          }
+
+          return routeTransformRunner({
+            kind: 'routeModule',
+            code: routeChunkArtifact.code,
+            resource: args.resource,
+            resourcePath: args.resourcePath,
+            environmentName: 'web',
+            sourceMaps: isSourceMapEnabled(
+              args.environment.config.output.sourceMap
+            ),
+            ssr,
+            isBuild,
+            isSpaMode,
+            rootRoutePath,
+          });
+        }
+      );
+    }
   );
 
   if (isBuild && splitRouteModules) {
@@ -199,9 +326,10 @@ export const registerBuildOutputTransforms = ({
           not: /__react-router-build-client-route|react-router-route|route-chunk=/,
         },
         environments: ['web'],
+        order: 'post',
       },
-      async args =>
-        performanceProfiler.record(
+      async args => {
+        return performanceProfiler.record(
           args.environment?.name,
           'route:split-exports',
           args.resource,
@@ -212,7 +340,8 @@ export const registerBuildOutputTransforms = ({
               resourcePath: args.resourcePath,
               routeChunkConfig,
             })
-        )
+        );
+      }
     );
   }
 
@@ -274,6 +403,11 @@ export const registerBuildOutputTransforms = ({
         resourceQuery: {
           not: /__react-router-build-client-route|react-router-route|route-chunk=/,
         },
+        // Invariant with the route-chunk= handler above: when split-chunk
+        // production builds transform web modules on the main chunk, this
+        // registration must stay scoped to ['node'] so web modules are not
+        // transformed twice.
+        environments: isBuild && splitRouteModules ? ['node'] : undefined,
         order: 'post',
       },
       transformRouteModule

package/src/classic-mode.ts

@@ -0,0 +1,253 @@
+import { readFileSync } from 'node:fs';
+import type { RsbuildEntryDescription, RsbuildPluginAPI } from '@rsbuild/core';
+import type { RouteConfigEntry } from '@react-router/dev/routes';
+import { resolve } from 'pathe';
+import {
+  getBuildManifest,
+  getRoutesByServerBundleId,
+} from './build-manifest.js';
+import { BUILD_CLIENT_ROUTE_QUERY_STRING } from './constants.js';
+import {
+  DEV_HMR_RUNTIME_MODULE_ID,
+  type DevHmrPlanOptions,
+} from './dev-hmr.js';
+import {
+  createReactRouterDevRuntimeController,
+  type ReactRouterDevRuntimeController,
+} from './dev-runtime-controller.js';
+import { generateWithProps } from './plugin-utils.js';
+import { resolvePrerenderPaths } from './prerender.js';
+import { generateServerBuild } from './server-utils.js';
+import {
+  createReactRouterServerBuildPlan,
+  type ReactRouterServerBundleEntry,
+} from './server-build-plan.js';
+import {
+  getRouteChunkEntryName,
+  getRouteChunkModuleId,
+  routeChunkExportNames,
+} from './route-chunks.js';
+import type { Config } from './react-router-config.js';
+import type { Route } from './types.js';
+
+type CreateClassicWebRouteEntriesOptions = {
+  appDirectory: string;
+  isBuild: boolean;
+  routes: Record<string, Route>;
+  splitRouteModules: boolean;
+};
+
+type CreateClassicVirtualModulesOptions = {
+  allowedActionOrigins: string[] | undefined;
+  appDirectory: string;
+  assetsBuildDirectory: string;
+  basename: string;
+  devHmrRuntimeModule?: string;
+  entryServerPath: string;
+  future: Config['future'];
+  isSpaMode: boolean;
+  prerenderPaths: string[];
+  publicPath: string;
+  routeDiscovery: Config['routeDiscovery'];
+  routes: Record<string, Route>;
+  routesByServerBundleId: Record<string, Record<string, Route>>;
+  ssr: boolean;
+};
+
+type CreateClassicBuildArtifactsOptions = {
+  api: RsbuildPluginAPI;
+  defaultEntryName: string;
+  isBuild: boolean;
+  prerenderConfig: Config['prerender'];
+  reactRouterConfig: Required<
+    Pick<
+      Config,
+      'appDirectory' | 'buildDirectory' | 'serverBuildFile' | 'future'
+    >
+  > &
+    Pick<Config, 'serverBundles'>;
+  routeConfig: RouteConfigEntry[];
+  routes: Record<string, Route>;
+  rootDirectory: string;
+  ssr: boolean;
+  devHmr?: DevHmrPlanOptions;
+};
+
+export type ClassicBuildArtifacts = {
+  buildManifest: Awaited<ReturnType<typeof getBuildManifest>>;
+  devRuntime: ReactRouterDevRuntimeController;
+  prerenderPaths: string[];
+  routesByServerBundleId: Record<string, Record<string, Route>>;
+  serverBundleEntries: ReactRouterServerBundleEntry[];
+};
+
+export const createClassicBuildArtifacts = async ({
+  api,
+  defaultEntryName,
+  isBuild,
+  prerenderConfig,
+  reactRouterConfig,
+  routeConfig,
+  routes,
+  rootDirectory,
+  ssr,
+  devHmr,
+}: CreateClassicBuildArtifactsOptions): Promise<ClassicBuildArtifacts> => {
+  const buildManifest = await getBuildManifest({
+    reactRouterConfig,
+    routes,
+    rootDirectory,
+  });
+  const routesByServerBundleId = getRoutesByServerBundleId(
+    buildManifest,
+    routes
+  );
+  const serverBuildPlan = createReactRouterServerBuildPlan({
+    routesByServerBundleId,
+    serverBuildFile: reactRouterConfig.serverBuildFile,
+    defaultEntryName,
+  });
+  const prerenderPaths = await resolvePrerenderPaths(
+    prerenderConfig,
+    ssr,
+    routeConfig,
+    {
+      logWarning: true,
+      warn: message => api.logger.warn(message),
+    }
+  );
+
+  return {
+    buildManifest,
+    devRuntime: createReactRouterDevRuntimeController({
+      api,
+      isBuild,
+      buildPlan: serverBuildPlan,
+      clientPatchesRouteMetadata: devHmr?.isEnabled,
+      onNodeRebuildCommitted: devHmr?.onNodeRebuildCommitted,
+    }),
+    prerenderPaths,
+    routesByServerBundleId,
+    serverBundleEntries: serverBuildPlan.serverBundleEntries,
+  };
+};
+
+export const createClassicWebRouteEntries = ({
+  appDirectory,
+  isBuild,
+  routes,
+  splitRouteModules,
+}: CreateClassicWebRouteEntriesOptions): {
+  manifestChunkNames: Set<string>;
+  webRouteEntries: Record<string, RsbuildEntryDescription>;
+} => {
+  const manifestChunkNames = new Set<string>(['entry.client']);
+  const webRouteEntries = Object.values(routes).reduce(
+    (acc, route) => {
+      const entryName = route.file.slice(0, route.file.lastIndexOf('.'));
+      const routeFilePath = resolve(appDirectory, route.file);
+      manifestChunkNames.add(entryName);
+      acc[entryName] = {
+        import: `${routeFilePath}${BUILD_CLIENT_ROUTE_QUERY_STRING}`,
+        html: false,
+      };
+
+      if (isBuild && splitRouteModules && route.id !== 'root') {
+        let source: string;
+        try {
+          source = readFileSync(routeFilePath, 'utf8');
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return acc;
+          }
+          throw error;
+        }
+        for (const exportName of routeChunkExportNames) {
+          if (!source.includes(exportName)) {
+            continue;
+          }
+          const chunkEntryName = getRouteChunkEntryName(route.id, exportName);
+          manifestChunkNames.add(chunkEntryName);
+          acc[chunkEntryName] = {
+            import: getRouteChunkModuleId(routeFilePath, exportName),
+            html: false,
+          };
+        }
+      }
+
+      return acc;
+    },
+    {} as Record<string, RsbuildEntryDescription>
+  );
+
+  return {
+    manifestChunkNames,
+    webRouteEntries,
+  };
+};
+
+export const createClassicVirtualModules = ({
+  allowedActionOrigins,
+  appDirectory,
+  assetsBuildDirectory,
+  basename,
+  devHmrRuntimeModule,
+  entryServerPath,
+  future,
+  isSpaMode,
+  prerenderPaths,
+  publicPath,
+  routeDiscovery,
+  routes,
+  routesByServerBundleId,
+  ssr,
+}: CreateClassicVirtualModulesOptions): Record<string, string> => {
+  const serverBuildOptions = {
+    entryServerPath,
+    assetsBuildDirectory,
+    basename,
+    appDirectory,
+    ssr,
+    isSpaMode,
+    future,
+    allowedActionOrigins,
+    prerender: prerenderPaths,
+    routeDiscovery,
+    publicPath,
+  };
+  const bundleVirtualModules = Object.fromEntries(
+    Object.entries(routesByServerBundleId).map(([bundleId, bundleRoutes]) => [
+      `virtual/react-router/server-build-${bundleId}`,
+      generateServerBuild(bundleRoutes, {
+        ...serverBuildOptions,
+        serverManifestId: `virtual/react-router/server-manifest-${bundleId}`,
+      }),
+    ])
+  );
+  const bundleManifestModules = Object.fromEntries(
+    Object.entries(routesByServerBundleId)
+      .filter(
+        ([, bundleRoutes]) =>
+          bundleRoutes && Object.keys(bundleRoutes).length > 0
+      )
+      .map(([bundleId]) => [
+        `virtual/react-router/server-manifest-${bundleId}`,
+        'export default {};',
+      ])
+  );
+
+  return {
+    'virtual/react-router/browser-manifest': 'export default {};',
+    'virtual/react-router/server-manifest': 'export default {};',
+    'virtual/react-router/server-build': generateServerBuild(
+      routes,
+      serverBuildOptions
+    ),
+    ...bundleVirtualModules,
+    ...bundleManifestModules,
+    'virtual/react-router/with-props': generateWithProps(),
+    ...(devHmrRuntimeModule !== undefined
+      ? { [DEV_HMR_RUNTIME_MODULE_ID]: devHmrRuntimeModule }
+      : {}),
+  };
+};