@ecopages/react 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/router-adapter.ts

@@ -1,95 +0,0 @@
-/**
- * Router adapter interface for React integration.
- * Allows pluggable SPA routers to be used with the React plugin.
- * @module
- */
-
-/**
- * Configuration for a React router adapter.
- * Implement this interface to create custom router integrations.
- *
- * @example
- * ```ts
- * const myRouter: ReactRouterAdapter = {
- *   name: 'my-router',
- *   bundle: {
- *     importPath: '@my/router/browser.ts',
- *     outputName: 'my-router',
- *     externals: ['react', 'react-dom'],
- *   },
- *   importMapKey: '@my/router',
- *   components: {
- *     router: 'MyRouter',
- *     pageContent: 'PageOutlet',
- *   },
- *   getRouterProps: (page, props) => `{ page: ${page}, pageProps: ${props} }`,
- * };
- * ```
- */
-export interface ReactRouterAdapter {
-	/**
-	 * Unique identifier for caching and debugging.
-	 */
-	name: string;
-
-	/**
-	 * Runtime bundle configuration.
-	 */
-	bundle: {
-		/**
-		 * Node module import path for the browser-compatible entry.
-		 * @example '@ecopages/react-router/browser.ts'
-		 */
-		importPath: string;
-
-		/**
-		 * Output filename (without extension).
-		 * @example 'react-router-esm'
-		 */
-		outputName: string;
-
-		/**
-		 * Packages to externalize when bundling.
-		 * These should be available via import map.
-		 * @example ['react', 'react-dom', 'react/jsx-runtime']
-		 */
-		externals: string[];
-	};
-
-	/**
-	 * Bare specifier for the import map entry.
-	 * This is what the hydration script will import from.
-	 * @example '@ecopages/react-router'
-	 */
-	importMapKey: string;
-
-	/**
-	 * Component names to import from the router package.
-	 */
-	components: {
-		/**
-		 * The router component that wraps the layout.
-		 * @example 'EcoRouter'
-		 */
-		router: string;
-
-		/**
-		 * The component that renders the current page content.
-		 * @example 'PageContent'
-		 */
-		pageContent: string;
-	};
-
-	/**
-	 * Generate the props object for the router component.
-	 * @param page - Variable name holding the page component
-	 * @param props - Variable name holding the page props
-	 * @returns Code string for the router props
-	 * @example
-	 * ```ts
-	 * getRouterProps: (page, props) => `{ page: ${page}, pageProps: ${props} }`
-	 * // Results in: { page: Component, pageProps: props }
-	 * ```
-	 */
-	getRouterProps(page: string, props: string): string;
-}

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

@@ -1,212 +0,0 @@
-/**
- * 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.ts

@@ -1,24 +0,0 @@
-/**
- * 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.ts

@@ -1,260 +0,0 @@
-/**
- * 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 path from 'node:path';
-import type { EcoComponentConfig } from '@ecopages/core';
-import { rapidhash } from '@ecopages/core/hash';
-import { RESOLVED_ASSETS_DIR } from '@ecopages/core/constants';
-import {
-	AssetFactory,
-	type AssetDefinition,
-	type ProcessedAsset,
-} from '@ecopages/core/services/asset-processing-service';
-import type { AssetProcessingService } from '@ecopages/core/services/asset-processing-service';
-import { createHydrationScript } from '../utils/hydration-scripts.ts';
-import { createIslandHydrationScript } from '../utils/hydration-scripts.ts';
-import { collectDeclaredModulesInConfig } from '../utils/declared-modules.ts';
-import type { ReactBundleService } from './react-bundle.service.ts';
-import type { ReactHmrPageMetadataCache } from './react-hmr-page-metadata-cache.ts';
-import type { ReactRouterAdapter } from '../router-adapter.ts';
-
-/**
- * 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 class ReactHydrationAssetService {
-	constructor(private readonly 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
-	 */
-	async resolveAssetImportPath(pagePath: string, componentName: string): Promise<string> {
-		const hmrManager = this.config.assetProcessingService?.getHmrManager();
-
-		if (hmrManager?.isEnabled()) {
-			return hmrManager.registerEntrypoint(pagePath);
-		}
-
-		return `/${path
-			.join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath))
-			.replace(path.basename(pagePath), `${componentName}.js`)
-			.replace(/\\/g, '/')}`;
-	}
-
-	/**
-	 * 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[] {
-		const runtimeImports = this.config.bundleService.getRuntimeImports();
-		const dependencies: AssetDefinition[] = [
-			AssetFactory.createFileScript({
-				position: 'head',
-				filepath: pagePath,
-				name: componentName,
-				excludeFromHtml: true,
-				bundle: true,
-				bundleOptions,
-				attributes: {
-					type: 'module',
-					defer: '',
-					'data-eco-persist': 'true',
-				},
-			}),
-		];
-
-		if (props && Object.keys(props).length > 0) {
-			dependencies.push(
-				AssetFactory.createContentScript({
-					position: 'head',
-					content: `window.__ECO_PAGE__={module:"${importPath}",props:${JSON.stringify(props)}};`,
-					name: `${componentName}-props`,
-					bundle: false,
-					attributes: {
-						type: 'module',
-					},
-				}),
-			);
-		}
-
-		dependencies.push(
-			AssetFactory.createContentScript({
-				position: 'head',
-				content: createHydrationScript({
-					importPath,
-					reactImportPath: runtimeImports.react,
-					reactDomClientImportPath: runtimeImports.reactDomClient,
-					routerImportPath: runtimeImports.router,
-					isDevelopment,
-					isMdx,
-					router: this.config.routerAdapter,
-				}),
-				name: `${componentName}-hydration`,
-				bundle: false,
-				attributes: {
-					type: 'module',
-					defer: '',
-					'data-eco-rerun': 'true',
-					'data-eco-script-id': `${componentName}-hydration`,
-					'data-eco-persist': 'true',
-				},
-			}),
-		);
-
-		return dependencies;
-	}
-
-	/**
-	 * 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
-	 */
-	async buildComponentRenderAssets(
-		componentFile: string,
-		componentInstanceId: string,
-		props: Record<string, unknown>,
-		config?: EcoComponentConfig,
-	): Promise<ProcessedAsset[]> {
-		const componentName = `ecopages-react-island-${rapidhash(`${componentFile}:${componentInstanceId}`)}`;
-		const importPath = await this.resolveAssetImportPath(componentFile, componentName);
-		const hmrManager = this.config.assetProcessingService?.getHmrManager();
-		const isDevelopment = hmrManager?.isEnabled() ?? false;
-		const declaredModules = collectDeclaredModulesInConfig(config);
-		const bundleOptions = await this.config.bundleService.createBundleOptions(
-			componentName,
-			false,
-			declaredModules,
-		);
-		const runtimeImports = this.config.bundleService.getRuntimeImports();
-
-		const dependencies: AssetDefinition[] = [
-			AssetFactory.createFileScript({
-				position: 'head',
-				filepath: componentFile,
-				name: componentName,
-				excludeFromHtml: true,
-				bundle: true,
-				bundleOptions,
-				attributes: {
-					type: 'module',
-					defer: '',
-					'data-eco-persist': 'true',
-				},
-			}),
-			AssetFactory.createContentScript({
-				position: 'head',
-				content: createIslandHydrationScript({
-					importPath,
-					reactImportPath: runtimeImports.react,
-					reactDomClientImportPath: runtimeImports.reactDomClient,
-					targetSelector: `[data-eco-component-id="${componentInstanceId}"]`,
-					props,
-					componentRef: config?.__eco?.id,
-					componentFile,
-					isDevelopment,
-				}),
-				name: `${componentName}-hydration`,
-				bundle: false,
-				attributes: {
-					type: 'module',
-					defer: '',
-					'data-eco-rerun': 'true',
-					'data-eco-script-id': `${componentName}-hydration`,
-					'data-eco-persist': 'true',
-				},
-			}),
-		];
-
-		if (!this.config.assetProcessingService) {
-			return [];
-		}
-
-		return this.config.assetProcessingService.processDependencies(dependencies, componentName);
-	}
-
-	/**
-	 * 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
-	 */
-	async buildRouteRenderAssets(
-		pagePath: string,
-		isMdx: boolean,
-		declaredModules: string[],
-	): Promise<ProcessedAsset[]> {
-		const componentName = `ecopages-react-${rapidhash(pagePath)}`;
-		const hmrManager = this.config.assetProcessingService?.getHmrManager();
-		const isDevelopment = hmrManager?.isEnabled() ?? false;
-		if (isDevelopment) {
-			this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
-		}
-
-		const importPath = await this.resolveAssetImportPath(pagePath, componentName);
-		const bundleOptions = await this.config.bundleService.createBundleOptions(
-			componentName,
-			isMdx,
-			declaredModules,
-		);
-		const dependencies = this.createPageDependencies(
-			pagePath,
-			componentName,
-			importPath,
-			bundleOptions,
-			isDevelopment,
-			isMdx,
-		);
-
-		if (!this.config.assetProcessingService) {
-			throw new Error('AssetProcessingService is not set');
-		}
-
-		return this.config.assetProcessingService.processDependencies(dependencies, componentName);
-	}
-}