rsbuild-plugin-react-router 0.5.0 → 0.6.1

package/src/route-transform-tasks.ts

@@ -310,6 +310,41 @@ const buildComponentRefreshRegistrations = (names: string[]): string => {
   return `\nif (typeof $RefreshReg$ === 'function') {\n${registrations}\n}\n`;
 };
 
+export const validateSpaModeRouteExports = ({
+  exportNames,
+  resourcePath,
+  rootRoutePath,
+}: {
+  exportNames: readonly string[];
+  resourcePath: string;
+  rootRoutePath: string | null;
+}): void => {
+  const isRootRoute = resourcePath === rootRoutePath;
+  const relativePath = relative(process.cwd(), resourcePath);
+  const invalidServerOnly = exportNames.filter(exp => {
+    if (isRootRoute && exp === 'loader') return false;
+    return SERVER_ONLY_ROUTE_EXPORTS_SET.has(exp);
+  });
+
+  if (invalidServerOnly.length > 0) {
+    const list = invalidServerOnly.map(exp => `\`${exp}\``).join(', ');
+    throw new Error(
+      `SPA Mode: ${invalidServerOnly.length} invalid route export(s) in ` +
+        `\`${relativePath}\`: ${list}. ` +
+        `See https://reactrouter.com/how-to/spa for more information.`
+    );
+  }
+
+  if (!isRootRoute && exportNames.includes('HydrateFallback')) {
+    throw new Error(
+      `SPA Mode: Invalid \`HydrateFallback\` export found in ` +
+        `\`${relativePath}\`. ` +
+        `\`HydrateFallback\` is only permitted on the root route in SPA Mode. ` +
+        `See https://reactrouter.com/how-to/spa for more information.`
+    );
+  }
+};
+
 const transformRouteModule = async (
   task: RouteModuleTransformTask
 ): Promise<RouteTransformResult> => {
@@ -325,32 +360,11 @@ const transformRouteModule = async (
 
   const ast = parse(code, { sourceType: 'module' });
   if (task.environmentName === 'web' && !task.ssr && task.isSpaMode) {
-    const resolvedExportNames = collectProgramExportNames(getProgram(ast));
-    const isRootRoute = task.resourcePath === task.rootRoutePath;
-    const relativePath = relative(process.cwd(), task.resourcePath);
-
-    const invalidServerOnly = resolvedExportNames.filter(exp => {
-      if (isRootRoute && exp === 'loader') return false;
-      return SERVER_ONLY_ROUTE_EXPORTS_SET.has(exp);
+    validateSpaModeRouteExports({
+      exportNames: collectProgramExportNames(getProgram(ast)),
+      resourcePath: task.resourcePath,
+      rootRoutePath: task.rootRoutePath,
     });
-
-    if (invalidServerOnly.length > 0) {
-      const list = invalidServerOnly.map(e => `\`${e}\``).join(', ');
-      throw new Error(
-        `SPA Mode: ${invalidServerOnly.length} invalid route export(s) in ` +
-          `\`${relativePath}\`: ${list}. ` +
-          `See https://reactrouter.com/how-to/spa for more information.`
-      );
-    }
-
-    if (!isRootRoute && resolvedExportNames.includes('HydrateFallback')) {
-      throw new Error(
-        `SPA Mode: Invalid \`HydrateFallback\` export found in ` +
-          `\`${relativePath}\`. ` +
-          `\`HydrateFallback\` is only permitted on the root route in SPA Mode. ` +
-          `See https://reactrouter.com/how-to/spa for more information.`
-      );
-    }
   }
 
   const removedServerOnlyExports =

package/src/route-watch.ts

@@ -2,11 +2,12 @@ import { watch, type FSWatcher } from 'node:fs';
 import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
 import type { RsbuildConfig } from '@rsbuild/core';
 import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
 import { dirname, resolve } from 'pathe';
 import { getCappedPluginConcurrency } from './concurrency.js';
 import {
   createDelayedPluginTask,
-  runPluginEffect,
+  type PluginEffectRuntime,
   tryPluginPromise,
 } from './effect-runtime.js';
 import type { Route } from './types.js';
@@ -47,6 +48,17 @@ type WatchDirectoryEntry = (
   onError: (error: unknown) => void
 ) => DirectoryWatcher;
 
+export type CreateRouteTopologyWatcherOptions = {
+  runtime: PluginEffectRuntime;
+  watchDirectory: string;
+  getRouteTopology: () => Promise<Set<string>>;
+  initialRouteTopology?: Set<string>;
+  restartMarkerPath: string;
+  onError: (error: unknown) => void;
+  onRouteTopologyChange?: () => void | Promise<void>;
+  watchDirectoryEntry?: WatchDirectoryEntry;
+};
+
 const defaultWatchDirectoryEntry: WatchDirectoryEntry = (
   directory,
   onChange,
@@ -70,8 +82,8 @@ export const mergeWatchFiles = (
   ] as WatchFilesConfig;
 };
 
-export const getRouteRestartMarkerPath = (outputClientPath: string): string =>
-  resolve(outputClientPath, ROUTE_RESTART_MARKER_ASSET);
+export const getRouteRestartMarkerPath = (appDirectory: string): string =>
+  resolve(appDirectory, '..', ROUTE_RESTART_MARKER_ASSET);
 
 export const createRouteManifestSnapshot = (
   routes: RouteManifestSnapshotEntries
@@ -120,10 +132,6 @@ const areSetsEqual = <T>(left: Set<T>, right: Set<T>): boolean => {
   return true;
 };
 
-const readRouteDirectories = (watchDirectory: string): Promise<Set<string>> => {
-  return runPluginEffect(readRouteDirectoriesEffect(watchDirectory));
-};
-
 const readRouteDirectoriesEffect = (
   watchDirectory: string
 ): Effect.Effect<Set<string>, Error, never> => {
@@ -148,7 +156,8 @@ const readRouteDirectoriesEffect = (
   return walkDirectory(watchDirectory).pipe(Effect.as(directories));
 };
 
-export const createRouteTopologyWatcher = async ({
+const createRouteTopologyWatcherEffect = ({
+  runtime,
   watchDirectory,
   getRouteTopology,
   initialRouteTopology,
@@ -156,202 +165,171 @@ export const createRouteTopologyWatcher = async ({
   onError,
   onRouteTopologyChange,
   watchDirectoryEntry: watchDirectoryOverride = defaultWatchDirectoryEntry,
-}: {
-  watchDirectory: string;
-  getRouteTopology: () => Promise<Set<string>>;
-  initialRouteTopology?: Set<string>;
-  restartMarkerPath: string;
-  onError: (error: unknown) => void;
-  onRouteTopologyChange?: () => void | Promise<void>;
-  watchDirectoryEntry?: WatchDirectoryEntry;
-}): Promise<() => Promise<void>> => {
-  const discoveredDirectories = await readRouteDirectories(watchDirectory);
-  let discoveredState: RouteDirectoryState;
-  try {
-    discoveredState = {
+}: CreateRouteTopologyWatcherOptions) =>
+  Effect.gen(function* () {
+    const discoveredDirectories =
+      yield* readRouteDirectoriesEffect(watchDirectory);
+    const routeTopology = yield* tryPluginPromise(getRouteTopology).pipe(
+      Effect.catchAll(error => {
+        if (!initialRouteTopology) return Effect.fail(error);
+        onError(error);
+        return Effect.succeed(initialRouteTopology);
+      })
+    );
+    const discoveredState: RouteDirectoryState = {
       directories: discoveredDirectories,
-      routeTopology: await getRouteTopology(),
+      routeTopology,
     };
-  } catch (error) {
-    if (!initialRouteTopology) {
-      throw error;
-    }
-    onError(error);
-    discoveredState = {
-      directories: discoveredDirectories,
-      routeTopology: initialRouteTopology,
+    let state = {
+      ...discoveredState,
+      routeTopology: initialRouteTopology ?? discoveredState.routeTopology,
     };
-  }
-  let state = {
-    ...discoveredState,
-    routeTopology: initialRouteTopology ?? discoveredState.routeTopology,
-  };
-  let closed = false;
-  let rescanQueue = Promise.resolve();
-  const directoryWatchers = new Map<string, DirectoryWatcher>();
+    let closed = false;
+    const directoryWatchers = new Map<string, DirectoryWatcher>();
 
-  const touchRestartMarkerEffect = (): Effect.Effect<void, Error, never> =>
-    tryPluginPromise(() =>
-      mkdir(dirname(restartMarkerPath), { recursive: true })
-    ).pipe(
-      Effect.zipRight(
-        tryPluginPromise(() => writeFile(restartMarkerPath, String(Date.now())))
-      )
-    );
-
-  const closeRemovedDirectoryWatchers = (
-    nextDirectories: Set<string>
-  ): void => {
-    for (const [directory, watcher] of directoryWatchers) {
-      if (!nextDirectories.has(directory)) {
-        watcher.close();
-        directoryWatchers.delete(directory);
-      }
-    }
-  };
+    const touchRestartMarkerEffect = (): Effect.Effect<void, Error, never> =>
+      tryPluginPromise(() =>
+        mkdir(dirname(restartMarkerPath), { recursive: true })
+      ).pipe(
+        Effect.zipRight(
+          tryPluginPromise(() =>
+            writeFile(restartMarkerPath, String(Date.now()))
+          )
+        )
+      );
 
-  const watchNewDirectories = (nextDirectories: Set<string>): void => {
-    for (const directory of nextDirectories) {
-      if (directoryWatchers.has(directory)) {
-        continue;
-      }
-      try {
-        let watcher: DirectoryWatcher;
-        watcher = watchDirectoryOverride(
-          directory,
-          () => rescanTask.reschedule(),
-          error => {
-            if (directoryWatchers.get(directory) === watcher) {
-              watcher.close();
-              directoryWatchers.delete(directory);
-            }
-            onError(error);
-          }
-        );
-        directoryWatchers.set(directory, watcher);
-      } catch (error) {
-        onError(error);
+    const closeRemovedDirectoryWatchers = (
+      nextDirectories: Set<string>
+    ): void => {
+      for (const [directory, watcher] of directoryWatchers) {
+        if (!nextDirectories.has(directory)) {
+          watcher.close();
+          directoryWatchers.delete(directory);
+        }
       }
-    }
-  };
-
-  const syncDirectoryWatchers = (nextDirectories: Set<string>): void => {
-    closeRemovedDirectoryWatchers(nextDirectories);
-    watchNewDirectories(nextDirectories);
-  };
+    };
 
-  const applyNextStateEffect = (
-    nextState: RouteDirectoryState
-  ): Effect.Effect<void, Error, never> =>
-    Effect.suspend(() => {
-      if (closed) {
-        return Effect.void;
-      }
-      syncDirectoryWatchers(nextState.directories);
-      if (!areSetsEqual(state.routeTopology, nextState.routeTopology)) {
-        if (onRouteTopologyChange) {
-          // This is a notification boundary, not part of the rescan
-          // transaction. A custom-server callback may close this watcher while
-          // replacing its compiler, so awaiting it here would deadlock close().
-          state = nextState;
-          return Effect.sync(() => {
-            try {
-              void Promise.resolve(onRouteTopologyChange()).catch(onError);
-            } catch (error) {
+    const watchNewDirectories = (nextDirectories: Set<string>): void => {
+      for (const directory of nextDirectories) {
+        if (directoryWatchers.has(directory)) {
+          continue;
+        }
+        try {
+          let watcher: DirectoryWatcher;
+          watcher = watchDirectoryOverride(
+            directory,
+            () => {
+              if (!closed) rescanTask.reschedule();
+            },
+            error => {
+              if (closed) return;
+              if (directoryWatchers.get(directory) === watcher) {
+                watcher.close();
+                directoryWatchers.delete(directory);
+              }
               onError(error);
             }
-          });
+          );
+          directoryWatchers.set(directory, watcher);
+        } catch (error) {
+          onError(error);
         }
-        return touchRestartMarkerEffect().pipe(
-          Effect.zipRight(
-            Effect.sync(() => {
-              if (!closed) {
-                state = nextState;
-              }
-            })
-          )
-        );
       }
-      state = nextState;
-      return Effect.void;
-    });
+    };
 
-  const runRescanEffect = (): Effect.Effect<void, never, never> => {
-    let nextDirectories: Set<string> | undefined;
-    return Effect.gen(function* () {
-      if (closed) {
-        return;
-      }
-      nextDirectories = yield* readRouteDirectoriesEffect(watchDirectory);
-      if (closed) {
-        return;
-      }
-      const nextState = {
-        directories: nextDirectories,
-        routeTopology: yield* tryPluginPromise(getRouteTopology),
-      };
-      if (closed) {
-        return;
-      }
-      yield* applyNextStateEffect(nextState);
-    }).pipe(
-      Effect.catchAll(error =>
-        Effect.sync(() => {
-          if (nextDirectories && !closed) {
-            syncDirectoryWatchers(nextDirectories);
+    const syncDirectoryWatchers = (nextDirectories: Set<string>): void => {
+      closeRemovedDirectoryWatchers(nextDirectories);
+      watchNewDirectories(nextDirectories);
+    };
+
+    const applyNextStateEffect = (
+      nextState: RouteDirectoryState
+    ): Effect.Effect<void, Error, never> =>
+      Effect.suspend(() => {
+        if (closed) return Effect.void;
+        syncDirectoryWatchers(nextState.directories);
+        if (!areSetsEqual(state.routeTopology, nextState.routeTopology)) {
+          if (onRouteTopologyChange) {
+            // This is a notification boundary, not part of the rescan
+            // transaction. A custom-server callback may close this watcher while
+            // replacing its compiler, so awaiting it here would deadlock close().
+            state = nextState;
+            return Effect.sync(() => {
+              try {
+                void Promise.resolve(onRouteTopologyChange()).catch(onError);
+              } catch (error) {
+                onError(error);
+              }
+            });
           }
-          onError(error);
-        })
-      )
-    );
-  };
+          return touchRestartMarkerEffect().pipe(
+            Effect.zipRight(
+              Effect.sync(() => {
+                if (!closed) {
+                  state = nextState;
+                }
+              })
+            )
+          );
+        }
+        state = nextState;
+        return Effect.void;
+      });
 
-  const rescan = (): Promise<void> => {
-    rescanQueue = rescanQueue.then(
-      () => runPluginEffect(runRescanEffect()),
-      () => runPluginEffect(runRescanEffect())
-    );
-    return rescanQueue;
-  };
+    const runRescanEffect = (): Effect.Effect<void, never, never> => {
+      let nextDirectories: Set<string> | undefined;
+      return Effect.gen(function* () {
+        if (closed) return;
+        nextDirectories = yield* readRouteDirectoriesEffect(watchDirectory);
+        if (closed) return;
+        const nextState = {
+          directories: nextDirectories,
+          routeTopology: yield* tryPluginPromise(getRouteTopology),
+        };
+        if (closed) return;
+        yield* applyNextStateEffect(nextState);
+      }).pipe(
+        Effect.catchAll(error =>
+          Effect.sync(() => {
+            if (nextDirectories && !closed)
+              syncDirectoryWatchers(nextDirectories);
+            onError(error);
+          })
+        )
+      );
+    };
 
-  const rescanTask = createDelayedPluginTask({
-    delayMs: ROUTE_TOPOLOGY_RESCAN_DEBOUNCE_MS,
-    run: () =>
-      Effect.suspend(() =>
-        closed ? Effect.void : tryPluginPromise(rescan).pipe(Effect.asVoid)
-      ),
-    onError,
-  });
+    const rescanTask = createDelayedPluginTask({
+      runtime,
+      delayMs: ROUTE_TOPOLOGY_RESCAN_DEBOUNCE_MS,
+      run: () =>
+        Effect.suspend(() => (closed ? Effect.void : runRescanEffect())),
+      onError,
+    });
 
-  const cancelScheduledRescan = (): Promise<void> =>
-    runPluginEffect(rescanTask.cancelEffect());
+    const closeEffect = (): Effect.Effect<void, Error> =>
+      tryPluginPromise(() => {
+        if (closed) return;
+        closed = true;
+        for (const watcher of directoryWatchers.values()) {
+          watcher.close();
+        }
+        directoryWatchers.clear();
+      }).pipe(Effect.ensuring(rescanTask.cancelEffect()));
 
-  const applyNextState = async (nextState: RouteDirectoryState) => {
-    await runPluginEffect(applyNextStateEffect(nextState));
-  };
+    yield* applyNextStateEffect(discoveredState).pipe(
+      Effect.catchAll(error => Effect.sync(() => onError(error))),
+      Effect.onInterrupt(() => Effect.ignore(closeEffect()))
+    );
 
-  try {
-    await applyNextState(discoveredState);
-  } catch (error) {
-    onError(error);
-  }
+    return closeEffect;
+  });
 
-  return async () => {
-    if (closed) {
-      await cancelScheduledRescan();
-      await rescanQueue;
-      return;
-    }
-    closed = true;
-    await cancelScheduledRescan();
-    for (const watcher of directoryWatchers.values()) {
-      watcher.close();
-    }
-    directoryWatchers.clear();
-    await rescanQueue;
-    for (const watcher of directoryWatchers.values()) {
-      watcher.close();
-    }
-    directoryWatchers.clear();
-  };
-};
+export const acquireRouteTopologyWatcher = (
+  options: CreateRouteTopologyWatcherOptions
+): Effect.Effect<() => Effect.Effect<void, Error>, Error, Scope.Scope> =>
+  Effect.acquireRelease(createRouteTopologyWatcherEffect(options), close =>
+    close().pipe(
+      Effect.catchAll(error => Effect.sync(() => options.onError(error)))
+    )
+  );

package/src/rsc-dev-server.ts

@@ -0,0 +1,112 @@
+import { createRequestListener } from '@remix-run/node-fetch-server';
+import type { RsbuildConfig } from '@rsbuild/core';
+import { installDevServerSourceMapSupport } from './dev-source-maps.js';
+import { escapeHtml } from './plugin-utils.js';
+
+/**
+ * Turns an error thrown by the RSC server build into a source-mapped 500 HTML
+ * document. `@remix-run/node-fetch-server`'s request listener catches handler
+ * throws internally and, without an `onError`, emits a bare 500 with no body
+ * markup. React Router's classic dev path instead returns an ErrorBoundary
+ * document whose `<main>` carries the stack, and the integration test asserts
+ * on that `<main>`. Reading `error.stack` here triggers the installed
+ * `prepareStackTrace`, remapping generated `.js` frames back to the original
+ * `.tsx` source.
+ */
+const renderDevServerError = (error: unknown): Response => {
+  const stack =
+    error instanceof Error ? (error.stack ?? String(error)) : String(error);
+  return new Response(
+    `<!doctype html><html><body><main><pre>${escapeHtml(
+      stack
+    )}</pre></main></body></html>`,
+    { status: 500, headers: { 'content-type': 'text/html' } }
+  );
+};
+
+type RscServerBuild = {
+  default?: {
+    fetch?: (request: Request) => Promise<Response>;
+  };
+};
+
+type RscDevServerSetup = NonNullable<
+  NonNullable<RsbuildConfig['server']>['setup']
+>;
+
+type RscDevServerSetupOptions = {
+  entryName: string;
+  pluginName: string;
+};
+
+/**
+ * Decides whether a dev-server request should skip the RSC request handler
+ * and fall through to the rest of the middleware chain.
+ *
+ * Only Rsbuild-internal endpoints (`/__rsbuild_*`, e.g. HMR web socket
+ * fallbacks) are bypassed. Everything else — any method, any pathname,
+ * with or without a file extension — is handled by the RSC server build,
+ * matching production where the RSC server handles every request.
+ *
+ * Static assets need no bypass here: the RSC middleware is registered via
+ * the callback returned from `server.setup`, which Rsbuild invokes only
+ * after its built-in middlewares (compiled assets, public dir) are
+ * registered. A request that reaches this middleware was already declined
+ * by static asset serving.
+ */
+export const shouldBypassRscDevRequest = (request: {
+  url?: string;
+}): boolean => {
+  if (!request.url) {
+    return true;
+  }
+  const { pathname } = new URL(request.url, 'http://localhost');
+  return pathname.startsWith('/__rsbuild_');
+};
+
+export function createReactRouterRscDevServerSetup({
+  entryName,
+  pluginName,
+}: RscDevServerSetupOptions): RscDevServerSetup {
+  return context => {
+    if (context.action === 'preview') {
+      return;
+    }
+    const { server } = context;
+    // Remap generated `.js` stack frames back to original `.tsx` sources so a
+    // loader/render error surfaced below carries source-mapped locations, the
+    // same support the classic dev path installs.
+    installDevServerSourceMapSupport();
+    const listener = createRequestListener(
+      async request => {
+        const build =
+          await server.environments.node.loadBundle<RscServerBuild>(entryName);
+        const handler = build.default?.fetch;
+        if (typeof handler !== 'function') {
+          throw new Error(
+            `[${pluginName}] RSC server build must default-export an object with a fetch function.`
+          );
+        }
+        return handler(request);
+      },
+      { onError: renderDevServerError }
+    );
+
+    // Register the RSC middleware in the callback returned from
+    // `server.setup`. Rsbuild runs middlewares registered synchronously in
+    // `setup` BEFORE its built-ins, but runs returned callbacks AFTER
+    // built-in middlewares (compiled assets, public dir) are registered.
+    // Registering here makes the RSC handler the fallback for every request
+    // that static asset serving did not handle — the same routing semantics
+    // as production, where the RSC server handles everything.
+    return () => {
+      server.middlewares.use((req, res, next) => {
+        if (shouldBypassRscDevRequest(req)) {
+          next();
+          return;
+        }
+        Promise.resolve(listener(req, res)).catch(next);
+      });
+    };
+  };
+}