rsbuild-plugin-react-router 0.5.0 → 0.6.0

package/src/ssr-asset-relocation.ts

@@ -0,0 +1,183 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'pathe';
+
+/**
+ * Relocation of server-only static assets to the client build.
+ *
+ * In React Router framework mode a route's server-only code (a loader or a
+ * `.server` module) can import an asset — for example
+ * `import txtUrl from "./file.txt?url"` or a `.css?url` file. The imported URL
+ * is returned to the client (e.g. as loader data) and fetched from the client
+ * build directory at runtime, so the asset file must exist under
+ * `build/client` even though only the node/server compilation referenced it.
+ *
+ * Rspack emits these assets into the server output (`build/server/static/...`)
+ * and never into the client output. This module mirrors upstream React
+ * Router's Vite plugin, which internally enables `ssrEmitAssets` and then, in
+ * the SSR `writeBundle` hook, moves server-emitted static assets into the
+ * client assets directory and strips them from the server build
+ * (`react-router-dev/vite/plugin.ts`). Here the equivalent runs inside the
+ * node compilation's `processAssets` hook: static assets are written into the
+ * client output at the same public path and deleted from the server
+ * compilation so the server build never ships duplicate static files.
+ */
+
+/**
+ * The subset of an Rspack asset info that identifies static assets emitted by
+ * asset modules (`asset/resource`) and the CSS pipeline.
+ */
+export interface RelocatableAssetInfo {
+  /**
+   * Set by Rspack for assets produced from a source module (asset modules and
+   * extracted CSS). JavaScript chunks and generated files such as
+   * `package.json` do not carry a `sourceFilename`.
+   */
+  sourceFilename?: string;
+  /**
+   * Set for JavaScript chunk assets. Static assets never set this, so it is
+   * used to keep code-split JS in the server build.
+   */
+  javascriptModule?: boolean;
+}
+
+/**
+ * The minimal compilation surface needed to collect and relocate assets. Kept
+ * narrow so the logic can be unit-tested without a real Rspack compilation.
+ */
+export interface RelocatableAssetCompilation {
+  assets: Record<string, unknown>;
+  getAsset(name: string):
+    | {
+        name: string;
+        source: { buffer(): Buffer };
+        info: RelocatableAssetInfo;
+      }
+    | undefined
+    | void;
+  deleteAsset(name: string): void;
+}
+
+export interface CollectedServerAsset {
+  /** The public path of the asset, relative to the compilation output root. */
+  name: string;
+  source: { buffer(): Buffer };
+}
+
+/**
+ * Determine whether an emitted asset is a static asset that must live in the
+ * client build. Static assets (asset modules and CSS) carry a `sourceFilename`
+ * and are not JavaScript chunks. Code-split JavaScript is intentionally
+ * excluded so it remains in the server build.
+ */
+export const isRelocatableServerAsset = (
+  info: RelocatableAssetInfo | undefined
+): boolean => Boolean(info?.sourceFilename) && !info?.javascriptModule;
+
+/**
+ * Collect the server-only static assets from a node compilation. Returns them
+ * in stable (sorted) order so callers and tests see deterministic output.
+ */
+export const collectRelocatableServerAssets = (
+  compilation: RelocatableAssetCompilation
+): CollectedServerAsset[] => {
+  const collected: CollectedServerAsset[] = [];
+  for (const name of Object.keys(compilation.assets)) {
+    const asset = compilation.getAsset(name);
+    if (!asset) {
+      continue;
+    }
+    if (!isRelocatableServerAsset(asset.info)) {
+      continue;
+    }
+    collected.push({ name, source: asset.source });
+  }
+  collected.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return collected;
+};
+
+export interface RelocateServerAssetsResult {
+  /** Assets written into the client output because they were missing or stale. */
+  written: string[];
+  /**
+   * Assets that already existed in the client output. They are still removed
+   * from the server build but not rewritten.
+   */
+  skipped: string[];
+}
+
+/**
+ * Move server-only static assets into the client output and strip them from
+ * the server compilation.
+ *
+ * For each static asset: if it is missing or stale in the client output at the
+ * same public path, write it there; then delete it from the server compilation
+ * regardless. This mirrors upstream's move/remove behavior — the server build
+ * never ships static assets, and the client build gains fresh server-only
+ * assets.
+ */
+const digestBuffer = (buffer: Buffer): string =>
+  createHash('sha256').update(buffer).digest('hex');
+
+export const relocateServerAssetsToClient = async ({
+  compilation,
+  outputClientPath,
+  relocatedDestinations,
+  existsSyncFn = existsSync,
+  mkdirFn = (dir: string) => mkdir(dir, { recursive: true }),
+  readFileFn = readFile,
+  renameFn = rename,
+  rmFn = rm,
+  writeFileFn = writeFile,
+}: {
+  compilation: RelocatableAssetCompilation;
+  outputClientPath: string;
+  /**
+   * Destination content digests already handled by a previous compilation
+   * (dev rebuilds, serverBundles). Stable dev filenames can carry changed
+   * bytes, so the cache is keyed by path and digest rather than path alone.
+   */
+  relocatedDestinations?: Map<string, string>;
+  existsSyncFn?: (path: string) => boolean;
+  mkdirFn?: (dir: string) => Promise<unknown>;
+  readFileFn?: (path: string) => Promise<Buffer>;
+  renameFn?: (oldPath: string, newPath: string) => Promise<void>;
+  rmFn?: (path: string, options: { force: true }) => Promise<void>;
+  writeFileFn?: (path: string, data: Buffer) => Promise<void>;
+}): Promise<RelocateServerAssetsResult> => {
+  const assets = collectRelocatableServerAssets(compilation);
+  const written: string[] = [];
+  const skipped: string[] = [];
+
+  for (const asset of assets) {
+    const destination = join(outputClientPath, asset.name);
+    const sourceBuffer = asset.source.buffer();
+    const sourceDigest = digestBuffer(sourceBuffer);
+    const cachedDigest = relocatedDestinations?.get(destination);
+    const alreadyRelocated =
+      cachedDigest === sourceDigest ||
+      (existsSyncFn(destination) &&
+        digestBuffer(await readFileFn(destination)) === sourceDigest);
+    if (alreadyRelocated) {
+      skipped.push(asset.name);
+    } else {
+      await mkdirFn(dirname(destination));
+      const temporaryDestination = `${destination}.tmp-${process.pid}-${Date.now()}`;
+      await writeFileFn(temporaryDestination, sourceBuffer);
+      try {
+        await renameFn(temporaryDestination, destination);
+      } catch (error) {
+        await rmFn(temporaryDestination, { force: true });
+        throw error;
+      }
+      written.push(asset.name);
+    }
+    relocatedDestinations?.set(destination, sourceDigest);
+    // Remove the static asset from the server build so it is not shipped
+    // twice. Code-split JavaScript is not collected, so it stays.
+    compilation.deleteAsset(asset.name);
+  }
+
+  return { written, skipped };
+};

package/src/ssr-externals.ts

@@ -28,32 +28,14 @@ export function resolvePackageJson(
   }
 }
 
-function safeRealpath(pathname: string): string {
-  try {
-    return realpathSync(pathname);
-  } catch {
-    return pathname;
-  }
-}
-
-function isPathInNodeModules(pathname: string): boolean {
-  return pathname.split(sep).includes('node_modules');
-}
-
 export function getSsrExternals(rootDirectory: string): string[] {
-  const externals: string[] = [];
-
-  for (const name of REACT_ROUTER_EXTERNALS) {
+  return REACT_ROUTER_EXTERNALS.filter(name => {
     const resolved = resolvePackageJson(name, rootDirectory);
-    if (!resolved) {
-      continue;
-    }
-
-    const realPath = safeRealpath(resolved);
-    if (!isPathInNodeModules(realPath)) {
-      externals.push(name);
-    }
-  }
-
-  return externals;
+    if (resolved === null) return false;
+    let packageJsonPath = resolved;
+    try {
+      packageJsonPath = realpathSync(packageJsonPath);
+    } catch {}
+    return !packageJsonPath.split(sep).includes('node_modules');
+  });
 }

package/src/templates/entry.rsc.client.tsx

@@ -0,0 +1,168 @@
+import 'virtual/react-router/unstable_rsc/inject-hmr-runtime';
+
+import * as React from 'react';
+import { startTransition } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import type { DataRouter } from 'react-router';
+import {
+  unstable_createCallServer as createCallServer,
+  unstable_getRSCStream as getRSCStream,
+  unstable_RSCHydratedRouter as RSCHydratedRouter,
+  type unstable_RSCPayload as RSCPayload,
+} from 'react-router/dom';
+import {
+  createFromReadableStream,
+  createTemporaryReferenceSet,
+  encodeReply,
+  setServerCallback,
+} from 'react-server-dom-rspack/client.browser';
+
+type RscHydrationWindow = Window & {
+  __reactRouterDataRouter?: DataRouter;
+  __reactRouterHdrActive?: boolean;
+};
+
+const hydrationWindow = window as RscHydrationWindow;
+
+const InitialRscDataLoadGuard = ({
+  active,
+  children,
+}: {
+  active: boolean;
+  children?: React.ReactNode;
+}): React.ReactNode => {
+  React.useEffect(() => {
+    if (!active) {
+      return;
+    }
+
+    let frame: number;
+    const clearGuardOnceDataLoadStarts = () => {
+      const router = hydrationWindow.__reactRouterDataRouter;
+      if (
+        router &&
+        (router.state.initialized || router.state.navigation.state !== 'idle')
+      ) {
+        hydrationWindow.__reactRouterHdrActive = false;
+        return;
+      }
+      frame = requestAnimationFrame(clearGuardOnceDataLoadStarts);
+    };
+    frame = requestAnimationFrame(clearGuardOnceDataLoadStarts);
+    return () => cancelAnimationFrame(frame);
+  }, [active]);
+  return children;
+};
+
+setServerCallback(
+  createCallServer({
+    createFromReadableStream,
+    createTemporaryReferenceSet,
+    encodeReply,
+  })
+);
+
+const hydrate = () => {
+  createFromReadableStream<RSCPayload>(getRSCStream()).then(
+    payload => {
+      startTransition(async () => {
+        const formState =
+          payload.type === 'render' ? await payload.formState : undefined;
+        const needsInitialDataLoadGuard =
+          payload.type === 'render' &&
+          payload.matches.some(
+            match =>
+              match.clientLoader != null &&
+              !match.hasLoader &&
+              match.hydrateFallbackElement != null
+          );
+
+        // React Router's RSC single-fetch hydration skips its request while the
+        // router is both idle and uninitialized. An implicitly hydrating
+        // clientLoader with a fallback and no server loader can race the layout
+        // effect that starts initialization, leaving it with an empty result
+        // for parent routes. Its HDR guard already means “the initial data
+        // request is required”; keep that guard active until router
+        // initialization starts, then clear it in the effect above.
+        if (needsInitialDataLoadGuard) {
+          hydrationWindow.__reactRouterHdrActive = true;
+        }
+        hydrateRoot(
+          document,
+          React.createElement(
+            React.StrictMode,
+            null,
+            React.createElement(
+              InitialRscDataLoadGuard,
+              { active: needsInitialDataLoadGuard },
+              React.createElement(RSCHydratedRouter, {
+                createFromReadableStream,
+                payload,
+              })
+            )
+          ),
+          {
+            // @ts-expect-error React Router RSC formState is not typed yet.
+            formState,
+          }
+        );
+      });
+    },
+    error => {
+      setTimeout(() => {
+        throw error;
+      });
+    }
+  );
+};
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', hydrate, { once: true });
+} else {
+  hydrate();
+}
+
+// The RSC plugin emits an unqualified update for server-component changes; in
+// that case navigate to refresh the route tree. The framework integration emits
+// `{ revalidate: true }` for server-only data dependency changes, which can
+// refresh loader data without remounting client or browser state.
+//
+// The RSC plugin's message has no payload; there is no `reload` flag (full
+// reloads travel through the HMR runtime's own `full-reload` message).
+const hot = (
+  import.meta as unknown as {
+    webpackHot?: {
+      on(
+        event: string,
+        handler: (data?: { revalidate?: boolean }) => void
+      ): void;
+    };
+  }
+).webpackHot;
+
+hot?.on('rsc:update', data => {
+  requestAnimationFrame(() => {
+    const router = (
+      window as typeof window & { __reactRouterDataRouter?: DataRouter }
+    ).__reactRouterDataRouter;
+    if (data?.revalidate) {
+      router?.revalidate();
+      return;
+    }
+    if (router?.navigate) {
+      const basename = router.basename || '/';
+      let pathname = window.location.pathname;
+      if (basename !== '/' && pathname.startsWith(basename)) {
+        pathname = pathname.slice(basename.length) || '/';
+        if (pathname[0] !== '/') pathname = '/' + pathname;
+      }
+      void router.navigate(
+        pathname + window.location.search + window.location.hash,
+        {
+          replace: true,
+          preventScrollReset: true,
+        }
+      );
+    }
+  });
+});

package/src/templates/entry.rsc.ssr.tsx

@@ -0,0 +1,45 @@
+import * as React from 'react';
+import { renderToReadableStream as renderHTMLToReadableStream } from 'react-dom/server';
+import {
+  unstable_routeRSCServerRequest as routeRSCServerRequest,
+  unstable_RSCStaticRouter as RSCStaticRouter,
+} from 'react-router';
+import type { unstable_RSCPayload as RSCPayload } from 'react-router/dom';
+import { createFromReadableStream } from 'react-server-dom-rspack/client.node';
+
+type PayloadPromise = Promise<RSCPayload> & {
+  _deepestRenderedBoundaryId?: string | null;
+  formState?: Promise<unknown>;
+};
+
+export async function generateHTML(
+  request: Request,
+  serverResponse: Response,
+  options: {
+    bootstrapScripts?: string[];
+    bootstrapModules?: string[];
+  } = {}
+): Promise<Response> {
+  return routeRSCServerRequest({
+    request,
+    serverResponse,
+    createFromReadableStream,
+    async renderHTML(getPayload, renderOptions) {
+      const payloadPromise = getPayload() as PayloadPromise;
+      payloadPromise.formState ??= payloadPromise.then(payload =>
+        payload.type === 'render' ? payload.formState : undefined
+      );
+
+      return renderHTMLToReadableStream(
+        <RSCStaticRouter getPayload={getPayload} />,
+        {
+          ...renderOptions,
+          bootstrapModules: options.bootstrapModules,
+          bootstrapScripts: options.bootstrapScripts,
+          formState: (await payloadPromise.formState) as never,
+          signal: request.signal,
+        }
+      );
+    },
+  });
+}

package/src/templates/entry.rsc.tsx

@@ -0,0 +1,80 @@
+import {
+  createTemporaryReferenceSet,
+  decodeAction,
+  decodeFormState,
+  decodeReply,
+  loadServerAction as loadServerActionSync,
+  renderToReadableStream,
+} from 'react-server-dom-rspack/server.node';
+import {
+  RouterContextProvider,
+  unstable_matchRSCServerRequest as matchRSCServerRequest,
+} from 'react-router';
+
+import routes from 'virtual/react-router/unstable_rsc/routes';
+import routeDiscovery from 'virtual/react-router/unstable_rsc/route-discovery';
+import basename from 'virtual/react-router/unstable_rsc/basename';
+import allowedActionOrigins from 'virtual/react-router/unstable_rsc/allowed-action-origins';
+import clientVersion from 'virtual/react-router/unstable_rsc/client-version';
+import unstable_reactRouterServeConfig from 'virtual/react-router/unstable_rsc/react-router-serve-config';
+import bootstrapScripts from 'virtual/react-router/unstable_rsc/bootstrap-scripts';
+import getServerManifest from 'virtual/react-router/unstable_rsc/server-manifest';
+import { generateHTML } from './entry.rsc.ssr.js';
+
+export { unstable_reactRouterServeConfig };
+
+type RscRequestHandler = {
+  fetch(
+    request: Request,
+    requestContext?: RouterContextProvider
+  ): Promise<Response>;
+};
+
+export function fetchServer(
+  request: Request,
+  requestContext?: RouterContextProvider
+): Promise<Response> {
+  return matchRSCServerRequest({
+    allowedActionOrigins,
+    basename,
+    // @ts-expect-error Supported React Router 7.x types predate the 8.3 RSC
+    // client-version option; those runtimes safely ignore the extra field.
+    clientVersion,
+    createTemporaryReferenceSet,
+    decodeAction: body => decodeAction(body, getServerManifest()),
+    decodeFormState: async (actionResult, body) =>
+      (await decodeFormState(actionResult, body, getServerManifest())) ??
+      undefined,
+    decodeReply,
+    loadServerAction: (id: string) => Promise.resolve(loadServerActionSync(id)),
+    request,
+    requestContext,
+    routes,
+    routeDiscovery,
+    generateResponse(match, options) {
+      return new Response(renderToReadableStream(match.payload, options), {
+        status: match.statusCode,
+        headers: match.headers,
+      });
+    },
+  });
+}
+
+const handler: RscRequestHandler = {
+  async fetch(
+    request: Request,
+    requestContext?: RouterContextProvider
+  ): Promise<Response> {
+    if (requestContext && !(requestContext instanceof RouterContextProvider)) {
+      requestContext = undefined;
+    }
+
+    return generateHTML(request, await fetchServer(request, requestContext), {
+      bootstrapScripts,
+    });
+  },
+};
+
+export default handler;
+
+import.meta.webpackHot?.accept();

package/src/typegen.ts

@@ -3,7 +3,11 @@ import { dirname, resolve } from 'node:path';
 import type { RsbuildPluginAPI } from '@rsbuild/core';
 import type { ResultPromise } from 'execa';
 import * as Effect from 'effect/Effect';
-import { createDelayedPluginTask, tryPluginPromise } from './effect-runtime.js';
+import {
+  createDelayedPluginTask,
+  type PluginEffectRuntime,
+  tryPluginPromise,
+} from './effect-runtime.js';
 import { resolvePackageJson } from './ssr-externals.js';
 
 // Quiet period with no dev compiles before the typegen watch starts. Long
@@ -69,6 +73,7 @@ export const createReactRouterTypegenRunner = (
 ): ReactRouterTypegenRunner => {
   let typegenProcess: ResultPromise | undefined;
   let typegenCommand: TypegenCommand | undefined;
+  let watchGeneration = 0;
 
   const getTypegenCommand = (): TypegenCommand => {
     typegenCommand ??= (appDirectory
@@ -96,7 +101,11 @@ export const createReactRouterTypegenRunner = (
         return;
       }
 
+      const generation = watchGeneration;
       const execa = await loadExeca();
+      if (typegenProcess || generation !== watchGeneration) {
+        return;
+      }
       const { command, args } = getTypegenCommand();
       const process = execa(command, [...args, 'typegen', '--watch'], {
         stdio: 'inherit',
@@ -108,6 +117,7 @@ export const createReactRouterTypegenRunner = (
     },
 
     async closeWatch(): Promise<void> {
+      watchGeneration += 1;
       const process = typegenProcess;
       typegenProcess = undefined;
       if (!process) {
@@ -128,36 +138,48 @@ export const createReactRouterTypegenRunner = (
   };
 };
 
-export const registerReactRouterTypegen = (
+export const registerReactRouterTypegen = async (
   api: RsbuildPluginAPI,
   {
+    runtime,
     runner,
     devWatchDelayMs = TYPEGEN_IDLE_DELAY_MS,
     appDirectory,
   }: {
+    runtime: PluginEffectRuntime;
     runner?: ReactRouterTypegenRunner;
     devWatchDelayMs?: number;
     appDirectory?: string;
-  } = {}
-): void => {
+  }
+): Promise<void> => {
   const resolvedRunner =
     runner ?? createReactRouterTypegenRunner(loadDefaultExeca, appDirectory);
-  let devWatchStarted = false;
-  const devWatchTask = createDelayedPluginTask({
-    delayMs: devWatchDelayMs,
-    run: () =>
-      tryPluginPromise(() => {
-        devWatchStarted = true;
-        return resolvedRunner.startWatch();
-      }).pipe(Effect.asVoid),
-    onError(error) {
-      api.logger.warn(
-        `[react-router] Failed to start React Router typegen watch: ${error}`
-      );
-    },
-  });
 
   if (api.context.action !== 'build') {
+    let devWatchStarted = false;
+    const devWatchTask = createDelayedPluginTask({
+      runtime,
+      delayMs: devWatchDelayMs,
+      run: () =>
+        tryPluginPromise(() => {
+          devWatchStarted = true;
+          return resolvedRunner.startWatch();
+        }).pipe(Effect.asVoid),
+      onError(error) {
+        api.logger.warn(
+          `[react-router] Failed to start React Router typegen watch: ${error}`
+        );
+      },
+    });
+    const closeWatchEffect = () =>
+      devWatchTask
+        .cancelEffect()
+        .pipe(
+          Effect.zipRight(
+            Effect.orDie(tryPluginPromise(() => resolvedRunner.closeWatch()))
+          )
+        );
+    await runtime.runPromise(Effect.addFinalizer(closeWatchEffect));
     // Reschedule on every compile so the typegen watch only starts after a
     // quiet period with no compiles. Starting it during the initial compile
     // burst competes with HMR rebuilds for CPU on small machines.
@@ -169,10 +191,5 @@ export const registerReactRouterTypegen = (
     });
   }
 
-  api.onCloseDevServer(async () => {
-    await devWatchTask.cancel();
-    await resolvedRunner.closeWatch();
-  });
-
   api.onBeforeBuild(() => resolvedRunner.runBuild());
 };

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { RsbuildConfig } from '@rsbuild/core';
+import type { RsbuildConfig, Rspack } from '@rsbuild/core';
 
 export type Route = {
   id: string;
@@ -30,6 +30,23 @@ export type PluginOptions = {
    */
   federation?: boolean;
 
+  /**
+   * Enable experimental React Router RSC framework mode.
+   * This composes `rsbuild-plugin-rsc` with React Router's Rsbuild
+   * environments. Environment names are managed by this plugin.
+   * Requires `react-router >=7.18.0 || >=8.0.0`, `rsbuild-plugin-rsc`,
+   * and `react-server-dom-rspack`.
+   * @default false
+   */
+  rsc?:
+    | boolean
+    | {
+        layers?: {
+          rsc?: Rspack.RuleSetCondition;
+          ssr?: Rspack.RuleSetCondition;
+        };
+      };
+
   /**
    * Rsbuild dev-only lazy compilation behavior.
    *
@@ -73,6 +90,27 @@ export type PluginOptions = {
   onRouteTopologyChange?: () => void | Promise<void>;
 };
 
+export type ReactRouterRSCPluginOptions = Omit<PluginOptions, 'rsc'> & {
+  /**
+   * Optional overrides forwarded to `rsbuild-plugin-rsc`.
+   * Environment names are managed by this plugin.
+   */
+  rsc?: Exclude<NonNullable<PluginOptions['rsc']>, boolean>;
+};
+
+export type PrerenderPathsConfig =
+  | boolean
+  | string[]
+  | ((args: {
+      getStaticPaths: () => string[];
+    }) => boolean | string[] | Promise<boolean | string[]>);
+
+export type PrerenderConfigObject = {
+  paths: PrerenderPathsConfig;
+  concurrency?: number;
+  unstable_concurrency?: number;
+};
+
 export type RouteManifestItem = Omit<Route, 'file' | 'children'> & {
   module: string;
   clientActionModule?: string;