@ecopages/react 0.2.0-alpha.1

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

@@ -0,0 +1,68 @@
+/**
+ * Bundle configuration service for React integration.
+ *
+ * Encapsulates all esbuild plugin creation and bundle options
+ * for client-side React component builds.
+ *
+ * @module
+ */
+import type { ReactRouterAdapter } from '../router-adapter.js';
+import type { CompileOptions } from '@mdx-js/mdx';
+import { type ReactRuntimeImports } from './react-runtime-bundle.service.js';
+/**
+ * Configuration for the ReactBundleService.
+ */
+export interface ReactBundleServiceConfig {
+    rootDir: string;
+    routerAdapter?: ReactRouterAdapter;
+    mdxCompilerOptions?: CompileOptions;
+}
+/**
+ * Manages esbuild bundle configuration and plugin creation for React page/component builds.
+ */
+export declare class ReactBundleService {
+    private readonly config;
+    private readonly runtimeBundleService;
+    constructor(config: ReactBundleServiceConfig);
+    /**
+     * Returns resolved runtime import paths for the React runtime.
+     */
+    getRuntimeImports(): ReactRuntimeImports;
+    /**
+     * Creates esbuild bundle options for a page or component entry.
+     *
+     * @param componentName - Generated unique component name for output naming
+     * @param isMdx - Whether the source file is an MDX file
+     * @param declaredModules - Explicitly declared browser module specifiers
+     * @returns Bundle options object for the build adapter
+     */
+    createBundleOptions(componentName: string, isMdx: boolean, declaredModules: string[]): Promise<Record<string, unknown>>;
+    /**
+     * 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;
+    };
+    /**
+     * Creates the esbuild plugin that shims `use-sync-external-store/shim`
+     * to re-export from React's built-in `useSyncExternalStore`.
+     * This is needed because some packages use `use-sync-external-store/shim`
+     * but React 18+ has built-in `useSyncExternalStore`.
+     */
+    private createSyncExternalStorePlugin;
+}

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

@@ -0,0 +1,145 @@
+import { createClientGraphBoundaryPlugin } from "../utils/client-graph-boundary-plugin.js";
+import { ReactRuntimeBundleService } from "./react-runtime-bundle.service.js";
+class ReactBundleService {
+  constructor(config) {
+    this.config = config;
+    this.runtimeBundleService = new ReactRuntimeBundleService({
+      routerAdapter: config.routerAdapter
+    });
+  }
+  runtimeBundleService;
+  /**
+   * Returns resolved runtime import paths for the React runtime.
+   */
+  getRuntimeImports() {
+    return this.runtimeBundleService.getRuntimeImports();
+  }
+  /**
+   * Creates esbuild bundle options for a page or component entry.
+   *
+   * @param componentName - Generated unique component name for output naming
+   * @param isMdx - Whether the source file is an MDX file
+   * @param declaredModules - Explicitly declared browser module specifiers
+   * @returns Bundle options object for the build adapter
+   */
+  async createBundleOptions(componentName, isMdx, declaredModules) {
+    const runtimeImports = this.getRuntimeImports();
+    const options = {
+      external: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"],
+      mainFields: ["module", "browser", "main"],
+      naming: `${componentName}.[ext]`,
+      ...import.meta.env?.NODE_ENV === "production" && {
+        minify: true,
+        splitting: false,
+        treeshaking: true
+      }
+    };
+    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] : []
+      ]
+    });
+    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);
+      options.plugins = [runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+    } else {
+      options.plugins = [runtimeAliasPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+    }
+    return options;
+  }
+  /**
+   * 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
+          };
+        });
+      }
+    };
+  }
+  /**
+   * Creates the esbuild plugin that shims `use-sync-external-store/shim`
+   * to re-export from React's built-in `useSyncExternalStore`.
+   * This is needed because some packages use `use-sync-external-store/shim`
+   * but React 18+ has built-in `useSyncExternalStore`.
+   */
+  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"
+          })
+        );
+      }
+    };
+  }
+}
+export {
+  ReactBundleService
+};

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

@@ -0,0 +1,212 @@
+/**
+ * Bundle configuration service for React integration.
+ *
+ * Encapsulates all esbuild plugin creation and bundle options
+ * for client-side React component builds.
+ *
+ * @module
+ */
+
+import { createClientGraphBoundaryPlugin } from '../utils/client-graph-boundary-plugin.ts';
+import type { ReactRouterAdapter } from '../router-adapter.ts';
+import type { CompileOptions } from '@mdx-js/mdx';
+import { ReactRuntimeBundleService, type ReactRuntimeImports } from './react-runtime-bundle.service.ts';
+
+/**
+ * Configuration for the ReactBundleService.
+ */
+export interface ReactBundleServiceConfig {
+	rootDir: string;
+	routerAdapter?: ReactRouterAdapter;
+	mdxCompilerOptions?: CompileOptions;
+}
+
+/**
+ * Manages esbuild bundle configuration and plugin creation for React page/component builds.
+ */
+export class ReactBundleService {
+	private readonly runtimeBundleService: ReactRuntimeBundleService;
+
+	constructor(private readonly config: ReactBundleServiceConfig) {
+		this.runtimeBundleService = new ReactRuntimeBundleService({
+			routerAdapter: config.routerAdapter,
+		});
+	}
+
+	/**
+	 * Returns resolved runtime import paths for the React runtime.
+	 */
+	getRuntimeImports(): ReactRuntimeImports {
+		return this.runtimeBundleService.getRuntimeImports();
+	}
+
+	/**
+	 * Creates esbuild bundle options for a page or component entry.
+	 *
+	 * @param componentName - Generated unique component name for output naming
+	 * @param isMdx - Whether the source file is an MDX file
+	 * @param declaredModules - Explicitly declared browser module specifiers
+	 * @returns Bundle options object for the build adapter
+	 */
+	async createBundleOptions(
+		componentName: string,
+		isMdx: boolean,
+		declaredModules: string[],
+	): Promise<Record<string, unknown>> {
+		const runtimeImports = this.getRuntimeImports();
+		const options: Record<string, unknown> = {
+			external: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom/client'],
+			mainFields: ['module', 'browser', 'main'],
+			naming: `${componentName}.[ext]`,
+			...(import.meta.env?.NODE_ENV === 'production' && {
+				minify: true,
+				splitting: false,
+				treeshaking: true,
+			}),
+		};
+
+		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] : []),
+			],
+		});
+
+		const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeImports);
+		const useSyncExternalStoreShimPlugin = this.createSyncExternalStorePlugin();
+
+		if (isMdx && this.config.mdxCompilerOptions) {
+			const { createReactMdxLoaderPlugin } = await import('../utils/react-mdx-loader-plugin.ts');
+			const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
+			options.plugins = [runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+		} else {
+			options.plugins = [runtimeAliasPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+		}
+
+		return options;
+	}
+
+	/**
+	 * 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,
+					};
+				});
+			},
+		};
+	}
+
+	/**
+	 * Creates the esbuild plugin that shims `use-sync-external-store/shim`
+	 * to re-export from React's built-in `useSyncExternalStore`.
+	 * This is needed because some packages use `use-sync-external-store/shim`
+	 * but React 18+ has built-in `useSyncExternalStore`.
+	 */
+	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',
+					}),
+				);
+			},
+		};
+	}
+}

package/src/services/react-hmr-page-metadata-cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * React-only cache for page metadata that HMR rebuilds need during development.
+ *
+ * This keeps React Fast Refresh optimizations local to the React integration so
+ * core HMR interfaces do not need React-specific metadata hooks.
+ */
+export declare class ReactHmrPageMetadataCache {
+    private readonly declaredModulesByEntrypoint;
+    /**
+     * Stores the declared browser modules for a page entrypoint.
+     */
+    setDeclaredModules(entrypointPath: string, declaredModules: string[]): void;
+    /**
+     * Returns the last known declared browser modules for a page entrypoint.
+     */
+    getDeclaredModules(entrypointPath: string): string[] | undefined;
+}

package/src/services/react-hmr-page-metadata-cache.js

@@ -0,0 +1,19 @@
+class ReactHmrPageMetadataCache {
+  declaredModulesByEntrypoint = /* @__PURE__ */ new Map();
+  /**
+   * Stores the declared browser modules for a page entrypoint.
+   */
+  setDeclaredModules(entrypointPath, declaredModules) {
+    this.declaredModulesByEntrypoint.set(entrypointPath, [...declaredModules]);
+  }
+  /**
+   * Returns the last known declared browser modules for a page entrypoint.
+   */
+  getDeclaredModules(entrypointPath) {
+    const declaredModules = this.declaredModulesByEntrypoint.get(entrypointPath);
+    return declaredModules ? [...declaredModules] : void 0;
+  }
+}
+export {
+  ReactHmrPageMetadataCache
+};

package/src/services/react-hmr-page-metadata-cache.ts

@@ -0,0 +1,24 @@
+/**
+ * React-only cache for page metadata that HMR rebuilds need during development.
+ *
+ * This keeps React Fast Refresh optimizations local to the React integration so
+ * core HMR interfaces do not need React-specific metadata hooks.
+ */
+export class ReactHmrPageMetadataCache {
+	private readonly declaredModulesByEntrypoint = new Map<string, string[]>();
+
+	/**
+	 * Stores the declared browser modules for a page entrypoint.
+	 */
+	setDeclaredModules(entrypointPath: string, declaredModules: string[]): void {
+		this.declaredModulesByEntrypoint.set(entrypointPath, [...declaredModules]);
+	}
+
+	/**
+	 * Returns the last known declared browser modules for a page entrypoint.
+	 */
+	getDeclaredModules(entrypointPath: string): string[] | undefined {
+		const declaredModules = this.declaredModulesByEntrypoint.get(entrypointPath);
+		return declaredModules ? [...declaredModules] : undefined;
+	}
+}

package/src/services/react-hydration-asset.service.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Hydration asset creation service for React integration.
+ *
+ * Builds the asset definitions (bundled component scripts + hydration bootstrap scripts)
+ * required for client-side React rendering — both at the page level and the component
+ * island level.
+ *
+ * @module
+ */
+import type { EcoComponentConfig } from '@ecopages/core';
+import { type AssetDefinition, type ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
+import type { AssetProcessingService } from '@ecopages/core/services/asset-processing-service';
+import type { ReactBundleService } from './react-bundle.service.js';
+import type { ReactHmrPageMetadataCache } from './react-hmr-page-metadata-cache.js';
+import type { ReactRouterAdapter } from '../router-adapter.js';
+/**
+ * Configuration for the ReactHydrationAssetService.
+ */
+export interface ReactHydrationAssetServiceConfig {
+    srcDir: string;
+    routerAdapter?: ReactRouterAdapter;
+    assetProcessingService: AssetProcessingService;
+    bundleService: ReactBundleService;
+    hmrPageMetadataCache?: ReactHmrPageMetadataCache;
+}
+/**
+ * Manages the creation of client-side hydration assets for React pages and component islands.
+ */
+export declare class ReactHydrationAssetService {
+    private readonly config;
+    constructor(config: ReactHydrationAssetServiceConfig);
+    /**
+     * Resolves the import path for the bundled page component.
+     * Uses HMR manager for development or constructs static path for production.
+     *
+     * @param pagePath - Absolute path to the page source file
+     * @param componentName - Generated unique component name
+     * @returns The resolved import path for the bundled component
+     */
+    resolveAssetImportPath(pagePath: string, componentName: string): Promise<string>;
+    /**
+     * Creates the asset dependencies for a page: the bundled component and hydration script.
+     *
+     * @param pagePath - Absolute path to the page source file
+     * @param componentName - Generated unique component name
+     * @param importPath - Resolved import path for the bundled component
+     * @param bundleOptions - Bundle configuration options
+     * @param isDevelopment - Whether running in development mode with HMR
+     * @param isMdx - Whether the source file is an MDX file
+     * @param props - Optional page props for client serialization
+     * @returns Array of asset definitions for processing
+     */
+    createPageDependencies(pagePath: string, componentName: string, importPath: string, bundleOptions: Record<string, unknown>, isDevelopment: boolean, isMdx: boolean, props?: Record<string, unknown>): AssetDefinition[];
+    /**
+     * Builds client-side assets for a React component island.
+     *
+     * Includes the bundled component entry and an inline hydration bootstrap script.
+     *
+     * @param componentFile - Absolute path to the component source file
+     * @param componentInstanceId - Unique instance ID for DOM targeting
+     * @param props - Serialized props for client-side hydration
+     * @param config - Optional component config with `__eco` metadata
+     * @returns Processed assets ready for injection
+     */
+    buildComponentRenderAssets(componentFile: string, componentInstanceId: string, props: Record<string, unknown>, config?: EcoComponentConfig): Promise<ProcessedAsset[]>;
+    /**
+     * Builds all client-side route assets for a page.
+     *
+     * @param pagePath - Absolute file path of the page
+     * @param isMdx - Whether the page is an MDX file
+     * @param declaredModules - Explicitly declared browser module specifiers
+     * @returns Processed assets for the route
+     */
+    buildRouteRenderAssets(pagePath: string, isMdx: boolean, declaredModules: string[]): Promise<ProcessedAsset[]>;
+}