rsbuild-plugin-react-router 0.2.0 → 0.3.1

package/src/build-output-transforms.ts

@@ -0,0 +1,273 @@
+import type { RsbuildPluginAPI, TransformHandler } from '@rsbuild/core';
+import jsesc from 'jsesc';
+import { relative } from 'pathe';
+import { PLUGIN_NAME } from './constants.js';
+import {
+  getReactRouterManifestForDev,
+  type ReactRouterManifestStats,
+} from './manifest.js';
+import type { RouteTransformExecutor } from './parallel-route-transforms.js';
+import type { ReactRouterPerformanceProfiler } from './performance.js';
+import { createBundlerRouteExportResolver } from './route-export-resolution.js';
+import type { RouteChunkConfig } from './route-chunks.js';
+import type { PluginOptions, Route } from './types.js';
+import { isSourceMapEnabled } from './warnings/warn-on-client-source-maps.js';
+
+type ReactRouterManifest = Awaited<
+  ReturnType<typeof getReactRouterManifestForDev>
+>;
+
+type RegisterBuildOutputTransformsOptions = {
+  api: RsbuildPluginAPI;
+  resolvedServerOutput: 'module' | 'commonjs';
+  performanceProfiler: ReactRouterPerformanceProfiler;
+  getLatestServerManifest: () => ReactRouterManifest | null;
+  getLatestServerManifestByBundleId: (
+    bundleId: string
+  ) => ReactRouterManifest | undefined;
+  routes: Record<string, Route>;
+  pluginOptions: PluginOptions;
+  getClientStats: () => ReactRouterManifestStats | undefined;
+  appDirectory: string;
+  getAssetPrefix: () => string;
+  routeChunkOptions: Parameters<typeof getReactRouterManifestForDev>[5];
+  routeTransformExecutor: RouteTransformExecutor;
+  routeByFilePath: Map<string, Route>;
+  routeChunkConfig: RouteChunkConfig;
+  isBuild: boolean;
+  splitRouteModules: boolean;
+  ssr: boolean;
+  isSpaMode: boolean;
+  rootRoutePath: string;
+};
+
+export const registerBuildOutputTransforms = ({
+  api,
+  resolvedServerOutput,
+  performanceProfiler,
+  getLatestServerManifest,
+  getLatestServerManifestByBundleId,
+  routes,
+  pluginOptions,
+  getClientStats,
+  appDirectory,
+  getAssetPrefix,
+  routeChunkOptions,
+  routeTransformExecutor,
+  routeByFilePath,
+  routeChunkConfig,
+  isBuild,
+  splitRouteModules,
+  ssr,
+  isSpaMode,
+  rootRoutePath,
+}: RegisterBuildOutputTransformsOptions): void => {
+  const transformRouteModule = async (args: Parameters<TransformHandler>[0]) =>
+    performanceProfiler.record(
+      args.environment?.name,
+      'route:module',
+      args.resource,
+      async () =>
+        routeTransformExecutor.run({
+          kind: 'routeModule',
+          code: args.code,
+          resource: args.resource,
+          resourcePath: args.resourcePath,
+          environmentName: args.environment.name,
+          sourceMaps: isSourceMapEnabled(
+            args.environment.config.output.sourceMap
+          ),
+          ssr,
+          isBuild,
+          isSpaMode,
+          rootRoutePath,
+        })
+    );
+
+  api.processAssets(
+    { stage: 'additional', targets: ['node'] },
+    ({ sources, compilation }) => {
+      const packageJsonPath = 'package.json';
+      const source = new sources.RawSource(
+        `{"type": "${resolvedServerOutput}"}`
+      );
+
+      if (compilation.getAsset(packageJsonPath)) {
+        compilation.updateAsset(packageJsonPath, source);
+      } else {
+        compilation.emitAsset(packageJsonPath, source);
+      }
+    }
+  );
+
+  api.transform(
+    {
+      test: /virtual\/react-router\/(browser|server)-manifest/,
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'manifest:transform',
+        args.resource,
+        async () => {
+          if (args.environment.name === 'web') {
+            return {
+              code: `window.__reactRouterManifest = "PLACEHOLDER";`,
+            };
+          }
+
+          const bundleMatch = args.resource.match(
+            /virtual\/react-router\/server-manifest(?:-([^?]+))?/
+          );
+          const bundleId = bundleMatch?.[1]?.replace(/\.js$/, '');
+          const latestServerManifest = getLatestServerManifest();
+          const manifest =
+            (latestServerManifest
+              ? ((bundleId && getLatestServerManifestByBundleId(bundleId)) ??
+                latestServerManifest)
+              : null) ??
+            (await getReactRouterManifestForDev(
+              routes,
+              pluginOptions,
+              getClientStats(),
+              appDirectory,
+              getAssetPrefix(),
+              routeChunkOptions
+            ));
+          return {
+            code: `export default ${jsesc(manifest, { es6: true })};`,
+          };
+        }
+      )
+  );
+
+  api.transform(
+    {
+      resourceQuery: /__react-router-build-client-route/,
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'route:client-entry',
+        args.resource,
+        async () =>
+          routeTransformExecutor.run({
+            kind: 'routeClientEntry',
+            code: args.code,
+            resourcePath: args.resourcePath,
+            environmentName: args.environment?.name,
+            isBuild,
+            routeChunkConfig,
+          })
+      )
+  );
+
+  api.transform(
+    {
+      resourceQuery: /route-chunk=/,
+      environments: ['web'],
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'route:chunk',
+        args.resource,
+        async () =>
+          routeTransformExecutor.run({
+            kind: 'routeChunk',
+            code: args.code,
+            resource: args.resource,
+            resourcePath: args.resourcePath,
+            isBuild,
+            routeChunkConfig,
+          })
+      )
+  );
+
+  if (isBuild && splitRouteModules) {
+    api.transform(
+      {
+        test: path => routeByFilePath.has(path),
+        resourceQuery: {
+          not: /__react-router-build-client-route|react-router-route|route-chunk=/,
+        },
+        environments: ['web'],
+      },
+      async args =>
+        performanceProfiler.record(
+          args.environment?.name,
+          'route:split-exports',
+          args.resource,
+          async () =>
+            routeTransformExecutor.run({
+              kind: 'splitRouteExports',
+              code: args.code,
+              resourcePath: args.resourcePath,
+              routeChunkConfig,
+            })
+        )
+    );
+  }
+
+  api.transform(
+    {
+      test: /[\\/]\.server[\\/]|\.server(\.[cm]?[jt]sx?)?$/,
+      environments: ['web'],
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'module:server-only-guard',
+        args.resource,
+        async () => {
+          const relativePath = relative(process.cwd(), args.resourcePath);
+          throw new Error(
+            `[${PLUGIN_NAME}] Server-only module referenced by client: ${relativePath}`
+          );
+        }
+      )
+  );
+
+  api.transform(
+    {
+      test: /[\\/]\.client[\\/]|\.client(\.[cm]?[jt]sx?)?$/,
+      environments: ['node'],
+    },
+    async args =>
+      performanceProfiler.record(
+        args.environment?.name,
+        'module:client-only-stub',
+        args.resource,
+        async () => {
+          return routeTransformExecutor.run({
+            kind: 'clientOnlyStub',
+            code: args.code,
+            resourcePath: args.resourcePath,
+            resolveExportAllModule:
+              typeof args.resolve === 'function'
+                ? createBundlerRouteExportResolver(args.resolve)
+                : undefined,
+          });
+        }
+      )
+  );
+
+  api.transform(
+    {
+      resourceQuery: /\?react-router-route/,
+      order: 'post',
+    },
+    transformRouteModule
+  );
+
+  api.transform(
+    {
+      test: path => routeByFilePath.has(path),
+      resourceQuery: {
+        not: /__react-router-build-client-route|react-router-route|route-chunk=/,
+      },
+      order: 'post',
+    },
+    transformRouteModule
+  );
+};

package/src/concurrency.ts

@@ -0,0 +1,15 @@
+import { availableParallelism, cpus } from 'node:os';
+
+const DEFAULT_RESERVED_CORES = 2;
+
+export const getAvailableCpuCount = (): number =>
+  typeof availableParallelism === 'function'
+    ? availableParallelism()
+    : cpus().length;
+
+export const getDefaultConcurrency = (
+  cpuCount: number = getAvailableCpuCount()
+): number => Math.max(0, Math.floor(cpuCount) - DEFAULT_RESERVED_CORES);
+
+export const getCappedPluginConcurrency = (cap = 16): number =>
+  Math.max(1, Math.min(cap, getDefaultConcurrency() || 1));

package/src/config-imports.ts

@@ -0,0 +1,83 @@
+import type { ModuleCache } from 'jiti';
+import { createJiti } from 'jiti';
+import { resolve } from 'pathe';
+
+type ConfigImporter = Pick<ReturnType<typeof createJiti>, 'import'>;
+
+const normalizePath = (filePath: string): string => resolve(filePath);
+
+const isNodeModulePath = (filePath: string): boolean =>
+  filePath.split(/[\\/]/).includes('node_modules');
+
+export const collectConfigImportWatchPaths = (
+  configPath: string,
+  moduleCache: ModuleCache,
+  previousCacheKeys: ReadonlySet<string>
+): string[] => {
+  const normalizedConfigPath = normalizePath(configPath);
+  const watchPaths = new Set<string>();
+
+  for (const [cacheKey, module] of Object.entries(moduleCache)) {
+    if (previousCacheKeys.has(cacheKey)) {
+      continue;
+    }
+
+    const importPath = normalizePath(module?.filename ?? cacheKey);
+    if (importPath === normalizedConfigPath || isNodeModulePath(importPath)) {
+      continue;
+    }
+
+    watchPaths.add(importPath);
+  }
+
+  return Array.from(watchPaths);
+};
+
+export const clearConfigImportCache = (
+  moduleCache: ModuleCache,
+  filePaths: readonly string[]
+): void => {
+  const normalizedFilePaths = new Set(filePaths.map(normalizePath));
+
+  for (const [cacheKey, module] of Object.entries(moduleCache)) {
+    const cachedPath = normalizePath(module?.filename ?? cacheKey);
+    if (normalizedFilePaths.has(cachedPath)) {
+      delete moduleCache[cacheKey];
+    }
+  }
+};
+
+export const importConfigWithWatchPaths = async <T>(
+  configPath: string,
+  load: (importer: ConfigImporter) => PromiseLike<T> | T = async importer =>
+    importer.import<T>(configPath, { default: true })
+): Promise<{ value: Awaited<T>; watchPaths: string | string[] }> => {
+  const jiti = createJiti(process.cwd(), {
+    moduleCache: true,
+  });
+  const previousCacheKeys = new Set(Object.keys(jiti.cache));
+  let importPaths: string[] = [];
+
+  try {
+    const value = await load(jiti);
+    importPaths = collectConfigImportWatchPaths(
+      configPath,
+      jiti.cache,
+      previousCacheKeys
+    );
+    return {
+      value,
+      watchPaths:
+        importPaths.length > 0 ? [configPath, ...importPaths] : configPath,
+    };
+  } finally {
+    if (importPaths.length === 0) {
+      importPaths = collectConfigImportWatchPaths(
+        configPath,
+        jiti.cache,
+        previousCacheKeys
+      );
+    }
+    clearConfigImportCache(jiti.cache, [configPath, ...importPaths]);
+  }
+};

package/src/constants.ts

@@ -0,0 +1,91 @@
+export const PLUGIN_NAME = 'rsbuild:react-router';
+
+export const JS_EXTENSIONS = [
+  '.tsx',
+  '.ts',
+  '.jsx',
+  '.js',
+  '.mjs',
+  '.mts',
+] as const;
+
+export const JS_LOADERS = {
+  '.ts': 'ts',
+  '.tsx': 'tsx',
+  '.js': 'js',
+  '.jsx': 'jsx',
+  '.mjs': 'js',
+  '.mts': 'ts',
+} as const;
+
+export const BUILD_CLIENT_ROUTE_QUERY_STRING =
+  '?__react-router-build-client-route';
+
+export const SERVER_ONLY_ROUTE_EXPORTS = [
+  'loader',
+  'action',
+  'middleware',
+  'headers',
+] as const;
+
+export const SERVER_ONLY_ROUTE_EXPORTS_SET: ReadonlySet<string> = new Set(
+  SERVER_ONLY_ROUTE_EXPORTS
+);
+
+// Client route exports are split into non-component exports and component exports.
+// This mirrors upstream React Router Vite plugin intent and is used for export filtering.
+export const CLIENT_NON_COMPONENT_EXPORTS = [
+  'clientAction',
+  'clientLoader',
+  'clientMiddleware',
+  'handle',
+  'meta',
+  'links',
+  'shouldRevalidate',
+] as const;
+
+export const CLIENT_COMPONENT_EXPORTS = [
+  'default',
+  'ErrorBoundary',
+  'HydrateFallback',
+  'Layout',
+] as const;
+
+export const CLIENT_ROUTE_EXPORTS: readonly (
+  | (typeof CLIENT_NON_COMPONENT_EXPORTS)[number]
+  | (typeof CLIENT_COMPONENT_EXPORTS)[number]
+)[] = [...CLIENT_NON_COMPONENT_EXPORTS, ...CLIENT_COMPONENT_EXPORTS];
+
+export const CLIENT_ROUTE_EXPORTS_SET: ReadonlySet<string> = new Set(
+  CLIENT_ROUTE_EXPORTS
+);
+
+export const NAMED_COMPONENT_EXPORTS = [
+  'HydrateFallback',
+  'ErrorBoundary',
+] as const;
+
+export const NAMED_COMPONENT_EXPORTS_SET: ReadonlySet<string> = new Set(
+  NAMED_COMPONENT_EXPORTS
+);
+
+export const SERVER_EXPORTS = {
+  loader: 'loader',
+  action: 'action',
+  middleware: 'middleware',
+  headers: 'headers',
+} as const;
+
+export const CLIENT_EXPORTS = {
+  clientAction: 'clientAction',
+  clientLoader: 'clientLoader',
+  clientMiddleware: 'clientMiddleware',
+  default: 'default',
+  ErrorBoundary: 'ErrorBoundary',
+  handle: 'handle',
+  HydrateFallback: 'HydrateFallback',
+  Layout: 'Layout',
+  links: 'links',
+  meta: 'meta',
+  shouldRevalidate: 'shouldRevalidate',
+} as const;

package/src/dev-background-resources.ts

@@ -0,0 +1,255 @@
+import type { RsbuildPluginAPI } from '@rsbuild/core';
+import type { RouteConfigEntry } from '@react-router/dev/routes';
+import * as Effect from 'effect/Effect';
+import { relative } from 'pathe';
+import { PLUGIN_NAME } from './constants.js';
+import {
+  createDelayedPluginTask,
+  DEV_BACKGROUND_STARTUP_DELAY_MS,
+  normalizeEffectError,
+  runPluginEffect,
+  tryPluginPromise,
+} from './effect-runtime.js';
+import {
+  createLazyCompilationPrewarmController,
+  normalizeLazyCompilationPrewarmOptions,
+} from './lazy-compilation-prewarm.js';
+import {
+  configRoutesToRouteManifestEntries,
+  type ReactRouterManifestForDev,
+} from './manifest.js';
+import type { RouteTransformExecutor } from './parallel-route-transforms.js';
+import {
+  createRouteManifestSnapshot,
+  createRouteTopologyWatcher,
+  ensureDevRestartMarker,
+  type WatchFileConfig,
+} from './route-watch.js';
+import type { PluginOptions } from './types.js';
+
+type RegisterReactRouterDevBackgroundResourcesOptions = {
+  api: RsbuildPluginAPI;
+  isBuild: boolean;
+  lazyCompilationPrewarm: PluginOptions['unstableLazyCompilationPrewarm'];
+  routeTransformExecutor: RouteTransformExecutor;
+  routeRestartMarkerPath: string;
+  watchDirectory: string;
+  getRouteTopology: () => Promise<Set<string>>;
+  initialRouteTopology: Set<string>;
+  onRouteTopologyChange: PluginOptions['onRouteTopologyChange'];
+};
+
+type ReactRouterDevBackgroundResources = {
+  setManifest(manifest: ReactRouterManifestForDev): void;
+};
+
+export const createReactRouterRouteTopology = ({
+  appDirectory,
+  rootRouteFile,
+  routeConfig,
+  loadRouteConfig,
+  getRootRoutePath,
+}: {
+  appDirectory: string;
+  rootRouteFile: string;
+  routeConfig: RouteConfigEntry[];
+  loadRouteConfig: () => Promise<RouteConfigEntry[]>;
+  getRootRoutePath: () => string;
+}): {
+  initialRouteTopology: Set<string>;
+  getRouteTopology: () => Promise<Set<string>>;
+} => {
+  const createSnapshot = (
+    routeFile: string,
+    routeConfigEntries: RouteConfigEntry[]
+  ): Set<string> =>
+    createRouteManifestSnapshot([
+      ['root', { path: '', id: 'root', file: routeFile }],
+      ...configRoutesToRouteManifestEntries(appDirectory, routeConfigEntries),
+    ]);
+
+  return {
+    initialRouteTopology: createSnapshot(rootRouteFile, routeConfig),
+    async getRouteTopology() {
+      const latestRouteConfig = await loadRouteConfig();
+      const latestRootRouteFile = relative(appDirectory, getRootRoutePath());
+      return createSnapshot(latestRootRouteFile, latestRouteConfig);
+    },
+  };
+};
+
+export const createReactRouterRouteWatchFiles = ({
+  configWatchPaths,
+  routeConfigWatchPaths,
+  routeRestartMarkerPath,
+  onRouteTopologyChange,
+}: {
+  configWatchPaths: string | string[];
+  routeConfigWatchPaths: string | string[];
+  routeRestartMarkerPath: string;
+  onRouteTopologyChange: PluginOptions['onRouteTopologyChange'];
+}): WatchFileConfig[] => {
+  const watchFiles: WatchFileConfig[] = [
+    {
+      paths: configWatchPaths,
+      type: 'reload-server',
+    },
+  ];
+
+  if (!onRouteTopologyChange) {
+    watchFiles.push(
+      {
+        paths: routeConfigWatchPaths,
+        type: 'reload-server',
+      },
+      {
+        paths: routeRestartMarkerPath,
+        type: 'reload-server',
+      }
+    );
+  }
+
+  return watchFiles;
+};
+
+const closeAll = async (
+  message: string,
+  closers: Array<() => Promise<void>>
+): Promise<void> => {
+  const results = await Promise.allSettled(closers.map(closer => closer()));
+  const errors = results
+    .filter(
+      (result): result is PromiseRejectedResult => result.status === 'rejected'
+    )
+    .map(result => normalizeEffectError(result.reason));
+
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, message);
+  }
+};
+
+export const registerReactRouterDevBackgroundResources = ({
+  api,
+  isBuild,
+  lazyCompilationPrewarm,
+  routeTransformExecutor,
+  routeRestartMarkerPath,
+  watchDirectory,
+  getRouteTopology,
+  initialRouteTopology,
+  onRouteTopologyChange,
+}: RegisterReactRouterDevBackgroundResourcesOptions): ReactRouterDevBackgroundResources => {
+  let closeActiveRouteTopologyWatcher: (() => Promise<void>) | undefined;
+  let routeTopologyWatcherClosed = false;
+
+  const reportRouteTopologyWatcherError = (error: unknown): void => {
+    api.logger.warn(
+      `[${PLUGIN_NAME}] Failed to watch route topology changes: ${String(normalizeEffectError(error))}`
+    );
+  };
+
+  const routeTopologyWatcherTask = createDelayedPluginTask({
+    delayMs: DEV_BACKGROUND_STARTUP_DELAY_MS,
+    run: () =>
+      Effect.gen(function* () {
+        yield* tryPluginPromise(() =>
+          ensureDevRestartMarker(routeRestartMarkerPath)
+        );
+        const closeWatcher = yield* tryPluginPromise(() =>
+          createRouteTopologyWatcher({
+            watchDirectory,
+            getRouteTopology,
+            initialRouteTopology,
+            restartMarkerPath: routeRestartMarkerPath,
+            onRouteTopologyChange,
+            onError: reportRouteTopologyWatcherError,
+          })
+        );
+        if (routeTopologyWatcherClosed) {
+          yield* tryPluginPromise(() => closeWatcher());
+          return;
+        }
+        closeActiveRouteTopologyWatcher = closeWatcher;
+      }),
+    onError: reportRouteTopologyWatcherError,
+  });
+
+  const scheduleRouteTopologyWatcher = (): void => {
+    if (routeTopologyWatcherClosed || closeActiveRouteTopologyWatcher) {
+      return;
+    }
+    routeTopologyWatcherTask.schedule();
+  };
+
+  const lazyCompilationPrewarmConfig = normalizeLazyCompilationPrewarmOptions(
+    lazyCompilationPrewarm
+  );
+  const lazyCompilationPrewarmController = lazyCompilationPrewarmConfig
+    ? createLazyCompilationPrewarmController({
+        config: lazyCompilationPrewarmConfig,
+        onError: error =>
+          api.logger.warn(
+            `[${PLUGIN_NAME}] Lazy compilation prewarm skipped: ${error.message}`
+          ),
+      })
+    : null;
+
+  if (!isBuild) {
+    api.onBeforeStartDevServer(() => {
+      routeTopologyWatcherClosed = false;
+    });
+
+    api.onAfterStartDevServer(({ port }) => {
+      lazyCompilationPrewarmController?.setServerOrigin(
+        `http://localhost:${port}`
+      );
+      lazyCompilationPrewarmController?.schedule();
+    });
+
+    api.onAfterDevCompile(() => {
+      scheduleRouteTopologyWatcher();
+      lazyCompilationPrewarmController?.schedule();
+    });
+
+    // Spawn transform workers now so thread startup overlaps Rsbuild's own
+    // compiler creation instead of delaying the first route transform.
+    routeTransformExecutor.prewarm();
+  }
+
+  const closeRouteTopologyWatcher = async (): Promise<void> => {
+    routeTopologyWatcherClosed = true;
+    await runPluginEffect(routeTopologyWatcherTask.cancelEffect());
+    await closeActiveRouteTopologyWatcher?.();
+    closeActiveRouteTopologyWatcher = undefined;
+  };
+
+  const closeLazyCompilationPrewarm = async (): Promise<void> => {
+    await runPluginEffect(
+      lazyCompilationPrewarmController?.cancelEffect() ?? Effect.void
+    );
+  };
+
+  const closeRouteTransformExecutor = (): Promise<void> =>
+    routeTransformExecutor.close();
+
+  api.onCloseDevServer(() =>
+    closeAll(
+      '[rsbuild-plugin-react-router] Failed to close dev server resources.',
+      [
+        closeRouteTopologyWatcher,
+        closeLazyCompilationPrewarm,
+        closeRouteTransformExecutor,
+      ]
+    )
+  );
+  api.onCloseBuild(closeRouteTransformExecutor);
+
+  return {
+    setManifest(manifest) {
+      lazyCompilationPrewarmController?.setManifest(manifest);
+    },
+  };
+};