@ecopages/react 0.2.0-alpha.8 → 0.2.1

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

@@ -1,263 +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, 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 {
-	private readonly config: ReactHydrationAssetServiceConfig;
-
-	constructor(config: ReactHydrationAssetServiceConfig) {
-		this.config = config;
-	}
-
-	/**
-	 * 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_PAGES__=window.__ECO_PAGES__||{};window.__ECO_PAGES__.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);
-	}
-}

package/src/services/react-page-module.service.ts

@@ -1,224 +0,0 @@
-/**
- * Page module loading and configuration resolution service for React integration.
- *
- * Handles MDX compilation, component config metadata resolution,
- * and module hydration analysis.
- *
- * @module
- */
-
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import type { EcoComponentConfig, EcoPageFile } from '@ecopages/core';
-import type { BuildExecutor } from '@ecopages/core/build/build-adapter';
-import { rapidhash } from '@ecopages/core/hash';
-import { build } from '@ecopages/core/build/build-adapter';
-import { fileSystem } from '@ecopages/file-system';
-import type { CompileOptions } from '@mdx-js/mdx';
-import { collectDeclaredModulesInConfig } from '../utils/declared-modules.ts';
-
-/**
- * Configuration for the ReactPageModuleService.
- */
-export interface ReactPageModuleServiceConfig {
-	rootDir: string;
-	distDir: string;
-	workDir: string;
-	buildExecutor: BuildExecutor;
-	layoutsDir?: string;
-	componentsDir?: string;
-	mdxCompilerOptions?: CompileOptions;
-	mdxExtensions: string[];
-	integrationName: string;
-	hasRouterAdapter: boolean;
-}
-
-/**
- * Manages page module loading (including MDX compilation), config metadata
- * resolution, and hydration analysis for React pages.
- */
-export class ReactPageModuleService {
-	private readonly config: ReactPageModuleServiceConfig;
-
-	constructor(config: ReactPageModuleServiceConfig) {
-		this.config = config;
-	}
-
-	/**
-	 * Checks if the given file path corresponds to an MDX file based on configured extensions.
-	 * @param filePath - The file path to check
-	 * @returns True if the file is an MDX file
-	 */
-	isMdxFile(filePath: string): boolean {
-		return this.config.mdxExtensions.some((ext) => filePath.endsWith(ext));
-	}
-
-	/**
-	 * Compiles and imports an MDX file as a page module.
-	 *
-	 * @param filePath - Absolute path to the MDX file
-	 * @returns The imported module
-	 */
-	async importMdxPageFile(filePath: string): Promise<unknown> {
-		const { createReactMdxLoaderPlugin } = await import('../utils/react-mdx-loader-plugin.ts');
-		const mdxPlugin = createReactMdxLoaderPlugin(
-			this.config.mdxCompilerOptions ?? {
-				jsxImportSource: 'react',
-				jsxRuntime: 'automatic',
-				development: process?.env?.NODE_ENV === 'development',
-			},
-		);
-
-		const outdir = path.join(this.config.workDir, '.server-modules-react-mdx');
-		const fileBaseName = path.basename(filePath, path.extname(filePath));
-		const fileHash = fileSystem.hash(filePath);
-		const cacheBuster = process?.env?.NODE_ENV === 'development' ? `-${Date.now()}` : '';
-		const outputFileName = `${fileBaseName}-${fileHash}${cacheBuster}.js`;
-
-		const buildResult = await build(
-			{
-				entrypoints: [filePath],
-				root: this.config.rootDir,
-				outdir,
-				target: 'node',
-				format: 'esm',
-				sourcemap: 'none',
-				splitting: false,
-				minify: false,
-				treeshaking: false,
-				naming: outputFileName,
-				plugins: [mdxPlugin],
-			},
-			this.config.buildExecutor,
-		);
-
-		if (!buildResult.success) {
-			const details = buildResult.logs.map((log) => log.message).join(' | ');
-			throw new Error(`Failed to compile MDX page module: ${details}`);
-		}
-
-		const preferredOutputPath = path.join(outdir, outputFileName);
-		const compiledOutput =
-			buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ??
-			buildResult.outputs.find((output) => output.path.endsWith('.js'))?.path;
-
-		if (!compiledOutput) {
-			throw new Error(`No compiled MDX output generated for page: ${filePath}`);
-		}
-
-		return await import(pathToFileURL(compiledOutput).href);
-	}
-
-	/**
-	 * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
-	 * Resolves the file path from dependency declarations when not already set.
-	 *
-	 * @param config - The component config to augment
-	 * @param pagePath - Fallback file path if dependency resolution fails
-	 * @returns Config with `__eco` metadata populated
-	 */
-	ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig {
-		if (config.__eco?.file) {
-			return config;
-		}
-
-		const buildEcoMeta = (file: string) => ({
-			id: config.__eco?.id ?? rapidhash(file).toString(36),
-			integration: config.__eco?.integration ?? this.config.integrationName,
-			file,
-		});
-
-		const resolveDependencyValue = (value: string | { src?: string }) =>
-			typeof value === 'string' ? value : value.src;
-
-		const dependencyPaths = [
-			...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
-			...(config.dependencies?.scripts ?? []).map(resolveDependencyValue),
-		]
-			.filter((value): value is string => Boolean(value))
-			.filter((value) => value.startsWith('./') || value.startsWith('../'));
-
-		const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter(
-			(value): value is string => typeof value === 'string' && value.length > 0,
-		);
-
-		for (const dependencyPath of dependencyPaths) {
-			for (const candidateDir of candidateDirs) {
-				const resolvedDependency = path.resolve(candidateDir, dependencyPath);
-				if (fileSystem.exists(resolvedDependency)) {
-					return {
-						...config,
-						__eco: buildEcoMeta(path.join(candidateDir, path.basename(pagePath))),
-					};
-				}
-			}
-		}
-
-		return {
-			...config,
-			__eco: buildEcoMeta(pagePath),
-		};
-	}
-
-	/**
-	 * Recursively checks whether a component config tree declares any browser modules.
-	 * Used to determine if a page needs hydration.
-	 */
-	hasModulesInConfig(config: EcoComponentConfig | undefined, visited = new Set<EcoComponentConfig>()): boolean {
-		if (!config || visited.has(config)) {
-			return false;
-		}
-
-		visited.add(config);
-
-		if (config.dependencies?.modules?.some((entry) => entry.trim().length > 0)) {
-			return true;
-		}
-
-		if (config.layout?.config && this.hasModulesInConfig(config.layout.config, visited)) {
-			return true;
-		}
-
-		for (const component of config.dependencies?.components ?? []) {
-			if (this.hasModulesInConfig(component.config, visited)) {
-				return true;
-			}
-		}
-
-		return false;
-	}
-
-	/**
-	 * Determines whether a page needs client-side hydration.
-	 *
-	 * @param pageModule - The imported page module
-	 * @returns True if the page should be hydrated
-	 */
-	shouldHydratePage(
-		pageModule: EcoPageFile<{ config?: EcoComponentConfig }> & { config?: EcoComponentConfig },
-	): boolean {
-		if (this.config.hasRouterAdapter) {
-			return true;
-		}
-
-		const pageConfig = pageModule.default?.config;
-		return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
-	}
-
-	/**
-	 * Collects all explicitly declared browser module specifiers from a page module.
-	 *
-	 * @param pageModule - The imported page module
-	 * @returns Deduplicated list of declared module specifiers
-	 */
-	collectPageDeclaredModules(
-		pageModule: EcoPageFile<{ config?: EcoComponentConfig }> & { config?: EcoComponentConfig },
-	): string[] {
-		const declarations = [
-			...collectDeclaredModulesInConfig(pageModule.default?.config),
-			...collectDeclaredModulesInConfig(pageModule.config),
-		];
-
-		return Array.from(new Set(declarations));
-	}
-}

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

@@ -1,172 +0,0 @@
-/**
- * Runtime bundle service for React integration.
- *
- * Owns creation of the browser runtime assets for React and React DOM,
- * including shared runtime entry generation and specifier mapping.
- *
- * @module
- */
-
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import { createRuntimeSpecifierAliasPlugin } from '@ecopages/core/build/runtime-specifier-alias-plugin';
-import {
-	buildBrowserRuntimeAssetUrl,
-	createBrowserRuntimeModuleAsset,
-	createBrowserRuntimeScriptAsset,
-	type AssetDefinition,
-} from '@ecopages/core/services/asset-processing-service';
-import type { ReactRouterAdapter } from '../router-adapter.ts';
-import { createReactDomRuntimeInteropPlugin } from '../utils/react-dom-runtime-interop-plugin.ts';
-import { buildReactRuntimeSpecifierMap } from '../utils/react-runtime-specifier-map.ts';
-
-export type ReactRuntimeImports = {
-	react: string;
-	reactDomClient: string;
-	reactJsxRuntime: string;
-	reactJsxDevRuntime: string;
-	reactDom: string;
-	router?: string;
-};
-
-export interface ReactRuntimeBundleServiceConfig {
-	routerAdapter?: ReactRouterAdapter;
-}
-
-type RuntimeMode = 'development' | 'production';
-
-export class ReactRuntimeBundleService {
-	private readonly config: ReactRuntimeBundleServiceConfig;
-
-	constructor(config: ReactRuntimeBundleServiceConfig) {
-		this.config = config;
-	}
-
-	private get isDevelopment(): boolean {
-		return process.env.NODE_ENV === 'development';
-	}
-
-	private getCurrentRuntimeMode(): RuntimeMode {
-		return this.isDevelopment ? 'development' : 'production';
-	}
-
-	private createRuntimeDefines(mode: RuntimeMode): Record<string, string> {
-		const nodeEnv = JSON.stringify(mode);
-
-		return {
-			'process.env.NODE_ENV': nodeEnv,
-			'import.meta.env.NODE_ENV': nodeEnv,
-		};
-	}
-
-	private getReactVendorFileName(mode: RuntimeMode): string {
-		return mode === 'development' ? 'react.development.js' : 'react.js';
-	}
-
-	private getReactDomVendorFileName(mode: RuntimeMode): string {
-		return mode === 'development' ? 'react-dom.development.js' : 'react-dom.js';
-	}
-
-	private getRouterVendorFileName(mode: RuntimeMode): string {
-		if (!this.config.routerAdapter) {
-			return '';
-		}
-
-		return mode === 'development'
-			? `${this.config.routerAdapter.bundle.outputName}.development.js`
-			: `${this.config.routerAdapter.bundle.outputName}.js`;
-	}
-
-	getRuntimeImports(mode = this.getCurrentRuntimeMode()): ReactRuntimeImports {
-		const reactVendorFileName = this.getReactVendorFileName(mode);
-		const reactDomVendorFileName = this.getReactDomVendorFileName(mode);
-		const runtimeImports: ReactRuntimeImports = {
-			react: buildBrowserRuntimeAssetUrl(reactVendorFileName),
-			reactDomClient: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
-			reactJsxRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
-			reactJsxDevRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
-			reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
-		};
-
-		if (this.config.routerAdapter) {
-			runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getRouterVendorFileName(mode));
-		}
-
-		return runtimeImports;
-	}
-
-	getSpecifierMap(mode = this.getCurrentRuntimeMode()): Record<string, string> {
-		return buildReactRuntimeSpecifierMap(this.getRuntimeImports(mode), this.config.routerAdapter);
-	}
-
-	getDependencies(): AssetDefinition[] {
-		const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin();
-		const dependencies: AssetDefinition[] = [];
-
-		for (const mode of ['production', 'development'] as const) {
-			const reactRuntimeAliasPlugin = createRuntimeSpecifierAliasPlugin(
-				{
-					react: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode)),
-				},
-				{ name: `react-plugin-runtime-specifier-alias-${mode}` },
-			);
-			const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter(
-				(plugin): plugin is EcoBuildPlugin => plugin !== null,
-			);
-			const runtimeAliasPlugin = this.createRuntimeAliasPlugin(mode);
-			const mappedSpecifiers = new Set(Object.keys(this.getSpecifierMap(mode)));
-
-			dependencies.push(
-				createBrowserRuntimeModuleAsset({
-					modules: [
-						{ specifier: 'react', defaultExport: true },
-						{ specifier: 'react/jsx-runtime' },
-						{ specifier: 'react/jsx-dev-runtime' },
-					],
-					name: 'react',
-					fileName: this.getReactVendorFileName(mode),
-					cacheDirName: `ecopages-react-runtime-${mode}`,
-					bundleOptions: {
-						define: this.createRuntimeDefines(mode),
-					},
-				}),
-				createBrowserRuntimeModuleAsset({
-					modules: [{ specifier: 'react-dom', defaultExport: true }, { specifier: 'react-dom/client' }],
-					name: 'react-dom',
-					fileName: this.getReactDomVendorFileName(mode),
-					cacheDirName: `ecopages-react-runtime-${mode}`,
-					bundleOptions: {
-						define: this.createRuntimeDefines(mode),
-						plugins: reactDomBundlePlugins,
-					},
-				}),
-			);
-
-			if (this.config.routerAdapter) {
-				const unresolvedExternals = this.config.routerAdapter.bundle.externals.filter(
-					(external) => !mappedSpecifiers.has(external),
-				);
-
-				dependencies.push(
-					createBrowserRuntimeScriptAsset({
-						importPath: this.config.routerAdapter.bundle.importPath,
-						name: this.config.routerAdapter.bundle.outputName,
-						fileName: this.getRouterVendorFileName(mode),
-						bundleOptions: {
-							define: this.createRuntimeDefines(mode),
-							external: unresolvedExternals,
-							plugins: [runtimeAliasPlugin],
-						},
-					}),
-				);
-			}
-		}
-
-		return dependencies;
-	}
-
-	createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode()): EcoBuildPlugin {
-		return createRuntimeSpecifierAliasPlugin(this.getSpecifierMap(mode), {
-			name: `react-plugin-runtime-alias-${mode}`,
-		})!;
-	}
-}