rsbuild-plugin-react-router 0.5.0 → 0.6.0

package/src/rsc-runtime.d.ts

@@ -0,0 +1,143 @@
+interface ImportMeta {
+  webpackHot?: {
+    accept(): void;
+    on(event: string, handler: () => void): void;
+  };
+}
+
+declare module 'react-server-dom-rspack/client.browser' {
+  export function createFromReadableStream<T>(
+    stream: ReadableStream<Uint8Array>,
+    options?: { temporaryReferences?: unknown }
+  ): Promise<T>;
+
+  export function createTemporaryReferenceSet(): unknown;
+
+  export function encodeReply(
+    value: unknown,
+    options?: { temporaryReferences?: unknown }
+  ): Promise<BodyInit>;
+
+  export function setServerCallback(
+    fn: (id: string, args: unknown[]) => Promise<unknown>
+  ): void;
+}
+
+declare module 'react-server-dom-rspack/client.node' {
+  export * from 'react-server-dom-rspack/client.browser';
+}
+
+declare module 'react-server-dom-rspack/server.node' {
+  import type { ReactFormState } from 'react-dom/client';
+
+  export function createTemporaryReferenceSet(): unknown;
+
+  export function decodeAction(
+    body: FormData,
+    serverManifest?: unknown
+  ): Promise<() => Promise<unknown>>;
+
+  export function decodeFormState(
+    actionResult: unknown,
+    body: FormData,
+    serverManifest?: unknown
+  ): Promise<ReactFormState | null>;
+
+  export function decodeReply(
+    body: FormData | string,
+    options?: { temporaryReferences?: unknown }
+  ): Promise<unknown[]>;
+
+  export function loadServerAction(
+    actionId: string
+  ): (...args: unknown[]) => unknown;
+
+  export function renderToReadableStream(
+    model: unknown,
+    options?: {
+      onError?: (error: unknown) => string | undefined;
+      temporaryReferences?: unknown;
+    }
+  ): ReadableStream<Uint8Array>;
+}
+
+declare module 'virtual/react-router/unstable_rsc/routes' {
+  import type { unstable_RSCRouteConfig as RSCRouteConfig } from 'react-router';
+  const routes: RSCRouteConfig;
+  export default routes;
+}
+
+declare module 'virtual/react-router/unstable_rsc/route-discovery' {
+  const routeDiscovery:
+    | { mode: 'initial' }
+    | { mode: 'lazy'; manifestPath?: string };
+  export default routeDiscovery;
+}
+
+declare module 'virtual/react-router/unstable_rsc/basename' {
+  const basename: string;
+  export default basename;
+}
+
+declare module 'virtual/react-router/unstable_rsc/allowed-action-origins' {
+  const allowedActionOrigins: string[] | undefined;
+  export default allowedActionOrigins;
+}
+
+declare module 'virtual/react-router/unstable_rsc/client-version' {
+  const clientVersion: string | undefined;
+  export default clientVersion;
+}
+
+declare module 'virtual/react-router/unstable_rsc/react-router-serve-config' {
+  const config: {
+    assetsBuildDirectory: string;
+    publicPath: string;
+  };
+  export default config;
+}
+
+declare module 'virtual/react-router/unstable_rsc/inject-hmr-runtime' {}
+
+declare module 'virtual/react-router/unstable_rsc/bootstrap-scripts' {
+  const bootstrapScripts: string[];
+  export default bootstrapScripts;
+}
+
+declare module 'virtual/react-router/unstable_rsc/server-manifest' {
+  export default function getServerManifest(): unknown;
+}
+
+declare module 'virtual:react-router/unstable_rsc/routes' {
+  export { default } from 'virtual/react-router/unstable_rsc/routes';
+}
+
+declare module 'virtual:react-router/unstable_rsc/route-discovery' {
+  export { default } from 'virtual/react-router/unstable_rsc/route-discovery';
+}
+
+declare module 'virtual:react-router/unstable_rsc/basename' {
+  export { default } from 'virtual/react-router/unstable_rsc/basename';
+}
+
+declare module 'virtual:react-router/unstable_rsc/allowed-action-origins' {
+  export { default } from 'virtual/react-router/unstable_rsc/allowed-action-origins';
+}
+
+declare module 'virtual:react-router/unstable_rsc/client-version' {
+  export { default } from 'virtual/react-router/unstable_rsc/client-version';
+}
+
+declare module 'virtual:react-router/unstable_rsc/react-router-serve-config' {
+  export { default } from 'virtual/react-router/unstable_rsc/react-router-serve-config';
+}
+
+declare module 'virtual:react-router/unstable_rsc/inject-hmr-runtime' {}
+
+declare module 'virtual:react-router/unstable_rsc/bootstrap-scripts' {
+  export { default } from 'virtual/react-router/unstable_rsc/bootstrap-scripts';
+}
+
+declare module 'virtual:react-router/unstable_rsc/server-manifest' {
+  export { default } from 'virtual/react-router/unstable_rsc/server-manifest';
+}

package/src/rsc-support.ts

@@ -0,0 +1,116 @@
+import type { RsbuildPlugin } from '@rsbuild/core';
+import { getPackageVersion, parseVersionMajorMinor } from './plugin-utils.js';
+import type { Config } from './react-router-config.js';
+import type { PluginOptions } from './types.js';
+
+type RscPluginOptions = Exclude<NonNullable<PluginOptions['rsc']>, boolean>;
+type RscUnsupportedConfig = Pick<
+  Config,
+  'buildEnd' | 'future' | 'presets' | 'serverBundles' | 'subResourceIntegrity'
+>;
+
+// Mirrors upstream @react-router/dev's RSC-mode validateConfig: these
+// options have no effect in RSC framework mode, so reject them loudly
+// instead of silently dropping them.
+export const assertReactRouterRscConfigSupport = ({
+  pluginName,
+  userConfig,
+}: {
+  pluginName: string;
+  userConfig: RscUnsupportedConfig;
+}): void => {
+  const unsupported: string[] = [];
+  if (userConfig.buildEnd) unsupported.push('buildEnd');
+  if (userConfig.presets?.length) unsupported.push('presets');
+  if (userConfig.serverBundles) unsupported.push('serverBundles');
+  if (userConfig.subResourceIntegrity) unsupported.push('subResourceIntegrity');
+  if (unsupported.length) {
+    throw new Error(
+      `[${pluginName}] RSC Framework Mode does not currently support the ` +
+        `following React Router config:\n${unsupported
+          .map(option => ` - ${option}`)
+          .join('\n')}\n`
+    );
+  }
+};
+
+const supportsReactRouterRsc = (version: string | undefined): boolean => {
+  const parsed = parseVersionMajorMinor(version);
+  if (!parsed) {
+    return false;
+  }
+  return parsed.major >= 8 || (parsed.major === 7 && parsed.minor >= 18);
+};
+
+export const assertReactRouterRscSupport = ({
+  pluginName,
+  resolvePackagePath,
+}: {
+  pluginName: string;
+  resolvePackagePath: (specifier: string) => string | undefined;
+}): void => {
+  const reactRouterVersion = getPackageVersion(
+    'react-router',
+    resolvePackagePath
+  );
+  if (!supportsReactRouterRsc(reactRouterVersion)) {
+    throw new Error(
+      `[${pluginName}] React Router RSC mode requires react-router >=7.18.0 or >=8.0.0.`
+    );
+  }
+
+  for (const specifier of [
+    'react-server-dom-rspack/client.browser',
+    'rsbuild-plugin-rsc',
+  ]) {
+    if (!resolvePackagePath(specifier)) {
+      throw new Error(
+        `[${pluginName}] React Router RSC mode requires \`${specifier}\` to be installed.`
+      );
+    }
+  }
+};
+
+export const setupReactRouterRscPlugin = async ({
+  api,
+  entryRscPath,
+  entrySsrPath,
+  pluginName,
+  rsc,
+}: {
+  api: Parameters<RsbuildPlugin['setup']>[0];
+  entryRscPath: string;
+  entrySsrPath: string;
+  pluginName: string;
+  rsc: RscPluginOptions;
+}): Promise<void> => {
+  const { PLUGIN_RSC_NAME } = await import('rsbuild-plugin-rsc');
+  if (api.isPluginExists(PLUGIN_RSC_NAME)) {
+    throw new Error(
+      `[${pluginName}] The "${PLUGIN_RSC_NAME}" plugin is already registered. ` +
+        `Remove the separately configured plugin and pass RSC options through ` +
+        `"${pluginName}" so the managed node/web environments stay aligned.`
+    );
+  }
+
+  const { pluginRSC } = await import('rsbuild-plugin-rsc');
+  await pluginRSC({
+    ...rsc,
+    environments: {
+      server: 'node',
+      client: 'web',
+    },
+    layers: {
+      rsc: [entryRscPath],
+      ssr: [entrySsrPath],
+      ...rsc.layers,
+    },
+  }).setup(api);
+};
+
+export { createReactRouterRscDevServerSetup } from './rsc-dev-server.js';
+export { registerReactRouterRscRouteTransforms } from './rsc-route-transform-registration.js';
+export {
+  createReactRouterRscResolveAliases,
+  createReactRouterRscVirtualModules,
+} from './rsc-virtual-modules.js';

package/src/rsc-virtual-modules.ts

@@ -0,0 +1,113 @@
+import { relative, resolve } from 'pathe';
+import type { Config } from './react-router-config.js';
+import type { Route } from './types.js';
+import { combineURLs, normalizeAssetPrefix } from './plugin-utils.js';
+import { getVirtualModuleFilePath } from './virtual-modules.js';
+import {
+  createRscInternalClientModule,
+  createRscRouteConfig,
+} from './rsc-route-config.js';
+
+const defaultExport = (value: unknown): string =>
+  `export default ${JSON.stringify(value)};`;
+
+const RSC_VIRTUAL_ALIAS_IDS = [
+  'routes',
+  'route-discovery',
+  'inject-hmr-runtime',
+  'basename',
+  'allowed-action-origins',
+  'client-version',
+  'react-router-serve-config',
+  'bootstrap-scripts',
+  'server-manifest',
+] as const;
+
+type RscVirtualModulesOptions = {
+  allowedActionOrigins: string[] | undefined;
+  appDirectory: string;
+  basename: string;
+  buildDirectory: string;
+  isBuild: boolean;
+  /** Resolved web `output.distPath.js` segment, e.g. `static/js`. */
+  jsDistPath: string;
+  outputClientPath: string;
+  publicPath: string;
+  routeDiscovery: Config['routeDiscovery'];
+  routes: Record<string, Route>;
+  ssr: boolean;
+};
+
+export const createReactRouterRscResolveAliases = (
+  rootPath: string
+): Record<string, string> => ({
+  ...Object.fromEntries(
+    RSC_VIRTUAL_ALIAS_IDS.flatMap(id => {
+      const moduleId = `virtual/react-router/unstable_rsc/${id}`;
+      const modulePath = resolve(rootPath, getVirtualModuleFilePath(moduleId));
+      return [
+        [`virtual:react-router/unstable_rsc/${id}`, modulePath],
+        [moduleId, modulePath],
+      ];
+    })
+  ),
+  'react-router/internal/react-server-client': resolve(
+    rootPath,
+    getVirtualModuleFilePath('virtual/react-router/rsc-internal-client')
+  ),
+});
+
+export const createReactRouterRscVirtualModules = ({
+  allowedActionOrigins,
+  appDirectory,
+  basename,
+  buildDirectory,
+  isBuild,
+  jsDistPath,
+  outputClientPath,
+  publicPath,
+  routeDiscovery,
+  routes,
+  ssr,
+}: RscVirtualModulesOptions): Record<string, string> => {
+  const rscAssetsBuildDirectory = relative(
+    resolve(buildDirectory, 'server'),
+    outputClientPath
+  );
+  const bootstrapPublicPath = normalizeAssetPrefix(publicPath);
+
+  return {
+    'virtual/react-router/unstable_rsc/routes': createRscRouteConfig({
+      appDirectory,
+      routes,
+    }),
+    'virtual/react-router/unstable_rsc/route-discovery': defaultExport(
+      ssr === false ? { mode: 'initial' } : (routeDiscovery ?? { mode: 'lazy' })
+    ),
+    'virtual/react-router/unstable_rsc/inject-hmr-runtime': !isBuild
+      ? `if (import.meta.webpackHot) {
+  // The RSC client entry owns update navigation; this boundary only self-accepts.
+  import.meta.webpackHot.accept();
+}`
+      : '',
+    'virtual/react-router/unstable_rsc/basename': defaultExport(basename),
+    'virtual/react-router/unstable_rsc/allowed-action-origins':
+      defaultExport(allowedActionOrigins),
+    'virtual/react-router/unstable_rsc/client-version': isBuild
+      ? 'export default __webpack_hash__;'
+      : 'export default undefined;',
+    'virtual/react-router/unstable_rsc/react-router-serve-config':
+      defaultExport({
+        assetsBuildDirectory: rscAssetsBuildDirectory,
+        publicPath,
+      }),
+    'virtual/react-router/unstable_rsc/bootstrap-scripts': defaultExport([
+      combineURLs(bootstrapPublicPath, `${jsDistPath}/index.js`),
+    ]),
+    'virtual/react-router/unstable_rsc/server-manifest': `export default function getServerManifest() {
+  return __webpack_require__.rscM?.serverManifest;
+}
+`,
+    'virtual/react-router/rsc-internal-client': createRscInternalClientModule(),
+  };
+};

package/src/server-build-plan.ts

@@ -62,6 +62,7 @@ export const createReactRouterNodeEntries = ({
   isBuild,
   serverAppPath,
   entryServerPath,
+  serverBuildFile,
   defaultEntryName,
   serverBundleEntries,
 }: {
@@ -69,16 +70,26 @@ export const createReactRouterNodeEntries = ({
   isBuild: boolean;
   serverAppPath: string;
   entryServerPath: string;
+  serverBuildFile: string | undefined;
   defaultEntryName: string;
   serverBundleEntries: readonly ReactRouterServerBundleEntry[];
 }): Record<string, string> => {
+  const appEntry = hasServerApp
+    ? serverAppPath
+    : 'virtual/react-router/server-build';
   const entries: Record<string, string> = {
-    'static/js/app': hasServerApp
-      ? serverAppPath
-      : 'virtual/react-router/server-build',
+    'static/js/app': appEntry,
     'static/js/entry.server': entryServerPath,
   };
 
+  if (isBuild) {
+    const configuredEntryName = (serverBuildFile || 'index.js').replace(
+      /\.js$/,
+      ''
+    );
+    entries[configuredEntryName] = appEntry;
+  }
+
   if (hasServerApp && !isBuild) {
     entries[defaultEntryName] = 'virtual/react-router/server-build';
   }

package/src/server-build-resolution.ts

@@ -1,10 +1,7 @@
-// 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';
+// Internal module: exposes ServerBuild resolution used by dev-runtime code.
+// External callers go through the Promise wrappers in server-utils.ts.
 import type { ServerBuild } from 'react-router';
-import { tryPluginPromise, tryPluginSync } from './effect-runtime.js';
+import { normalizeEffectError } from './effect-runtime.js';
 
 const RESOLVABLE_BUILD_EXPORTS = new Set([
   'allowedActionOrigins',
@@ -40,31 +37,25 @@ function isRouteDiscovery(value: unknown): boolean {
   );
 }
 
-function resolveBuildExportsEffect(
+async function resolveBuildExports(
   build: Record<string, unknown>
-): Effect.Effect<Record<string, unknown>, Error, never> {
+): Promise<Record<string, unknown>> {
   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));
+  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 {
@@ -86,26 +77,25 @@ function isServerBuild(value: unknown): value is ServerBuild {
   );
 }
 
-function resolveServerBuildCandidateEffect(
+async function resolveServerBuildCandidate(
   candidate: unknown
-): Effect.Effect<ServerBuild | undefined, Error, never> {
+): Promise<ServerBuild | undefined> {
   if (!isRecord(candidate)) {
-    return Effect.succeed(undefined);
+    return undefined;
   }
-  return resolveBuildExportsEffect(candidate).pipe(
-    Effect.map(resolved => (isServerBuild(resolved) ? resolved : undefined))
-  );
+  const resolved = await resolveBuildExports(candidate);
+  return isServerBuild(resolved) ? resolved : undefined;
 }
 
-export function resolveServerBuildModuleEffect(
+export async function resolveServerBuildModule(
   buildModule: unknown,
   source: string
-): Effect.Effect<ServerBuild, Error, never> {
-  return Effect.gen(function* () {
+): Promise<ServerBuild> {
+  try {
     const moduleValue = isPromiseLike(buildModule)
-      ? yield* tryPluginPromise(() => buildModule)
+      ? await buildModule
       : buildModule;
-    const candidates = [() => moduleValue];
+    const candidates: Array<() => unknown> = [() => moduleValue];
     if (isRecord(moduleValue)) {
       if ('default' in moduleValue) {
         candidates.push(() => moduleValue.default);
@@ -116,16 +106,16 @@ export function resolveServerBuildModuleEffect(
     }
 
     for (const getCandidate of candidates) {
-      const candidate = yield* tryPluginPromise(() => getCandidate());
-      const serverBuild = yield* resolveServerBuildCandidateEffect(candidate);
+      const candidate = await getCandidate();
+      const serverBuild = await resolveServerBuildCandidate(candidate);
       if (serverBuild) {
         return serverBuild;
       }
     }
-    return yield* Effect.fail(
-      new Error(
-        `[rsbuild-plugin-react-router] ${source} did not contain a valid React Router ServerBuild.`
-      )
+    throw new Error(
+      `[rsbuild-plugin-react-router] ${source} did not contain a valid React Router ServerBuild.`
     );
-  });
+  } catch (cause) {
+    throw normalizeEffectError(cause);
+  }
 }

package/src/server-utils.ts

@@ -1,7 +1,6 @@
 import { resolve } from 'pathe';
 import type { ServerBuild } from 'react-router';
-import { runPluginEffect } from './effect-runtime.js';
-import { resolveServerBuildModuleEffect } from './server-build-resolution.js';
+import { resolveServerBuildModule } from './server-build-resolution.js';
 import type { Route } from './types.js';
 
 /**
@@ -17,6 +16,7 @@ interface ServerBuildOptions {
   basename: string;
   appDirectory: string;
   ssr: boolean;
+  isSpaMode: boolean;
   future?: unknown;
   allowedActionOrigins?: string[];
   prerender?: string[];
@@ -33,19 +33,28 @@ interface ServerBuildOptions {
     | undefined;
 }
 
-function generateStaticTemplate(
+/**
+ * Generates the server build module content
+ * @param routes The route manifest
+ * @param options Build options
+ * @returns The generated module content as a string
+ */
+export function generateServerBuild(
   routes: Record<string, Route>,
   options: ServerBuildOptions
 ): string {
   const manifestId =
     options.serverManifestId ?? 'virtual/react-router/server-manifest';
+  const routeEntries = Object.entries(routes);
   return `
     import * as entryServer from ${JSON.stringify(options.entryServerPath)};
-    ${Object.keys(routes)
-      .map((key, index) => {
-        const route = routes[key];
+    ${routeEntries
+      .map(([, route], index) => {
+        if (options.isSpaMode && route.id !== 'root') {
+          return `const route${index} = { default: () => null };`;
+        }
         return `import * as route${index} from ${JSON.stringify(
-          `${resolve(options.appDirectory, route.file)}?react-router-route`
+          resolve(options.appDirectory, route.file)
         )};`;
       })
       .join('\n')}
@@ -56,7 +65,7 @@ function generateStaticTemplate(
     )};
     export const basename = ${JSON.stringify(options.basename)};
     export const future = ${JSON.stringify(options.future ?? {})};
-    export const isSpaMode = ${!options.ssr};
+    export const isSpaMode = ${options.isSpaMode};
     export const ssr = ${options.ssr};
     export const routeDiscovery = ${JSON.stringify(options.routeDiscovery)};
     export const prerender = ${JSON.stringify(options.prerender ?? [])};
@@ -64,9 +73,8 @@ function generateStaticTemplate(
     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];
+    ${routeEntries
+      .map(([key, route], index) => {
         return `routes[${JSON.stringify(key)}] = {
           id: ${JSON.stringify(route.id)},
           parentId: ${JSON.stringify(route.parentId)},
@@ -80,32 +88,10 @@ function generateStaticTemplate(
   `;
 }
 
-/**
- * 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 { resolveServerBuildModule };
 
 export function resolveReactRouterServerBuild(
   buildModule: unknown
 ): Promise<ServerBuild> {
-  return runPluginEffect(
-    resolveServerBuildModuleEffect(buildModule, 'Imported module')
-  );
+  return resolveServerBuildModule(buildModule, 'Imported module');
 }
-
-export { generateServerBuild };