rsbuild-plugin-react-router 0.4.1 → 0.6.0

package/src/dev-runtime-controller.ts

@@ -1,7 +1,7 @@
 import type { RsbuildConfig, RsbuildPluginAPI, Rspack } from '@rsbuild/core';
-import * as Effect from 'effect/Effect';
 import type { ServerBuild } from 'react-router';
 import { PLUGIN_NAME } from './constants.js';
+import { escapeHtml } from './plugin-utils.js';
 import {
   beginDevCompilerAttempt,
   clearDevCompilerStart,
@@ -19,6 +19,7 @@ import {
   registerReactRouterDevRuntime,
   unregisterReactRouterDevRuntime,
 } from './dev-generation.js';
+import { DEV_MANIFEST_UPDATE_EVENT } from './dev-hmr.js';
 import {
   getEnvironmentStats,
   snapshotDevChangedFiles,
@@ -27,17 +28,11 @@ import {
   type ReactRouterDevBuildPlan,
   type ReactRouterDevManifestSet,
 } from './dev-runtime-artifacts.js';
-import { DEV_HDR_REVISION_RELATIVE_PATH } from './dev-hmr.js';
 import {
   createDevRuntimeSessionManager,
   type RuntimeBinding,
 } from './dev-runtime-session.js';
-import {
-  normalizeEffectError,
-  runPluginEffect,
-  tryPluginPromise,
-  tryPluginSync,
-} from './effect-runtime.js';
+import { normalizeEffectError } from './effect-runtime.js';
 
 type ServerSetup = Exclude<
   NonNullable<NonNullable<RsbuildConfig['server']>['setup']>,
@@ -56,6 +51,11 @@ type CreateControllerOptions = {
   api: RsbuildPluginAPI;
   isBuild: boolean;
   buildPlan: ReactRouterDevBuildPlan;
+  /**
+   * The browser HMR runtime patches route manifest metadata (loader/action
+   * flags) in place, so metadata-only changes no longer need a full reload.
+   */
+  clientPatchesRouteMetadata?: boolean | (() => boolean);
   /**
    * Invoked after a development attempt commits a re-evaluated node build for
    * changed server files. Used to signal hot data revalidation to the client.
@@ -63,36 +63,19 @@ type CreateControllerOptions = {
   onNodeRebuildCommitted?: () => void;
 };
 
-const escapeHtml = (value: string): string =>
-  value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;');
-
 const CSS_SOURCE_RELOAD_DELAY_MS = 1000;
 
 const isHdrRevisionFile = (file: string): boolean =>
-  file.includes(DEV_HDR_REVISION_RELATIVE_PATH);
+  file.includes('.react-router/hdr-revision.mjs');
 
 const isCssSourceFile = (file: string): boolean =>
   /\.css(?:\.[cm]?[jt]s)?$/.test(file);
 
-// A change that should bump the HDR revision: anything except the revision
-// file itself (the bump's own echo) and CSS sources (styling never changes
-// loader data).
-const hasHdrTriggeringChange = (files: Iterable<string>): boolean => {
-  for (const file of files) {
-    if (!isHdrRevisionFile(file) && !isCssSourceFile(file)) {
-      return true;
-    }
-  }
-  return false;
-};
-
 export const createReactRouterDevRuntimeController = ({
   api,
   isBuild,
   buildPlan,
+  clientPatchesRouteMetadata,
   onNodeRebuildCommitted,
 }: CreateControllerOptions): ReactRouterDevRuntimeController => {
   if (isBuild) {
@@ -165,56 +148,44 @@ export const createReactRouterDevRuntimeController = ({
     NonNullable<DevGraphIdentity['node']>
   >();
 
-  const finishRuntimeAttemptEffect = (
+  const finishRuntimeAttempt = async (
     binding: RuntimeBinding,
     pair: DevCompilerPair,
     stats: DevRuntimeStats,
     changes: Parameters<RuntimeBinding['runtime']['finishAttempt']>[1],
     identity: Parameters<RuntimeBinding['runtime']['finishAttempt']>[2]
-  ): Effect.Effect<void, Error, never> =>
-    tryPluginPromise(() =>
-      binding.runtime.finishAttempt(stats, changes, identity)
-    ).pipe(
-      Effect.flatMap(result =>
-        tryPluginSync(() => {
-          if (sessions.getActiveBinding()?.id !== binding.id) {
-            return;
-          }
-          if (result === 'retry-node') {
-            pair.node.watching?.invalidate();
-            return;
-          }
-          if (
-            result === 'committed' &&
-            changes.node.known &&
-            identity.node !== undefined &&
-            hdrSignaledNodeIdentity.get(pair) !== identity.node &&
-            hasHdrTriggeringChange(changes.node.files)
-          ) {
-            hdrSignaledNodeIdentity.set(pair, identity.node);
-            onNodeRebuildCommitted?.();
-          }
-        })
-      ),
-      Effect.catchAll(cause =>
-        tryPluginSync(() => {
-          if (sessions.getActiveBinding()?.id === binding.id) {
-            binding.runtime.failAttempt(normalizeEffectError(cause));
-          }
-        })
-      )
-    );
-
-  const finishRuntimeAttempt = (
-    binding: RuntimeBinding,
-    pair: DevCompilerPair,
-    stats: DevRuntimeStats,
-    changes: Parameters<RuntimeBinding['runtime']['finishAttempt']>[1],
-    identity: Parameters<RuntimeBinding['runtime']['finishAttempt']>[2]
-  ): Promise<void> =>
-    runPluginEffect(
-      finishRuntimeAttemptEffect(binding, pair, stats, changes, identity)
-    );
+  ): Promise<void> => {
+    try {
+      const result = await binding.runtime.finishAttempt(
+        stats,
+        changes,
+        identity
+      );
+      if (sessions.getActiveBinding()?.id !== binding.id) {
+        return;
+      }
+      if (result === 'retry-node') {
+        pair.node.watching?.invalidate();
+        return;
+      }
+      if (
+        result === 'committed' &&
+        changes.node.known &&
+        identity.node !== undefined &&
+        hdrSignaledNodeIdentity.get(pair) !== identity.node &&
+        Array.from(changes.node.files).some(
+          file => !isHdrRevisionFile(file) && !isCssSourceFile(file)
+        )
+      ) {
+        hdrSignaledNodeIdentity.set(pair, identity.node);
+        onNodeRebuildCommitted?.();
+      }
+    } catch (cause) {
+      if (sessions.getActiveBinding()?.id === binding.id) {
+        binding.runtime.failAttempt(normalizeEffectError(cause));
+      }
+    }
+  };
 
   const flushSettledAttempt = (
     binding: RuntimeBinding,
@@ -306,11 +277,22 @@ export const createReactRouterDevRuntimeController = ({
           reloadAfterCssAssetOwnershipRemoval = change === 'removed';
           sendCssAssetOwnershipReload();
         },
-        onRouteManifestChanged() {
+        onRouteManifestChanged(manifest) {
           if (sessions.getActiveBinding()?.runtime !== runtime) {
             return;
           }
-          server.sockWrite('full-reload', { path: '*' });
+          const patchesRouteMetadata =
+            typeof clientPatchesRouteMetadata === 'function'
+              ? clientPatchesRouteMetadata()
+              : clientPatchesRouteMetadata;
+          if (patchesRouteMetadata) {
+            server.sockWrite('custom', {
+              event: DEV_MANIFEST_UPDATE_EVENT,
+              data: manifest.routes,
+            });
+          } else {
+            server.sockWrite('full-reload', { path: '*' });
+          }
         },
         onWarning: message => api.logger.warn(message),
       });
@@ -566,21 +548,29 @@ export const createReactRouterDevRuntimeController = ({
     },
 
     createBuildLoader(entryName?: string): () => Promise<ServerBuild> {
-      const server = sessions.getActiveBinding()?.server;
-      if (server) {
-        return () => loadReactRouterServerBuild(server, entryName);
-      }
-      const state = sessions.getState();
-      if (state.status === 'terminal') {
-        const { error } = state;
-        return () => Promise.reject(error);
-      }
-      return () =>
-        Promise.reject(
+      // Pin the loader to the dev-server session active at creation time. Once a
+      // loader is handed to React Router for session N it must keep serving N (or
+      // fail loudly with 'not registered' once N closes) and never silently migrate
+      // to a replacement session — this preserves SSR generation/session coherency.
+      // The live fallback below applies ONLY when no session exists yet at creation
+      // (boundServer === undefined), i.e. a loader built during config setup before
+      // the dev server has started; there is no session to stay coherent with yet.
+      const boundServer = sessions.getActiveBinding()?.server;
+      return () => {
+        const server = boundServer ?? sessions.getActiveBinding()?.server;
+        if (server) {
+          return loadReactRouterServerBuild(server, entryName);
+        }
+        const state = sessions.getState();
+        if (state.status === 'terminal') {
+          return Promise.reject(state.error);
+        }
+        return Promise.reject(
           new Error(
             `[${PLUGIN_NAME}] The development server runtime is not ready.`
           )
         );
+      };
     },
   };
 };

package/src/dev-runtime-session.ts

@@ -1,13 +1,8 @@
 import type { RsbuildDevServer } from '@rsbuild/core';
-import * as Effect from 'effect/Effect';
 import { PLUGIN_NAME } from './constants.js';
 import type { ReactRouterDevRuntime } from './dev-generation.js';
 import type { DevCompilerPair } from './dev-runtime-compilation.js';
-import {
-  runPluginEffect,
-  tryPluginPromise,
-  tryPluginSync,
-} from './effect-runtime.js';
+import { normalizeEffectError } from './effect-runtime.js';
 
 export type RuntimeBinding = {
   id: number;
@@ -115,18 +110,19 @@ export const createDevRuntimeSessionManager = (
       if (observation.promise) {
         return observation.promise;
       }
-      observation.promise = runPluginEffect(
-        tryPluginPromise(close).pipe(
-          Effect.tap(() =>
-            tryPluginSync(() => applyCloseOutcome(observation, { ok: true }))
-          ),
-          Effect.catchAll(cause =>
-            tryPluginSync(() =>
-              applyCloseOutcome(observation, { ok: false, cause })
-            ).pipe(Effect.zipRight(Effect.fail(cause)))
-          )
-        )
-      );
+      let closePromise: Promise<void>;
+      try {
+        closePromise = Promise.resolve(close());
+      } catch (cause) {
+        closePromise = Promise.reject(normalizeEffectError(cause));
+      }
+      observation.promise = closePromise
+        .then(() => applyCloseOutcome(observation, { ok: true }))
+        .catch(cause => {
+          const error = normalizeEffectError(cause);
+          applyCloseOutcome(observation, { ok: false, cause: error });
+          throw error;
+        });
       return observation.promise;
     };
     closeObservationByServer.set(server, observation);

package/src/dev-server.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { RsbuildConfig } from '@rsbuild/core';
 import type { ServerBuild } from 'react-router';
+import { installDevServerSourceMapSupport } from './dev-source-maps.js';
 
 export type ServerSetup = Exclude<
   NonNullable<NonNullable<RsbuildConfig['server']>['setup']>,
@@ -83,6 +84,7 @@ export const createReactRouterDevServerSetup = ({
     // middlewares, so static assets are served before the React Router
     // request handler.
     return () => {
+      installDevServerSourceMapSupport();
       context.server.middlewares.use(createDevServerMiddleware({ loadBuild }));
     };
   };

package/src/dev-source-maps.ts

@@ -0,0 +1,257 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { SourceMap, type SourceMapPayload } from 'node:module';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Rspack } from '@rsbuild/core';
+
+type CachedSourceMap = {
+  cacheKey: string;
+  sourceMap: SourceMap | null;
+};
+
+type InMemorySourceMap = {
+  load: () => SourceMapPayload | null;
+  sourceMap?: SourceMap | null;
+};
+
+const SOURCE_MAPPING_URL_MARKER = '//# sourceMappingURL=';
+const GENERATED_JS_FRAME_RE =
+  /(file:\/\/\/[^\s()]+\.m?js|\/[^\s()]+\.m?js):(\d+):(\d+)/g;
+
+let installed = false;
+let previousPrepareStackTrace: typeof Error.prepareStackTrace;
+const sourceMapCache = new Map<string, CachedSourceMap>();
+const inMemorySourceMaps = new Map<string, InMemorySourceMap>();
+const generatedFilesByOutputPath = new Map<string, Set<string>>();
+
+const getGeneratedFilePath = (fileName: string): string => {
+  if (fileName.startsWith('file://')) {
+    return fileURLToPath(fileName);
+  }
+  return fileName;
+};
+
+const getCacheKey = (filePath: string): string | null => {
+  try {
+    const generatedStats = statSync(filePath);
+    const mapPath = `${filePath}.map`;
+    const mapStats = existsSync(mapPath) ? statSync(mapPath) : undefined;
+    return [
+      generatedStats.mtimeMs,
+      generatedStats.size,
+      mapStats?.mtimeMs ?? 0,
+      mapStats?.size ?? 0,
+    ].join(':');
+  } catch {
+    return null;
+  }
+};
+
+const parseSourceMapPayload = (sourceMapJson: string): SourceMapPayload => {
+  const payload = JSON.parse(sourceMapJson) as Partial<SourceMapPayload>;
+  return {
+    file: payload.file ?? '',
+    version: payload.version ?? 3,
+    sources: payload.sources ?? [],
+    sourcesContent: payload.sourcesContent ?? [],
+    names: payload.names ?? [],
+    mappings: payload.mappings ?? '',
+    sourceRoot: payload.sourceRoot ?? '',
+  };
+};
+
+const toSourceMapPayload = (value: unknown): SourceMapPayload | null => {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const payload = value as Partial<SourceMapPayload>;
+  return {
+    file: payload.file ?? '',
+    version: payload.version ?? 3,
+    sources: payload.sources ?? [],
+    sourcesContent: payload.sourcesContent ?? [],
+    names: payload.names ?? [],
+    mappings: payload.mappings ?? '',
+    sourceRoot: payload.sourceRoot ?? '',
+  };
+};
+
+const readInlineSourceMap = (filePath: string): string | null => {
+  const source = readFileSync(filePath, 'utf8');
+  const markerIndex = source.lastIndexOf(SOURCE_MAPPING_URL_MARKER);
+  if (markerIndex === -1) {
+    return null;
+  }
+
+  const sourceMapUrlStart = markerIndex + SOURCE_MAPPING_URL_MARKER.length;
+  const nextLineIndex = source.indexOf('\n', sourceMapUrlStart);
+  const sourceMapUrl = source
+    .slice(sourceMapUrlStart, nextLineIndex === -1 ? undefined : nextLineIndex)
+    .trim();
+  if (!sourceMapUrl.startsWith('data:')) {
+    return null;
+  }
+
+  const commaIndex = sourceMapUrl.indexOf(',');
+  if (commaIndex === -1) {
+    return null;
+  }
+
+  const metadata = sourceMapUrl.slice(0, commaIndex);
+  const data = sourceMapUrl.slice(commaIndex + 1);
+  return metadata.endsWith(';base64')
+    ? Buffer.from(data, 'base64').toString('utf8')
+    : decodeURIComponent(data);
+};
+
+const readSourceMapPayload = (filePath: string): SourceMapPayload | null => {
+  const inlineSourceMap = readInlineSourceMap(filePath);
+  if (inlineSourceMap) {
+    return parseSourceMapPayload(inlineSourceMap);
+  }
+
+  const externalSourceMapPath = `${filePath}.map`;
+  if (!existsSync(externalSourceMapPath)) {
+    return null;
+  }
+
+  return parseSourceMapPayload(readFileSync(externalSourceMapPath, 'utf8'));
+};
+
+const getSourceMap = (filePath: string): SourceMap | null => {
+  const inMemory = inMemorySourceMaps.get(filePath);
+  if (inMemory) {
+    if (inMemory.sourceMap !== undefined) {
+      return inMemory.sourceMap;
+    }
+    try {
+      const payload = inMemory.load();
+      inMemory.sourceMap = payload ? new SourceMap(payload) : null;
+    } catch {
+      inMemory.sourceMap = null;
+    }
+    return inMemory.sourceMap;
+  }
+
+  const cacheKey = getCacheKey(filePath);
+  if (!cacheKey) {
+    return null;
+  }
+
+  const cached = sourceMapCache.get(filePath);
+  if (cached?.cacheKey === cacheKey) {
+    return cached.sourceMap;
+  }
+
+  let sourceMap: SourceMap | null = null;
+  try {
+    const payload = readSourceMapPayload(filePath);
+    sourceMap = payload ? new SourceMap(payload) : null;
+  } catch {
+    sourceMap = null;
+  }
+
+  sourceMapCache.set(filePath, { cacheKey, sourceMap });
+  return sourceMap;
+};
+
+export const registerDevServerSourceMaps = (
+  compilation: Pick<Rspack.Compilation, 'getAssets' | 'outputOptions'>
+): void => {
+  const outputPath = compilation.outputOptions.path;
+  if (!outputPath) {
+    return;
+  }
+  const previousFiles = generatedFilesByOutputPath.get(outputPath);
+  if (previousFiles) {
+    for (const filePath of previousFiles) {
+      inMemorySourceMaps.delete(filePath);
+    }
+  }
+
+  const assets = compilation.getAssets();
+  const assetsByName = new Map(assets.map(asset => [asset.name, asset]));
+  const generatedFiles = new Set<string>();
+
+  for (const asset of assets) {
+    if (!/\.m?js$/.test(asset.name)) {
+      continue;
+    }
+
+    const generatedFilePath = resolve(outputPath, asset.name);
+    const externalMap = assetsByName.get(`${asset.name}.map`);
+    const load = externalMap
+      ? () =>
+          parseSourceMapPayload(externalMap.source.buffer().toString('utf8'))
+      : () => toSourceMapPayload(asset.source.map());
+
+    generatedFiles.add(generatedFilePath);
+    inMemorySourceMaps.set(generatedFilePath, { load });
+  }
+
+  generatedFilesByOutputPath.set(outputPath, generatedFiles);
+};
+
+const resolveOriginalFileName = (
+  generatedFilePath: string,
+  originalFileName: string
+): string => {
+  if (
+    isAbsolute(originalFileName) ||
+    originalFileName.startsWith('node:') ||
+    originalFileName.includes('://')
+  ) {
+    return originalFileName;
+  }
+  return resolve(dirname(generatedFilePath), originalFileName);
+};
+
+export const remapDevServerStack = (stack: string): string =>
+  stack.replace(GENERATED_JS_FRAME_RE, (match, fileName, line, column) => {
+    const generatedFilePath = getGeneratedFilePath(fileName);
+    const sourceMap = getSourceMap(generatedFilePath);
+    const origin = sourceMap?.findOrigin(Number(line), Number(column));
+    if (!origin || !('fileName' in origin)) {
+      return match;
+    }
+
+    return `${resolveOriginalFileName(
+      generatedFilePath,
+      origin.fileName
+    )}:${origin.lineNumber}:${origin.columnNumber}`;
+  });
+
+const formatStackTrace = (
+  error: Error,
+  callSites: NodeJS.CallSite[]
+): string => {
+  const message = error.message
+    ? `${error.name}: ${error.message}`
+    : error.name;
+  const frames = callSites.map(callSite => `    at ${callSite.toString()}`);
+  return [message, ...frames].join('\n');
+};
+
+const prepareStackTrace: NonNullable<typeof Error.prepareStackTrace> = (
+  error,
+  callSites
+) => {
+  const formattedStack =
+    previousPrepareStackTrace && previousPrepareStackTrace !== prepareStackTrace
+      ? previousPrepareStackTrace(error, callSites)
+      : formatStackTrace(error, callSites);
+
+  return typeof formattedStack === 'string'
+    ? remapDevServerStack(formattedStack)
+    : formattedStack;
+};
+
+export const installDevServerSourceMapSupport = (): void => {
+  if (installed) {
+    return;
+  }
+
+  installed = true;
+  previousPrepareStackTrace = Error.prepareStackTrace;
+  Error.prepareStackTrace = prepareStackTrace;
+};