rsbuild-plugin-react-router 0.1.1 → 0.3.0

package/src/route-watch.ts

@@ -0,0 +1,322 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
+import type { RsbuildConfig } from '@rsbuild/core';
+import { dirname, resolve } from 'pathe';
+import type { Route } from './types.js';
+
+const ROUTE_RESTART_MARKER_ASSET = '.react-router/route-watch';
+const INITIAL_RESTART_MARKER_CONTENT = 'react-router-route-watch';
+
+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 = async (
+  watchDirectory: string
+): Promise<Set<string>> => {
+  const directories = new Set<string>();
+
+  const walkDirectory = async (directory: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    directories.add(directory);
+    await Promise.all(
+      entries.map(async entry => {
+        const entryPath = resolve(directory, entry.name);
+        if (entry.isDirectory()) {
+          await walkDirectory(entryPath);
+        }
+      })
+    );
+  };
+
+  await walkDirectory(watchDirectory);
+  return 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 rescanTimer: ReturnType<typeof setTimeout> | undefined;
+  let rescanQueue = Promise.resolve();
+  const directoryWatchers = new Map<string, DirectoryWatcher>();
+
+  const touchRestartMarker = async (): Promise<void> => {
+    await mkdir(dirname(restartMarkerPath), { recursive: true });
+    await 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, scheduleRescan, 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 applyNextState = async (nextState: RouteDirectoryState) => {
+    if (closed) {
+      return;
+    }
+    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;
+        try {
+          void Promise.resolve(onRouteTopologyChange()).catch(onError);
+        } catch (error) {
+          onError(error);
+        }
+        return;
+      } else {
+        await touchRestartMarker();
+      }
+      if (closed) {
+        return;
+      }
+      state = nextState;
+      return;
+    }
+    state = nextState;
+  };
+
+  const runRescan = async (): Promise<void> => {
+    if (closed) {
+      return;
+    }
+    let nextDirectories: Set<string> | undefined;
+    try {
+      nextDirectories = await readRouteDirectories(watchDirectory);
+      if (closed) {
+        return;
+      }
+      const nextState = {
+        directories: nextDirectories,
+        routeTopology: await getRouteTopology(),
+      };
+      if (closed) {
+        return;
+      }
+      await applyNextState(nextState);
+    } catch (error) {
+      if (nextDirectories && !closed) {
+        syncDirectoryWatchers(nextDirectories);
+      }
+      onError(error);
+    }
+  };
+
+  const rescan = (): Promise<void> => {
+    rescanQueue = rescanQueue.then(runRescan, runRescan);
+    return rescanQueue;
+  };
+
+  const scheduleRescan = (): void => {
+    if (rescanTimer) {
+      clearTimeout(rescanTimer);
+    }
+    rescanTimer = setTimeout(() => {
+      rescanTimer = undefined;
+      void rescan();
+    }, 100);
+  };
+
+  try {
+    await applyNextState(discoveredState);
+  } catch (error) {
+    onError(error);
+  }
+
+  return async () => {
+    if (closed) {
+      await rescanQueue;
+      return;
+    }
+    closed = true;
+    if (rescanTimer) {
+      clearTimeout(rescanTimer);
+    }
+    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-utils.ts

@@ -0,0 +1,210 @@
+import { resolve } from 'pathe';
+import type { ServerBuild } from 'react-router';
+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);
+}
+
+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 (
+    isRecord(value) &&
+    (value.mode === 'initial' ||
+      (value.mode === 'lazy' &&
+        (value.manifestPath === undefined ||
+          typeof value.manifestPath === 'string')))
+  );
+}
+
+async function resolveBuildExports(
+  build: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  const resolved = { ...build };
+  for (const key of Object.keys(build)) {
+    if (!RESOLVABLE_BUILD_EXPORTS.has(key)) {
+      continue;
+    }
+    const value = build[key];
+    if (typeof value === 'function' && value.length === 0) {
+      const result = value();
+      resolved[key] = isPromiseLike(result) ? await result : result;
+      continue;
+    }
+    if (isPromiseLike(value)) {
+      resolved[key] = await value;
+    }
+  }
+  return 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'
+  );
+}
+
+async function resolveServerBuildCandidate(
+  candidate: unknown
+): Promise<ServerBuild | undefined> {
+  if (!isRecord(candidate)) {
+    return undefined;
+  }
+  const resolved = await resolveBuildExports(candidate);
+  return isServerBuild(resolved) ? resolved : undefined;
+}
+
+export async function resolveServerBuildModule(
+  buildModule: unknown,
+  source: string
+): Promise<ServerBuild> {
+  const moduleValue = await 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 = await getCandidate();
+    const serverBuild = await resolveServerBuildCandidate(candidate);
+    if (serverBuild) {
+      return serverBuild;
+    }
+  }
+  throw new Error(
+    `[rsbuild-plugin-react-router] ${source} did not contain a valid React Router ServerBuild.`
+  );
+}
+
+export function resolveReactRouterServerBuild(
+  buildModule: unknown
+): Promise<ServerBuild> {
+  return resolveServerBuildModule(buildModule, 'Imported module');
+}
+
+export { generateServerBuild };

package/src/ssr-externals.ts

@@ -0,0 +1,59 @@
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { sep } from 'node:path';
+
+const REACT_ROUTER_EXTERNALS = [
+  'react-router',
+  'react-router-dom',
+  '@react-router/architect',
+  '@react-router/cloudflare',
+  '@react-router/dev',
+  '@react-router/express',
+  '@react-router/node',
+  '@react-router/serve',
+];
+
+const requireFromHere = createRequire(import.meta.url);
+
+function resolvePackageJson(
+  name: string,
+  rootDirectory: string
+): string | null {
+  try {
+    return requireFromHere.resolve(`${name}/package.json`, {
+      paths: [rootDirectory],
+    });
+  } catch {
+    return null;
+  }
+}
+
+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) {
+    const resolved = resolvePackageJson(name, rootDirectory);
+    if (!resolved) {
+      continue;
+    }
+
+    const realPath = safeRealpath(resolved);
+    if (!isPathInNodeModules(realPath)) {
+      externals.push(name);
+    }
+  }
+
+  return externals;
+}

package/src/templates/context.ts

@@ -0,0 +1,12 @@
+import { createContext } from 'react';
+import type { Context } from 'react';
+
+export interface Assets {
+  scriptTags: string[];
+  styleTags: string[];
+}
+
+export const AssetsContext: Context<Assets> = createContext<Assets>({
+  scriptTags: [],
+  styleTags: [],
+});

package/src/templates/entry.client.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { HydratedRouter } from 'react-router/dom';
+
+React.startTransition(() => {
+  hydrateRoot(
+    document,
+    <React.StrictMode>
+      <HydratedRouter />
+    </React.StrictMode>
+  );
+});