rsbuild-plugin-react-router 0.2.0 → 0.3.1

package/src/route-watch.ts

@@ -0,0 +1,357 @@
+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 { dirname, resolve } from 'pathe';
+import { getCappedPluginConcurrency } from './concurrency.js';
+import {
+  createDelayedPluginTask,
+  runPluginEffect,
+  tryPluginPromise,
+} from './effect-runtime.js';
+import type { Route } from './types.js';
+
+const ROUTE_RESTART_MARKER_ASSET = '.react-router/route-watch';
+const INITIAL_RESTART_MARKER_CONTENT = 'react-router-route-watch';
+const ROUTE_TOPOLOGY_RESCAN_DEBOUNCE_MS = 100;
+const ROUTE_DIRECTORY_SCAN_CONCURRENCY = getCappedPluginConcurrency();
+
+type RouteManifestSnapshotEntry = Pick<
+  Route,
+  'caseSensitive' | 'file' | 'id' | 'index' | 'parentId' | 'path'
+>;
+type RouteManifestSnapshotEntryPair = readonly [
+  string,
+  RouteManifestSnapshotEntry,
+];
+type RouteManifestSnapshotEntries =
+  | Record<string, RouteManifestSnapshotEntry>
+  | ReadonlyArray<RouteManifestSnapshotEntryPair>;
+
+type WatchFilesConfig = NonNullable<
+  NonNullable<RsbuildConfig['dev']>['watchFiles']
+>;
+export type WatchFileConfig =
+  | Exclude<WatchFilesConfig, readonly unknown[]>
+  | Extract<WatchFilesConfig, readonly unknown[]>[number];
+
+type RouteDirectoryState = {
+  directories: Set<string>;
+  routeTopology: Set<string>;
+};
+
+type DirectoryWatcher = Pick<FSWatcher, 'close'>;
+type WatchDirectoryEntry = (
+  directory: string,
+  onChange: () => void,
+  onError: (error: unknown) => void
+) => DirectoryWatcher;
+
+const defaultWatchDirectoryEntry: WatchDirectoryEntry = (
+  directory,
+  onChange,
+  onError
+) => {
+  const watcher = watch(directory, onChange);
+  watcher.on('error', onError);
+  return watcher;
+};
+
+export const mergeWatchFiles = (
+  existing: WatchFilesConfig | undefined,
+  additions: WatchFileConfig[]
+): WatchFilesConfig => {
+  if (!existing) {
+    return additions as WatchFilesConfig;
+  }
+  return [
+    ...(Array.isArray(existing) ? existing : [existing]),
+    ...additions,
+  ] as WatchFilesConfig;
+};
+
+export const getRouteRestartMarkerPath = (outputClientPath: string): string =>
+  resolve(outputClientPath, ROUTE_RESTART_MARKER_ASSET);
+
+export const createRouteManifestSnapshot = (
+  routes: RouteManifestSnapshotEntries
+): Set<string> =>
+  new Set(
+    (Array.isArray(routes) ? routes : Object.entries(routes))
+      // React Router uses sibling declaration order as a match tiebreaker, so
+      // callers that have ordered route config should pass ordered entries
+      // instead of a record with numeric-like keys.
+      .map(([routeId, route], order) =>
+        JSON.stringify([
+          order,
+          routeId,
+          route.id,
+          route.parentId ?? null,
+          route.path ?? null,
+          route.index ?? null,
+          route.caseSensitive ?? null,
+          route.file,
+        ])
+      )
+  );
+
+export const ensureDevRestartMarker = async (
+  restartMarkerPath: string
+): Promise<void> => {
+  // Dev owns this watched file directly so ordinary rebuilds do not rewrite it
+  // and trigger reload loops.
+  await mkdir(dirname(restartMarkerPath), { recursive: true });
+  try {
+    await access(restartMarkerPath);
+  } catch {
+    await writeFile(restartMarkerPath, INITIAL_RESTART_MARKER_CONTENT);
+  }
+};
+
+const areSetsEqual = <T>(left: Set<T>, right: Set<T>): boolean => {
+  if (left.size !== right.size) {
+    return false;
+  }
+  for (const value of left) {
+    if (!right.has(value)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const readRouteDirectories = (watchDirectory: string): Promise<Set<string>> => {
+  return runPluginEffect(readRouteDirectoriesEffect(watchDirectory));
+};
+
+const readRouteDirectoriesEffect = (
+  watchDirectory: string
+): Effect.Effect<Set<string>, Error, never> => {
+  const directories = new Set<string>();
+  const walkDirectory = (directory: string): Effect.Effect<void> =>
+    tryPluginPromise(() => readdir(directory, { withFileTypes: true })).pipe(
+      Effect.catchAll(() => Effect.succeed([])),
+      Effect.map(entries => {
+        directories.add(directory);
+        return entries
+          .filter(entry => entry.isDirectory())
+          .map(entry => resolve(directory, entry.name));
+      }),
+      Effect.flatMap(childDirectories =>
+        Effect.forEach(childDirectories, walkDirectory, {
+          concurrency: ROUTE_DIRECTORY_SCAN_CONCURRENCY,
+          discard: true,
+        })
+      )
+    );
+
+  return walkDirectory(watchDirectory).pipe(Effect.as(directories));
+};
+
+export const createRouteTopologyWatcher = async ({
+  watchDirectory,
+  getRouteTopology,
+  initialRouteTopology,
+  restartMarkerPath,
+  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 = {
+      directories: discoveredDirectories,
+      routeTopology: await getRouteTopology(),
+    };
+  } catch (error) {
+    if (!initialRouteTopology) {
+      throw error;
+    }
+    onError(error);
+    discoveredState = {
+      directories: discoveredDirectories,
+      routeTopology: initialRouteTopology,
+    };
+  }
+  let state = {
+    ...discoveredState,
+    routeTopology: initialRouteTopology ?? discoveredState.routeTopology,
+  };
+  let closed = false;
+  let rescanQueue = Promise.resolve();
+  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 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 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);
+            }
+          });
+        }
+        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);
+          }
+          onError(error);
+        })
+      )
+    );
+  };
+
+  const rescan = (): Promise<void> => {
+    rescanQueue = rescanQueue.then(
+      () => runPluginEffect(runRescanEffect()),
+      () => runPluginEffect(runRescanEffect())
+    );
+    return rescanQueue;
+  };
+
+  const rescanTask = createDelayedPluginTask({
+    delayMs: ROUTE_TOPOLOGY_RESCAN_DEBOUNCE_MS,
+    run: () =>
+      Effect.suspend(() =>
+        closed ? Effect.void : tryPluginPromise(rescan).pipe(Effect.asVoid)
+      ),
+    onError,
+  });
+
+  const cancelScheduledRescan = (): Promise<void> =>
+    runPluginEffect(rescanTask.cancelEffect());
+
+  const applyNextState = async (nextState: RouteDirectoryState) => {
+    await runPluginEffect(applyNextStateEffect(nextState));
+  };
+
+  try {
+    await applyNextState(discoveredState);
+  } catch (error) {
+    onError(error);
+  }
+
+  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();
+  };
+};

package/src/server-build-plan.ts

@@ -0,0 +1,91 @@
+import { PLUGIN_NAME } from './constants.js';
+import type { ReactRouterDevBuildPlan } from './dev-runtime-artifacts.js';
+import type { Route } from './types.js';
+
+export type ReactRouterServerBundleEntry = {
+  bundleId: string;
+  entryName: string;
+};
+
+export type ReactRouterServerBuildPlan = ReactRouterDevBuildPlan & {
+  serverBundleEntries: ReactRouterServerBundleEntry[];
+};
+
+export const createReactRouterServerBuildPlan = ({
+  routesByServerBundleId,
+  serverBuildFile,
+  defaultEntryName,
+}: {
+  routesByServerBundleId: Record<string, Record<string, Route>>;
+  serverBuildFile: string | undefined;
+  defaultEntryName: string;
+}): ReactRouterServerBuildPlan => {
+  const serverBuildFileBase = (serverBuildFile || 'index.js').replace(
+    /\.js$/,
+    ''
+  );
+  const serverBundleEntries = Object.entries(routesByServerBundleId)
+    .filter(([, bundleRoutes]) =>
+      Boolean(bundleRoutes && Object.keys(bundleRoutes).length > 0)
+    )
+    .map(([bundleId]) => ({
+      bundleId,
+      entryName: `${bundleId}/${serverBuildFileBase}`,
+    }));
+
+  const reservedNodeEntryNames = new Set([
+    'static/js/app',
+    'static/js/entry.server',
+    defaultEntryName,
+  ]);
+  for (const { entryName } of serverBundleEntries) {
+    if (reservedNodeEntryNames.has(entryName)) {
+      throw new Error(
+        `[${PLUGIN_NAME}] Server bundle entry ${JSON.stringify(entryName)} conflicts with a reserved node entry.`
+      );
+    }
+    reservedNodeEntryNames.add(entryName);
+  }
+
+  return {
+    defaultEntryName,
+    entryNames: [
+      defaultEntryName,
+      ...serverBundleEntries.map(({ entryName }) => entryName),
+    ],
+    serverBundleEntries,
+  };
+};
+
+export const createReactRouterNodeEntries = ({
+  hasServerApp,
+  isBuild,
+  serverAppPath,
+  entryServerPath,
+  defaultEntryName,
+  serverBundleEntries,
+}: {
+  hasServerApp: boolean;
+  isBuild: boolean;
+  serverAppPath: string;
+  entryServerPath: string;
+  defaultEntryName: string;
+  serverBundleEntries: readonly ReactRouterServerBundleEntry[];
+}): Record<string, string> => {
+  const entries: Record<string, string> = {
+    'static/js/app': hasServerApp
+      ? serverAppPath
+      : 'virtual/react-router/server-build',
+    'static/js/entry.server': entryServerPath,
+  };
+
+  if (hasServerApp && !isBuild) {
+    entries[defaultEntryName] = 'virtual/react-router/server-build';
+  }
+
+  for (const { bundleId, entryName } of serverBundleEntries) {
+    entries[entryName] = `virtual/react-router/server-build-${bundleId}`;
+  }
+
+  return entries;
+};

package/src/server-build-resolution.ts

@@ -0,0 +1,131 @@
+// Internal module: exposes the Effect-based ServerBuild resolution used by
+// dev-runtime code. Not re-exported from the package entry so the public
+// declaration graph stays free of `effect` types; external callers go through
+// the Promise wrappers in server-utils.ts.
+import * as Effect from 'effect/Effect';
+import type { ServerBuild } from 'react-router';
+import { tryPluginPromise, tryPluginSync } from './effect-runtime.js';
+
+const RESOLVABLE_BUILD_EXPORTS = new Set([
+  'allowedActionOrigins',
+  'assets',
+  'assetsBuildDirectory',
+  'basename',
+  'entry',
+  'future',
+  'isSpaMode',
+  'prerender',
+  'publicPath',
+  'routeDiscovery',
+  'routes',
+  'ssr',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return isRecord(value) && typeof value.then === 'function';
+}
+
+function isRouteDiscovery(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (isRecord(value) &&
+      (value.mode === 'initial' ||
+        (value.mode === 'lazy' &&
+          (value.manifestPath === undefined ||
+            typeof value.manifestPath === 'string'))))
+  );
+}
+
+function resolveBuildExportsEffect(
+  build: Record<string, unknown>
+): Effect.Effect<Record<string, unknown>, Error, never> {
+  const resolved = { ...build };
+  return Effect.forEach(
+    Object.keys(build),
+    key =>
+      Effect.gen(function* () {
+        if (!RESOLVABLE_BUILD_EXPORTS.has(key)) {
+          return;
+        }
+        const value = build[key];
+        if (typeof value === 'function' && value.length === 0) {
+          const result = yield* tryPluginSync(() => value());
+          resolved[key] = isPromiseLike(result)
+            ? yield* tryPluginPromise(() => result)
+            : result;
+          return;
+        }
+        if (isPromiseLike(value)) {
+          resolved[key] = yield* tryPluginPromise(() => value);
+        }
+      }),
+    { discard: true }
+  ).pipe(Effect.as(resolved));
+}
+
+function isServerBuild(value: unknown): value is ServerBuild {
+  return Boolean(
+    isRecord(value) &&
+    isRecord(value.entry) &&
+    isRecord(value.entry.module) &&
+    typeof value.entry.module.default === 'function' &&
+    isRecord(value.routes) &&
+    isRecord(value.assets) &&
+    typeof value.assetsBuildDirectory === 'string' &&
+    (value.basename === undefined || typeof value.basename === 'string') &&
+    isRecord(value.future) &&
+    typeof value.isSpaMode === 'boolean' &&
+    Array.isArray(value.prerender) &&
+    typeof value.publicPath === 'string' &&
+    isRouteDiscovery(value.routeDiscovery) &&
+    typeof value.ssr === 'boolean'
+  );
+}
+
+function resolveServerBuildCandidateEffect(
+  candidate: unknown
+): Effect.Effect<ServerBuild | undefined, Error, never> {
+  if (!isRecord(candidate)) {
+    return Effect.succeed(undefined);
+  }
+  return resolveBuildExportsEffect(candidate).pipe(
+    Effect.map(resolved => (isServerBuild(resolved) ? resolved : undefined))
+  );
+}
+
+export function resolveServerBuildModuleEffect(
+  buildModule: unknown,
+  source: string
+): Effect.Effect<ServerBuild, Error, never> {
+  return Effect.gen(function* () {
+    const moduleValue = isPromiseLike(buildModule)
+      ? yield* tryPluginPromise(() => buildModule)
+      : buildModule;
+    const candidates = [() => moduleValue];
+    if (isRecord(moduleValue)) {
+      if ('default' in moduleValue) {
+        candidates.push(() => moduleValue.default);
+      }
+      if ('module.exports' in moduleValue) {
+        candidates.push(() => moduleValue['module.exports']);
+      }
+    }
+
+    for (const getCandidate of candidates) {
+      const candidate = yield* tryPluginPromise(() => getCandidate());
+      const serverBuild = yield* resolveServerBuildCandidateEffect(candidate);
+      if (serverBuild) {
+        return serverBuild;
+      }
+    }
+    return yield* Effect.fail(
+      new Error(
+        `[rsbuild-plugin-react-router] ${source} did not contain a valid React Router ServerBuild.`
+      )
+    );
+  });
+}

package/src/server-utils.ts

@@ -0,0 +1,111 @@
+import { resolve } from 'pathe';
+import type { ServerBuild } from 'react-router';
+import { runPluginEffect } from './effect-runtime.js';
+import { resolveServerBuildModuleEffect } from './server-build-resolution.js';
+import type { Route } from './types.js';
+
+/**
+ * Generates the server build template string.
+ *
+ * Note: Federation mode used to require async `import()` wrappers for entrypoints.
+ * With Rspack/@module-federation support for `experiments.asyncStartup`, the
+ * server build can always use static imports.
+ */
+interface ServerBuildOptions {
+  entryServerPath: string;
+  assetsBuildDirectory: string;
+  basename: string;
+  appDirectory: string;
+  ssr: boolean;
+  future?: unknown;
+  allowedActionOrigins?: string[];
+  prerender?: string[];
+  publicPath?: string;
+  serverManifestId?: string;
+  routeDiscovery:
+    | {
+        mode: 'lazy';
+        manifestPath?: string;
+      }
+    | {
+        mode: 'initial';
+      }
+    | undefined;
+}
+
+function generateStaticTemplate(
+  routes: Record<string, Route>,
+  options: ServerBuildOptions
+): string {
+  const manifestId =
+    options.serverManifestId ?? 'virtual/react-router/server-manifest';
+  return `
+    import * as entryServer from ${JSON.stringify(options.entryServerPath)};
+    ${Object.keys(routes)
+      .map((key, index) => {
+        const route = routes[key];
+        return `import * as route${index} from ${JSON.stringify(
+          `${resolve(options.appDirectory, route.file)}?react-router-route`
+        )};`;
+      })
+      .join('\n')}
+        
+    export { default as assets } from ${JSON.stringify(manifestId)};
+    export const assetsBuildDirectory = ${JSON.stringify(
+      options.assetsBuildDirectory
+    )};
+    export const basename = ${JSON.stringify(options.basename)};
+    export const future = ${JSON.stringify(options.future ?? {})};
+    export const isSpaMode = ${!options.ssr};
+    export const ssr = ${options.ssr};
+    export const routeDiscovery = ${JSON.stringify(options.routeDiscovery)};
+    export const prerender = ${JSON.stringify(options.prerender ?? [])};
+    export const publicPath = ${JSON.stringify(options.publicPath ?? '/')};
+    export const entry = { module: entryServer };
+    export const allowedActionOrigins = ${JSON.stringify(options.allowedActionOrigins)};
+    export var routes = {};
+    ${Object.keys(routes)
+      .map((key, index) => {
+        const route = routes[key];
+        return `routes[${JSON.stringify(key)}] = {
+          id: ${JSON.stringify(route.id)},
+          parentId: ${JSON.stringify(route.parentId)},
+          path: ${JSON.stringify(route.path)},
+          index: ${JSON.stringify(route.index)},
+          caseSensitive: ${JSON.stringify(route.caseSensitive)},
+          module: route${index}
+        };`;
+      })
+      .join('\n    ')}
+  `;
+}
+
+/**
+ * Generates the server build module content
+ * @param routes The route manifest
+ * @param options Build options
+ * @returns The generated module content as a string
+ */
+function generateServerBuild(
+  routes: Record<string, Route>,
+  options: ServerBuildOptions & { federation?: boolean }
+): string {
+  return generateStaticTemplate(routes, options);
+}
+
+export function resolveServerBuildModule(
+  buildModule: unknown,
+  source: string
+): Promise<ServerBuild> {
+  return runPluginEffect(resolveServerBuildModuleEffect(buildModule, source));
+}
+
+export function resolveReactRouterServerBuild(
+  buildModule: unknown
+): Promise<ServerBuild> {
+  return runPluginEffect(
+    resolveServerBuildModuleEffect(buildModule, 'Imported module')
+  );
+}
+
+export { generateServerBuild };