@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.8

package/src/react.plugin.d.ts

@@ -5,7 +5,6 @@
 import { IntegrationPlugin } from '@ecopages/core/plugins/integration-plugin';
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
 import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
-import type { IHmrManager } from '@ecopages/core/internal-types';
 import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
 import type { CompileOptions } from '@mdx-js/mdx';
 import type React from 'react';
@@ -106,12 +105,28 @@ export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
     private mdxLoaderPlugin;
     private runtimeBundleService;
     private readonly hmrPageMetadataCache;
+    private runtimeDependenciesInitialized;
     /**
      * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
      */
     private explicitGraphEnabled;
     constructor(options?: Omit<ReactPluginOptions, 'name'>);
+    private ensureRuntimeDependencies;
     get plugins(): EcoBuildPlugin[];
+    /**
+     * Ensures the optional React MDX loader exists before either config-time
+     * manifest sealing or runtime setup needs it.
+     */
+    private ensureMdxLoaderPlugin;
+    /**
+     * Prepares React's build-facing loader contributions before config build seals
+     * the app manifest.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Performs runtime-only React setup after build contributions are already
+     * materialized.
+     */
     setup(): Promise<void>;
     /**
      * Provides React-specific HMR strategy with Fast Refresh support.
@@ -123,10 +138,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
      * @returns ReactHmrStrategy instance for handling React component updates
      */
     getHmrStrategy(): HmrStrategy | undefined;
-    /**
-     * Override to register React-specific specifier mappings for HMR.
-     */
-    setHmrManager(hmrManager: IHmrManager): void;
+    getRuntimeSpecifierMap(): Record<string, string>;
     /**
      * Declares React's boundary deferral rule for cross-integration rendering.
      *

package/src/react.plugin.js

@@ -15,15 +15,21 @@ class ReactPlugin extends IntegrationPlugin {
   mdxLoaderPlugin;
   runtimeBundleService;
   hmrPageMetadataCache = new ReactHmrPageMetadataCache();
+  runtimeDependenciesInitialized = false;
   /**
    * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
    */
   explicitGraphEnabled;
   constructor(options) {
-    const extensions = [".tsx"];
+    const { extensions: _ignoredExtensions, ...restOptions } = options ?? {};
+    const extensions = [...options?.extensions ?? [".tsx"]];
     const mdxExtensions = options?.mdx?.extensions ?? [".mdx"];
     if (options?.mdx?.enabled) {
-      extensions.push(...mdxExtensions);
+      for (const extension of mdxExtensions) {
+        if (!extensions.includes(extension)) {
+          extensions.push(extension);
+        }
+      }
     } else if (options?.mdx?.extensions?.length) {
       appLogger.warn(
         "MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support."
@@ -32,7 +38,7 @@ class ReactPlugin extends IntegrationPlugin {
     super({
       name: PLUGIN_NAME,
       extensions,
-      ...options
+      ...restOptions
     });
     this.mdxEnabled = options?.mdx?.enabled ?? false;
     this.mdxExtensions = mdxExtensions;
@@ -59,7 +65,13 @@ class ReactPlugin extends IntegrationPlugin {
     ReactRenderer.mdxExtensions = this.mdxExtensions;
     ReactRenderer.explicitGraphEnabled = this.explicitGraphEnabled;
     ReactRenderer.hmrPageMetadataCache = this.hmrPageMetadataCache;
+  }
+  ensureRuntimeDependencies() {
+    if (this.runtimeDependenciesInitialized) {
+      return;
+    }
     this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
+    this.runtimeDependenciesInitialized = true;
   }
   get plugins() {
     if (this.mdxLoaderPlugin) {
@@ -67,11 +79,32 @@ class ReactPlugin extends IntegrationPlugin {
     }
     return [];
   }
-  async setup() {
-    if (this.mdxEnabled && this.mdxCompilerOptions) {
-      const { createReactMdxLoaderPlugin } = await import("./utils/react-mdx-loader-plugin.js");
-      this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+  /**
+   * Ensures the optional React MDX loader exists before either config-time
+   * manifest sealing or runtime setup needs it.
+   */
+  async ensureMdxLoaderPlugin() {
+    if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
+      return;
     }
+    const { createReactMdxLoaderPlugin } = await import("./utils/react-mdx-loader-plugin.js");
+    this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+  }
+  /**
+   * Prepares React's build-facing loader contributions before config build seals
+   * the app manifest.
+   */
+  async prepareBuildContributions() {
+    this.ensureRuntimeDependencies();
+    await this.ensureMdxLoaderPlugin();
+  }
+  /**
+   * Performs runtime-only React setup after build contributions are already
+   * materialized.
+   */
+  async setup() {
+    this.ensureRuntimeDependencies();
+    await this.ensureMdxLoaderPlugin();
     await super.setup();
   }
   /**
@@ -92,15 +125,13 @@ class ReactPlugin extends IntegrationPlugin {
       context,
       this.hmrPageMetadataCache,
       this.mdxCompilerOptions,
+      this.extensions,
+      this.appConfig.templatesExt,
       this.explicitGraphEnabled
     );
   }
-  /**
-   * Override to register React-specific specifier mappings for HMR.
-   */
-  setHmrManager(hmrManager) {
-    super.setHmrManager(hmrManager);
-    hmrManager.registerSpecifierMap(this.runtimeBundleService.getSpecifierMap());
+  getRuntimeSpecifierMap() {
+    return this.runtimeBundleService.getSpecifierMap();
   }
   /**
    * Declares React's boundary deferral rule for cross-integration rendering.

package/src/react.plugin.ts

@@ -5,7 +5,6 @@
 import { IntegrationPlugin } from '@ecopages/core/plugins/integration-plugin';
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
 import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
-import type { IHmrManager } from '@ecopages/core/internal-types';
 import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
 import { Logger } from '@ecopages/logger';
 import type { CompileOptions } from '@mdx-js/mdx';
@@ -116,17 +115,23 @@ export class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
 	private mdxLoaderPlugin: EcoBuildPlugin | undefined;
 	private runtimeBundleService: ReactRuntimeBundleService;
 	private readonly hmrPageMetadataCache = new ReactHmrPageMetadataCache();
+	private runtimeDependenciesInitialized = false;
 	/**
 	 * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
 	 */
 	private explicitGraphEnabled: boolean;
 
 	constructor(options?: Omit<ReactPluginOptions, 'name'>) {
-		const extensions = ['.tsx'];
+		const { extensions: _ignoredExtensions, ...restOptions } = options ?? {};
+		const extensions = [...(options?.extensions ?? ['.tsx'])];
 		const mdxExtensions = options?.mdx?.extensions ?? ['.mdx'];
 
 		if (options?.mdx?.enabled) {
-			extensions.push(...mdxExtensions);
+			for (const extension of mdxExtensions) {
+				if (!extensions.includes(extension)) {
+					extensions.push(extension);
+				}
+			}
 		} else if (options?.mdx?.extensions?.length) {
 			appLogger.warn(
 				'MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support.',
@@ -136,7 +141,7 @@ export class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
 		super({
 			name: PLUGIN_NAME,
 			extensions,
-			...options,
+			...restOptions,
 		});
 
 		this.mdxEnabled = options?.mdx?.enabled ?? false;
@@ -166,7 +171,15 @@ export class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
 		ReactRenderer.mdxExtensions = this.mdxExtensions;
 		ReactRenderer.explicitGraphEnabled = this.explicitGraphEnabled;
 		ReactRenderer.hmrPageMetadataCache = this.hmrPageMetadataCache;
+	}
+
+	private ensureRuntimeDependencies(): void {
+		if (this.runtimeDependenciesInitialized) {
+			return;
+		}
+
 		this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
+		this.runtimeDependenciesInitialized = true;
 	}
 
 	override get plugins(): EcoBuildPlugin[] {
@@ -176,11 +189,35 @@ export class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
 		return [];
 	}
 
-	override async setup(): Promise<void> {
-		if (this.mdxEnabled && this.mdxCompilerOptions) {
-			const { createReactMdxLoaderPlugin } = await import('./utils/react-mdx-loader-plugin.ts');
-			this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+	/**
+	 * Ensures the optional React MDX loader exists before either config-time
+	 * manifest sealing or runtime setup needs it.
+	 */
+	private async ensureMdxLoaderPlugin(): Promise<void> {
+		if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
+			return;
 		}
+
+		const { createReactMdxLoaderPlugin } = await import('./utils/react-mdx-loader-plugin.ts');
+		this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+	}
+
+	/**
+	 * Prepares React's build-facing loader contributions before config build seals
+	 * the app manifest.
+	 */
+	override async prepareBuildContributions(): Promise<void> {
+		this.ensureRuntimeDependencies();
+		await this.ensureMdxLoaderPlugin();
+	}
+
+	/**
+	 * Performs runtime-only React setup after build contributions are already
+	 * materialized.
+	 */
+	override async setup(): Promise<void> {
+		this.ensureRuntimeDependencies();
+		await this.ensureMdxLoaderPlugin();
 		await super.setup();
 	}
 
@@ -204,16 +241,14 @@ export class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
 			context,
 			this.hmrPageMetadataCache,
 			this.mdxCompilerOptions,
+			this.extensions,
+			this.appConfig.templatesExt,
 			this.explicitGraphEnabled,
 		);
 	}
 
-	/**
-	 * Override to register React-specific specifier mappings for HMR.
-	 */
-	override setHmrManager(hmrManager: IHmrManager): void {
-		super.setHmrManager(hmrManager);
-		hmrManager.registerSpecifierMap(this.runtimeBundleService.getSpecifierMap());
+	override getRuntimeSpecifierMap(): Record<string, string> {
+		return this.runtimeBundleService.getSpecifierMap();
 	}
 
 	/**

package/src/router-adapter.d.ts

@@ -46,13 +46,13 @@ export interface ReactRouterAdapter {
         outputName: string;
         /**
          * Packages to externalize when bundling.
-         * These should be available via import map.
+         * These should be available through the runtime bare-specifier map.
          * @example ['react', 'react-dom', 'react/jsx-runtime']
          */
         externals: string[];
     };
     /**
-     * Bare specifier for the import map entry.
+     * Bare specifier for the runtime mapping entry.
      * This is what the hydration script will import from.
      * @example '@ecopages/react-router'
      */

package/src/router-adapter.ts

@@ -50,14 +50,14 @@ export interface ReactRouterAdapter {
 
 		/**
 		 * Packages to externalize when bundling.
-		 * These should be available via import map.
+		 * These should be available through the runtime bare-specifier map.
 		 * @example ['react', 'react-dom', 'react/jsx-runtime']
 		 */
 		externals: string[];
 	};
 
 	/**
-	 * Bare specifier for the import map entry.
+	 * Bare specifier for the runtime mapping entry.
 	 * This is what the hydration script will import from.
 	 * @example '@ecopages/react-router'
 	 */

package/src/services/react-bundle.service.d.ts

@@ -21,8 +21,8 @@ export interface ReactBundleServiceConfig {
  * Manages esbuild bundle configuration and plugin creation for React page/component builds.
  */
 export declare class ReactBundleService {
-    private readonly config;
     private readonly runtimeBundleService;
+    private readonly config;
     constructor(config: ReactBundleServiceConfig);
     /**
      * Returns resolved runtime import paths for the React runtime.
@@ -41,33 +41,5 @@ export declare class ReactBundleService {
      * Creates the esbuild plugin that rewrites bare React specifiers
      * to their runtime asset URLs.
      */
-    createRuntimeAliasPlugin(runtimeImports: ReactRuntimeImports): {
-        name: string;
-        setup(build: {
-            onResolve: (options: {
-                filter: RegExp;
-                namespace?: string;
-            }, callback: (args: {
-                path: string;
-                importer: string;
-                namespace: string;
-            }) => {
-                path?: string;
-                namespace?: string;
-                external?: boolean;
-            } | undefined) => void;
-        }): void;
-    };
-    /**
-     * Redirects `use-sync-external-store/shim` imports to React's built-in
-     * `useSyncExternalStore`.
-     *
-     * Libraries like React Aria still list `use-sync-external-store` as a
-     * dependency to support React 16/17. On React 18+ the `/shim` export is
-     * already a pass-through, but without this plugin esbuild would bundle
-     * the full CJS shim (including `process.env` branching) into the browser
-     * bundle. The plugin short-circuits the resolution so only a single clean
-     * ESM re-export is emitted.
-     */
-    private createSyncExternalStorePlugin;
+    createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>): import("packages/core/src/build/build-types.ts").EcoBuildPlugin | null;
 }

package/src/services/react-bundle.service.js

@@ -1,13 +1,21 @@
 import { createClientGraphBoundaryPlugin } from "../utils/client-graph-boundary-plugin.js";
+import {
+  buildReactRuntimeSpecifierMap,
+  getReactClientGraphAllowSpecifiers,
+  getReactRuntimeExternalSpecifiers
+} from "../utils/react-runtime-specifier-map.js";
+import { createUseSyncExternalStoreShimPlugin } from "../utils/use-sync-external-store-shim-plugin.js";
+import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import { ReactRuntimeBundleService } from "./react-runtime-bundle.service.js";
 class ReactBundleService {
+  runtimeBundleService;
+  config;
   constructor(config) {
     this.config = config;
     this.runtimeBundleService = new ReactRuntimeBundleService({
       routerAdapter: config.routerAdapter
     });
   }
-  runtimeBundleService;
   /**
    * Returns resolved runtime import paths for the React runtime.
    */
@@ -24,8 +32,9 @@ class ReactBundleService {
    */
   async createBundleOptions(componentName, isMdx, declaredModules) {
     const runtimeImports = this.getRuntimeImports();
+    const runtimeSpecifierMap = buildReactRuntimeSpecifierMap(runtimeImports, this.config.routerAdapter);
     const options = {
-      external: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"],
+      external: getReactRuntimeExternalSpecifiers(),
       mainFields: ["module", "browser", "main"],
       naming: `${componentName}.[ext]`,
       ...import.meta.env?.NODE_ENV === "production" && {
@@ -37,18 +46,13 @@ class ReactBundleService {
     const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
       absWorkingDir: this.config.rootDir,
       declaredModules,
-      alwaysAllowSpecifiers: [
-        "@ecopages/core",
-        "react",
-        "react-dom",
-        "react/jsx-runtime",
-        "react/jsx-dev-runtime",
-        "react-dom/client",
-        ...this.config.routerAdapter ? [this.config.routerAdapter.importMapKey] : []
-      ]
+      alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter)
+    });
+    const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeSpecifierMap);
+    const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
+      name: "react-renderer-use-sync-external-store-shim",
+      namespace: "ecopages-react-renderer-shim"
     });
-    const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeImports);
-    const useSyncExternalStoreShimPlugin = this.createSyncExternalStorePlugin();
     if (isMdx && this.config.mdxCompilerOptions) {
       const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
       const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
@@ -62,87 +66,8 @@ class ReactBundleService {
    * Creates the esbuild plugin that rewrites bare React specifiers
    * to their runtime asset URLs.
    */
-  createRuntimeAliasPlugin(runtimeImports) {
-    const aliases = /* @__PURE__ */ new Map([
-      ["react", runtimeImports.react],
-      ["react-dom/client", runtimeImports.reactDomClient],
-      ["react/jsx-runtime", runtimeImports.reactJsxRuntime],
-      ["react/jsx-dev-runtime", runtimeImports.reactJsxDevRuntime],
-      ["react-dom", runtimeImports.reactDom]
-    ]);
-    if (this.config.routerAdapter && runtimeImports.router) {
-      aliases.set(this.config.routerAdapter.importMapKey, runtimeImports.router);
-    }
-    const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const pattern = new RegExp(
-      `^(${Array.from(aliases.keys()).map((key) => escapeRegExp(key)).join("|")})$`
-    );
-    return {
-      name: "react-runtime-import-alias",
-      setup(build) {
-        build.onResolve({ filter: pattern }, (args) => {
-          const mappedPath = aliases.get(args.path);
-          if (!mappedPath) {
-            return void 0;
-          }
-          return {
-            path: mappedPath,
-            external: true
-          };
-        });
-      }
-    };
-  }
-  /**
-   * Redirects `use-sync-external-store/shim` imports to React's built-in
-   * `useSyncExternalStore`.
-   *
-   * Libraries like React Aria still list `use-sync-external-store` as a
-   * dependency to support React 16/17. On React 18+ the `/shim` export is
-   * already a pass-through, but without this plugin esbuild would bundle
-   * the full CJS shim (including `process.env` branching) into the browser
-   * bundle. The plugin short-circuits the resolution so only a single clean
-   * ESM re-export is emitted.
-   */
-  createSyncExternalStorePlugin() {
-    return {
-      name: "react-renderer-use-sync-external-store-shim",
-      setup(build) {
-        build.onResolve({ filter: /^use-sync-external-store\/shim(?:\/index\.js)?$/ }, () => ({
-          path: "use-sync-external-store/shim",
-          namespace: "ecopages-react-renderer-shim"
-        }));
-        build.onLoad(
-          { filter: /^use-sync-external-store\/shim$/, namespace: "ecopages-react-renderer-shim" },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-        build.onLoad({ filter: /[\\/]use-sync-external-store[\\/]shim[\\/]index\.js$/ }, () => ({
-          contents: "export { useSyncExternalStore } from 'react';",
-          loader: "js"
-        }));
-        build.onLoad(
-          {
-            filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.development\.js$/
-          },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-        build.onLoad(
-          {
-            filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.production\.js$/
-          },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-      }
-    };
+  createRuntimeAliasPlugin(runtimeSpecifierMap) {
+    return createRuntimeSpecifierAliasPlugin(runtimeSpecifierMap, { name: "react-runtime-import-alias" });
   }
 }
 export {

package/src/services/react-bundle.service.ts

@@ -8,6 +8,13 @@
  */
 
 import { createClientGraphBoundaryPlugin } from '../utils/client-graph-boundary-plugin.ts';
+import {
+	buildReactRuntimeSpecifierMap,
+	getReactClientGraphAllowSpecifiers,
+	getReactRuntimeExternalSpecifiers,
+} from '../utils/react-runtime-specifier-map.ts';
+import { createUseSyncExternalStoreShimPlugin } from '../utils/use-sync-external-store-shim-plugin.ts';
+import { createRuntimeSpecifierAliasPlugin } from '@ecopages/core/build/runtime-specifier-alias-plugin';
 import type { ReactRouterAdapter } from '../router-adapter.ts';
 import type { CompileOptions } from '@mdx-js/mdx';
 import { ReactRuntimeBundleService, type ReactRuntimeImports } from './react-runtime-bundle.service.ts';
@@ -26,8 +33,10 @@ export interface ReactBundleServiceConfig {
  */
 export class ReactBundleService {
 	private readonly runtimeBundleService: ReactRuntimeBundleService;
+	private readonly config: ReactBundleServiceConfig;
 
-	constructor(private readonly config: ReactBundleServiceConfig) {
+	constructor(config: ReactBundleServiceConfig) {
+		this.config = config;
 		this.runtimeBundleService = new ReactRuntimeBundleService({
 			routerAdapter: config.routerAdapter,
 		});
@@ -54,8 +63,9 @@ export class ReactBundleService {
 		declaredModules: string[],
 	): Promise<Record<string, unknown>> {
 		const runtimeImports = this.getRuntimeImports();
+		const runtimeSpecifierMap = buildReactRuntimeSpecifierMap(runtimeImports, this.config.routerAdapter);
 		const options: Record<string, unknown> = {
-			external: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom/client'],
+			external: getReactRuntimeExternalSpecifiers(),
 			mainFields: ['module', 'browser', 'main'],
 			naming: `${componentName}.[ext]`,
 			...(import.meta.env?.NODE_ENV === 'production' && {
@@ -68,19 +78,14 @@ export class ReactBundleService {
 		const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
 			absWorkingDir: this.config.rootDir,
 			declaredModules,
-			alwaysAllowSpecifiers: [
-				'@ecopages/core',
-				'react',
-				'react-dom',
-				'react/jsx-runtime',
-				'react/jsx-dev-runtime',
-				'react-dom/client',
-				...(this.config.routerAdapter ? [this.config.routerAdapter.importMapKey] : []),
-			],
+			alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter),
 		});
 
-		const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeImports);
-		const useSyncExternalStoreShimPlugin = this.createSyncExternalStorePlugin();
+		const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeSpecifierMap);
+		const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
+			name: 'react-renderer-use-sync-external-store-shim',
+			namespace: 'ecopages-react-renderer-shim',
+		});
 
 		if (isMdx && this.config.mdxCompilerOptions) {
 			const { createReactMdxLoaderPlugin } = await import('../utils/react-mdx-loader-plugin.ts');
@@ -97,121 +102,7 @@ export class ReactBundleService {
 	 * Creates the esbuild plugin that rewrites bare React specifiers
 	 * to their runtime asset URLs.
 	 */
-	createRuntimeAliasPlugin(runtimeImports: ReactRuntimeImports) {
-		const aliases = new Map<string, string>([
-			['react', runtimeImports.react],
-			['react-dom/client', runtimeImports.reactDomClient],
-			['react/jsx-runtime', runtimeImports.reactJsxRuntime],
-			['react/jsx-dev-runtime', runtimeImports.reactJsxDevRuntime],
-			['react-dom', runtimeImports.reactDom],
-		]);
-
-		if (this.config.routerAdapter && runtimeImports.router) {
-			aliases.set(this.config.routerAdapter.importMapKey, runtimeImports.router);
-		}
-
-		const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-		const pattern = new RegExp(
-			`^(${Array.from(aliases.keys())
-				.map((key) => escapeRegExp(key))
-				.join('|')})$`,
-		);
-
-		return {
-			name: 'react-runtime-import-alias',
-			setup(build: {
-				onResolve: (
-					options: { filter: RegExp; namespace?: string },
-					callback: (args: {
-						path: string;
-						importer: string;
-						namespace: string;
-					}) => { path?: string; namespace?: string; external?: boolean } | undefined,
-				) => void;
-			}) {
-				build.onResolve({ filter: pattern }, (args) => {
-					const mappedPath = aliases.get(args.path);
-					if (!mappedPath) {
-						return undefined;
-					}
-					return {
-						path: mappedPath,
-						external: true,
-					};
-				});
-			},
-		};
-	}
-
-	/**
-	 * Redirects `use-sync-external-store/shim` imports to React's built-in
-	 * `useSyncExternalStore`.
-	 *
-	 * Libraries like React Aria still list `use-sync-external-store` as a
-	 * dependency to support React 16/17. On React 18+ the `/shim` export is
-	 * already a pass-through, but without this plugin esbuild would bundle
-	 * the full CJS shim (including `process.env` branching) into the browser
-	 * bundle. The plugin short-circuits the resolution so only a single clean
-	 * ESM re-export is emitted.
-	 */
-	private createSyncExternalStorePlugin() {
-		return {
-			name: 'react-renderer-use-sync-external-store-shim',
-			setup(build: {
-				onResolve: (
-					options: { filter: RegExp; namespace?: string },
-					callback: (args: {
-						path: string;
-						importer: string;
-						namespace: string;
-					}) => { path?: string; namespace?: string } | undefined,
-				) => void;
-				onLoad: (
-					options: { filter: RegExp; namespace?: string },
-					callback: (args: {
-						path: string;
-						namespace: string;
-					}) => { contents?: string; loader?: 'js' } | undefined,
-				) => void;
-			}) {
-				build.onResolve({ filter: /^use-sync-external-store\/shim(?:\/index\.js)?$/ }, () => ({
-					path: 'use-sync-external-store/shim',
-					namespace: 'ecopages-react-renderer-shim',
-				}));
-
-				build.onLoad(
-					{ filter: /^use-sync-external-store\/shim$/, namespace: 'ecopages-react-renderer-shim' },
-					() => ({
-						contents: "export { useSyncExternalStore } from 'react';",
-						loader: 'js',
-					}),
-				);
-
-				build.onLoad({ filter: /[\\/]use-sync-external-store[\\/]shim[\\/]index\.js$/ }, () => ({
-					contents: "export { useSyncExternalStore } from 'react';",
-					loader: 'js',
-				}));
-
-				build.onLoad(
-					{
-						filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.development\.js$/,
-					},
-					() => ({
-						contents: "export { useSyncExternalStore } from 'react';",
-						loader: 'js',
-					}),
-				);
-
-				build.onLoad(
-					{
-						filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.production\.js$/,
-					},
-					() => ({
-						contents: "export { useSyncExternalStore } from 'react';",
-						loader: 'js',
-					}),
-				);
-			},
-		};
+	createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>) {
+		return createRuntimeSpecifierAliasPlugin(runtimeSpecifierMap, { name: 'react-runtime-import-alias' });
 	}
 }