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

package/src/react-renderer.ts

@@ -1,403 +0,0 @@
-/**
- * This module contains the React renderer
- * @module
- */
-
-import type {
-	ComponentRenderInput,
-	ComponentRenderResult,
-	EcoComponent,
-	EcoComponentConfig,
-	EcoPageFile,
-	HtmlTemplateProps,
-	IntegrationRendererRenderOptions,
-	PageMetadataProps,
-	RequestLocals,
-	RouteRendererBody,
-} from '@ecopages/core';
-import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
-import { LocalsAccessError } from '@ecopages/core/errors/locals-access-error';
-import { RESOLVED_ASSETS_DIR } from '@ecopages/core/constants';
-import { rapidhash } from '@ecopages/core/hash';
-import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
-import { createElement, type ReactNode } from 'react';
-import { renderToReadableStream, renderToString } from 'react-dom/server';
-import type { CompileOptions } from '@mdx-js/mdx';
-import { PLUGIN_NAME } from './react.plugin.ts';
-import type { ReactRouterAdapter } from './router-adapter.ts';
-import { hasSingleRootElement } from './utils/html-boundary.ts';
-import { ReactBundleService } from './services/react-bundle.service.ts';
-import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.ts';
-import { ReactPageModuleService } from './services/react-page-module.service.ts';
-import { ReactHydrationAssetService } from './services/react-hydration-asset.service.ts';
-
-type ReactComponentRenderContext = {
-	componentInstanceId?: string;
-};
-
-/**
- * Error thrown when an error occurs while rendering a React component.
- */
-export class ReactRenderError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = 'ReactRenderError';
-	}
-}
-
-/**
- * Error thrown when an error occurs while bundling a React component.
- */
-export class BundleError extends Error {
-	constructor(
-		message: string,
-		public readonly logs: string[],
-	) {
-		super(message);
-		this.name = 'BundleError';
-	}
-}
-
-/**
- * Renderer for React components.
- * @extends IntegrationRenderer
- */
-export class ReactRenderer extends IntegrationRenderer<ReactNode> {
-	name = PLUGIN_NAME;
-	componentDirectory = RESOLVED_ASSETS_DIR;
-	private componentRenderSequence = 0;
-	static routerAdapter: ReactRouterAdapter | undefined;
-	static mdxCompilerOptions: CompileOptions | undefined;
-	static mdxExtensions: string[] = ['.mdx'];
-	static hmrPageMetadataCache: ReactHmrPageMetadataCache | undefined;
-	/**
-	 * Enables explicit graph behavior for React page-entry bundling.
-	 *
-	 * When true, page-entry bundles disable AST server-only stripping and rely
-	 * on explicit dependency declarations for browser graph composition.
-	 */
-	static explicitGraphEnabled = false;
-
-	/** @internal */
-	readonly bundleService: ReactBundleService;
-	/** @internal */
-	readonly pageModuleService: ReactPageModuleService;
-	/** @internal */
-	readonly hydrationAssetService: ReactHydrationAssetService;
-
-	constructor(options: {
-		appConfig: ConstructorParameters<typeof IntegrationRenderer>[0]['appConfig'];
-		assetProcessingService: ConstructorParameters<typeof IntegrationRenderer>[0]['assetProcessingService'];
-		resolvedIntegrationDependencies?: ProcessedAsset[];
-		runtimeOrigin: string;
-	}) {
-		super(options);
-
-		this.bundleService = new ReactBundleService({
-			rootDir: this.appConfig.rootDir,
-			routerAdapter: ReactRenderer.routerAdapter,
-			mdxCompilerOptions: ReactRenderer.mdxCompilerOptions,
-		});
-
-		this.pageModuleService = new ReactPageModuleService({
-			rootDir: this.appConfig.rootDir,
-			distDir: this.appConfig.absolutePaths.distDir,
-			layoutsDir: this.appConfig.absolutePaths.layoutsDir,
-			componentsDir: this.appConfig.absolutePaths.componentsDir,
-			mdxCompilerOptions: ReactRenderer.mdxCompilerOptions,
-			mdxExtensions: ReactRenderer.mdxExtensions,
-			integrationName: this.name,
-			hasRouterAdapter: Boolean(ReactRenderer.routerAdapter),
-		});
-
-		this.hydrationAssetService = new ReactHydrationAssetService({
-			srcDir: this.appConfig.srcDir,
-			routerAdapter: ReactRenderer.routerAdapter,
-			assetProcessingService: this.assetProcessingService,
-			bundleService: this.bundleService,
-			hmrPageMetadataCache: ReactRenderer.hmrPageMetadataCache,
-		});
-	}
-
-	protected override shouldRenderPageComponent(): boolean {
-		return false;
-	}
-
-	/**
-	 * Renders a React component for component-level orchestration.
-	 *
-	 * Behavior:
-	 * - SSR always returns the component's own root HTML (no synthetic wrapper).
-	 * - For single-root output, a stable `data-eco-component-id` attribute is attached
-	 *   to the root element so the client island runtime can target it directly.
-	 * - Island client scripts are emitted through `assets` and mounted independently.
-	 *
-	 * This preserves DOM shape for global CSS/layout selectors while keeping a
-	 * deterministic mount target per component instance.
-	 */
-	override async renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult> {
-		const Component = input.component as unknown as React.FunctionComponent;
-		const componentConfig = input.component.config;
-		const element =
-			input.children === undefined
-				? createElement(Component, input.props)
-				: createElement(Component, input.props, input.children);
-		let html = renderToString(element);
-		let canAttachAttributes = hasSingleRootElement(html);
-		let rootTag = this.getRootTagName(html);
-		const componentFile = componentConfig?.__eco?.file;
-		const context = (input.integrationContext as ReactComponentRenderContext | undefined) ?? {};
-
-		let rootAttributes: Record<string, string> | undefined;
-		let assets: ProcessedAsset[] | undefined;
-
-		if (canAttachAttributes && componentFile && this.assetProcessingService) {
-			const componentInstanceId =
-				context.componentInstanceId ??
-				`eco-component-${rapidhash(componentFile)}-${++this.componentRenderSequence}`;
-			assets = await this.hydrationAssetService.buildComponentRenderAssets(
-				componentFile,
-				componentInstanceId,
-				input.props,
-				componentConfig,
-			);
-			rootAttributes = { 'data-eco-component-id': componentInstanceId };
-		}
-
-		return {
-			html,
-			canAttachAttributes,
-			rootTag,
-			integrationName: this.name,
-			rootAttributes,
-			assets,
-		};
-	}
-
-	/**
-	 * 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
-	 */
-	public isMdxFile(filePath: string): boolean {
-		return this.pageModuleService.isMdxFile(filePath);
-	}
-
-	/**
-	 * Processes MDX-specific configuration dependencies including layout dependencies.
-	 * @param pagePath - Absolute path to the MDX page file
-	 * @returns Processed assets for MDX configuration dependencies
-	 */
-	private async processMdxConfigDependencies(pagePath: string): Promise<ProcessedAsset[]> {
-		const { config } = await this.importPageFile(pagePath);
-		const resolvedLayout = config?.layout;
-		const components: Partial<EcoComponent>[] = [];
-
-		if (resolvedLayout?.config?.dependencies) {
-			const layoutConfig = this.pageModuleService.ensureConfigFileMetadata(resolvedLayout.config, pagePath);
-			components.push({ config: layoutConfig });
-		}
-
-		if (config?.dependencies) {
-			const configWithMeta = {
-				...config,
-				__eco: { id: rapidhash(pagePath).toString(36), file: pagePath, integration: 'react' },
-			};
-			components.push({ config: configWithMeta });
-		}
-
-		return this.processComponentDependencies(components);
-	}
-
-	override async buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]> {
-		try {
-			const pageModule = (await this.importPageFile(pagePath)) as EcoPageFile<{ config?: EcoComponentConfig }> & {
-				config?: EcoComponentConfig;
-			};
-			const shouldHydrate = ReactRenderer.explicitGraphEnabled
-				? true
-				: this.pageModuleService.shouldHydratePage(pageModule);
-			if (!shouldHydrate) {
-				return [];
-			}
-
-			const isMdx = this.pageModuleService.isMdxFile(pagePath);
-			const declaredModules = this.pageModuleService.collectPageDeclaredModules(pageModule);
-			const processedAssets = await this.hydrationAssetService.buildRouteRenderAssets(
-				pagePath,
-				isMdx,
-				declaredModules,
-			);
-
-			if (isMdx) {
-				const mdxConfigAssets = await this.processMdxConfigDependencies(pagePath);
-				return [...processedAssets, ...mdxConfigAssets];
-			}
-
-			return processedAssets;
-		} catch (error) {
-			if (error instanceof BundleError) {
-				console.error('[ecopages] Bundle errors:', error.logs);
-			}
-
-			throw new ReactRenderError(
-				`Failed to generate hydration script: ${error instanceof Error ? error.message : String(error)}`,
-			);
-		}
-	}
-
-	protected override async importPageFile(file: string): Promise<EcoPageFile<{ config?: EcoComponentConfig }>> {
-		const module = (
-			this.pageModuleService.isMdxFile(file)
-				? await this.pageModuleService.importMdxPageFile(file)
-				: await super.importPageFile(file)
-		) as EcoPageFile<{ config?: EcoComponentConfig }> & {
-			config?: EcoComponentConfig;
-		};
-		const { default: Page, getMetadata, config } = module;
-
-		if (this.pageModuleService.isMdxFile(file) && config) {
-			Page.config = config;
-		}
-
-		return {
-			default: Page,
-			getMetadata,
-			config,
-		};
-	}
-
-	async render({
-		params,
-		query,
-		props,
-		locals,
-		pageLocals,
-		metadata,
-		Page,
-		Layout,
-		HtmlTemplate,
-		pageProps,
-	}: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody> {
-		try {
-			const pageElement = createElement(Page, { params, query, ...props, locals: pageLocals });
-			const contentElement = Layout
-				? createElement(Layout as React.FunctionComponent, { locals } as object, pageElement)
-				: pageElement;
-
-			const safeLocals = this.getSerializableLocals(locals as RequestLocals);
-			const allPageProps: HtmlTemplateProps['pageProps'] = {
-				...pageProps,
-				params,
-				query,
-				...(safeLocals && { locals: safeLocals }),
-			};
-
-			return await renderToReadableStream(
-				createElement(
-					HtmlTemplate,
-					{
-						metadata,
-						pageProps: allPageProps,
-					} as HtmlTemplateProps,
-					contentElement,
-				),
-			);
-		} catch (error) {
-			throw this.createRenderError('Failed to render component', error);
-		}
-	}
-
-	/**
-	 * Safely extracts locals for client-side hydration.
-	 *
-	 * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
-	 * request-scoped data (e.g., session). This data needs to be serialized to the
-	 * client for hydration to match the server-rendered output.
-	 *
-	 * On static pages, `locals` is a Proxy that throws `LocalsAccessError` on access
-	 * to prevent accidental use. This method safely detects that case and returns
-	 * `undefined` instead of throwing.
-	 *
-	 * @param locals - The locals object from the render context
-	 * @returns The locals object if serializable, undefined otherwise
-	 */
-	private getSerializableLocals(locals: RequestLocals): RequestLocals | undefined {
-		try {
-			if (locals && Object.keys(locals).length > 0) {
-				return locals;
-			}
-			return undefined;
-		} catch (e) {
-			if (e instanceof LocalsAccessError) {
-				return undefined;
-			}
-			throw e;
-		}
-	}
-
-	async renderToResponse<P = Record<string, unknown>>(
-		view: EcoComponent<P>,
-		props: P,
-		ctx: RenderToResponseContext,
-	): Promise<Response> {
-		try {
-			const viewConfig = view.config;
-			const Layout = viewConfig?.layout as React.FunctionComponent | undefined;
-
-			const ViewComponent = view as unknown as React.FunctionComponent;
-			const pageElement = createElement(ViewComponent, props || {});
-
-			if (ctx.partial) {
-				const stream = await renderToReadableStream(pageElement);
-				return this.createHtmlResponse(stream, ctx);
-			}
-
-			const contentElement = Layout
-				? createElement(Layout as React.FunctionComponent, {}, pageElement)
-				: pageElement;
-
-			const HtmlTemplate = await this.getHtmlTemplate();
-			const metadata: PageMetadataProps = view.metadata
-				? await view.metadata({
-						params: {},
-						query: {},
-						props,
-						appConfig: this.appConfig,
-					})
-				: this.appConfig.defaultMetadata;
-
-			await this.prepareViewDependencies(view, Layout as unknown as EcoComponent | undefined);
-
-			const viewFilePath = viewConfig?.__eco?.file;
-			if (viewFilePath) {
-				const hydrationAssets = await this.buildRouteRenderAssets(viewFilePath);
-				this.htmlTransformer.setProcessedDependencies([
-					...this.htmlTransformer.getProcessedDependencies(),
-					...hydrationAssets,
-				]);
-			}
-
-			const streamBody = await renderToReadableStream(
-				createElement(
-					HtmlTemplate,
-					{
-						metadata,
-						pageProps: props,
-					} as HtmlTemplateProps,
-					contentElement,
-				),
-			);
-
-			const transformedResponse = await this.htmlTransformer.transform(
-				new Response(streamBody, {
-					headers: { 'Content-Type': 'text/html' },
-				}),
-			);
-
-			return this.createHtmlResponse(transformedResponse.body ?? '', ctx);
-		} catch (error) {
-			throw this.createRenderError('Failed to render view', error);
-		}
-	}
-}

package/src/react.plugin.ts

@@ -1,241 +0,0 @@
-/**
- * This module contains the react plugin for Ecopages
- * @module
- */
-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';
-import type React from 'react';
-import { ReactRenderer } from './react-renderer.ts';
-import { ReactHmrStrategy } from './react-hmr-strategy.ts';
-import type { ReactRouterAdapter } from './router-adapter.ts';
-import type { ComponentBoundaryPolicyInput } from '@ecopages/core/plugins/integration-plugin';
-import { ReactRuntimeBundleService } from './services/react-runtime-bundle.service.ts';
-import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.ts';
-
-const appLogger = new Logger('[ReactPlugin]');
-
-/**
- * MDX configuration options for the React plugin
- */
-export type ReactMdxOptions = {
-	/**
-	 * Whether to enable MDX support.
-	 * @default false
-	 */
-	enabled: boolean;
-	/**
-	 * Compiler options for MDX.
-	 * @default undefined
-	 */
-	compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
-	/**
-	 * Remark plugins.
-	 * @default undefined
-	 */
-	remarkPlugins?: CompileOptions['remarkPlugins'];
-	/**
-	 * Rehype plugins.
-	 * @default undefined
-	 */
-	rehypePlugins?: CompileOptions['rehypePlugins'];
-	/**
-	 * Recma plugins.
-	 * @default undefined
-	 */
-	recmaPlugins?: CompileOptions['recmaPlugins'];
-	/**
-	 * Custom extensions to be treated as MDX files.
-	 * @default ['.mdx']
-	 */
-	extensions?: string[];
-};
-
-/**
- * Options for the React plugin
- */
-export type ReactPluginOptions = {
-	extensions?: string[];
-	dependencies?: AssetDefinition[];
-	/**
-	 * Enables explicit client graph mode for React page entries.
-	 *
-	 * When enabled, React page-entry bundling relies on explicit dependency declarations
-	 * and skips AST-based `middleware`/`requires` stripping in the React path.
-	 * @default false
-	 */
-	explicitGraph?: boolean;
-	/**
-	 * Router adapter for SPA navigation.
-	 * When provided, pages with layouts will be wrapped in the router for client-side navigation.
-	 * @example
-	 * ```ts
-	 * import { ecoRouter } from '@ecopages/react-router';
-	 * reactPlugin({ router: ecoRouter() })
-	 * ```
-	 */
-	router?: ReactRouterAdapter;
-	/**
-	 * MDX configuration for handling .mdx files within the React plugin.
-	 * When enabled, MDX files are treated as React pages with full router support.
-	 * @example
-	 * ```ts
-	 * reactPlugin({
-	 *   router: ecoRouter(),
-	 *   mdx: {
-	 *     enabled: true,
-	 *     extensions: ['.mdx', '.md'],
-	 *     remarkPlugins: [remarkGfm],
-	 *     rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
-	 *   }
-	 * })
-	 * ```
-	 */
-	mdx?: ReactMdxOptions;
-};
-
-/**
- * The name of the React plugin
- */
-export const PLUGIN_NAME = 'react';
-
-/**
- * The React plugin class
- * This plugin provides support for React components in Ecopages
- */
-export class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
-	renderer = ReactRenderer;
-	routerAdapter: ReactRouterAdapter | undefined;
-	private mdxEnabled: boolean;
-	private mdxCompilerOptions?: CompileOptions;
-	private mdxExtensions: string[];
-	private mdxLoaderPlugin: EcoBuildPlugin | undefined;
-	private runtimeBundleService: ReactRuntimeBundleService;
-	private readonly hmrPageMetadataCache = new ReactHmrPageMetadataCache();
-	/**
-	 * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
-	 */
-	private explicitGraphEnabled: boolean;
-
-	constructor(options?: Omit<ReactPluginOptions, 'name'>) {
-		const extensions = ['.tsx'];
-		const mdxExtensions = options?.mdx?.extensions ?? ['.mdx'];
-
-		if (options?.mdx?.enabled) {
-			extensions.push(...mdxExtensions);
-		} 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.',
-			);
-		}
-
-		super({
-			name: PLUGIN_NAME,
-			extensions,
-			...options,
-		});
-
-		this.mdxEnabled = options?.mdx?.enabled ?? false;
-		this.mdxExtensions = mdxExtensions;
-
-		if (this.mdxEnabled) {
-			const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = options?.mdx || {};
-			this.mdxCompilerOptions = {
-				...compilerOptions,
-				remarkPlugins: [...(compilerOptions?.remarkPlugins || []), ...(remarkPlugins || [])],
-				rehypePlugins: [...(compilerOptions?.rehypePlugins || []), ...(rehypePlugins || [])],
-				recmaPlugins: [...(compilerOptions?.recmaPlugins || []), ...(recmaPlugins || [])],
-				jsxImportSource: 'react',
-				jsxRuntime: 'automatic',
-				development: process.env.NODE_ENV === 'development',
-			};
-			appLogger.debug('MDX mode enabled with React jsx runtime');
-		}
-
-		this.routerAdapter = options?.router;
-		this.runtimeBundleService = new ReactRuntimeBundleService({
-			routerAdapter: this.routerAdapter,
-		});
-		this.explicitGraphEnabled = options?.explicitGraph ?? false;
-		ReactRenderer.routerAdapter = this.routerAdapter;
-		ReactRenderer.mdxCompilerOptions = this.mdxCompilerOptions;
-		ReactRenderer.mdxExtensions = this.mdxExtensions;
-		ReactRenderer.explicitGraphEnabled = this.explicitGraphEnabled;
-		ReactRenderer.hmrPageMetadataCache = this.hmrPageMetadataCache;
-		this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
-	}
-
-	override get plugins(): EcoBuildPlugin[] {
-		if (this.mdxLoaderPlugin) {
-			return [this.mdxLoaderPlugin];
-		}
-		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);
-		}
-		await super.setup();
-	}
-
-	/**
-	 * Provides React-specific HMR strategy with Fast Refresh support.
-	 *
-	 * The strategy shares a React-only page metadata cache with the renderer so
-	 * save-time rebuilds can reuse declared-module analysis without expanding the
-	 * core HMR interfaces.
-	 *
-	 * @returns ReactHmrStrategy instance for handling React component updates
-	 */
-	override getHmrStrategy(): HmrStrategy | undefined {
-		if (!this.hmrManager || !this.appConfig) {
-			return undefined;
-		}
-
-		const context = this.hmrManager.getDefaultContext();
-
-		return new ReactHmrStrategy(
-			context,
-			this.hmrPageMetadataCache,
-			this.mdxCompilerOptions,
-			this.explicitGraphEnabled,
-		);
-	}
-
-	/**
-	 * Override to register React-specific specifier mappings for HMR.
-	 */
-	override setHmrManager(hmrManager: IHmrManager): void {
-		super.setHmrManager(hmrManager);
-		hmrManager.registerSpecifierMap(this.runtimeBundleService.getSpecifierMap());
-	}
-
-	/**
-	 * Declares React's boundary deferral rule for cross-integration rendering.
-	 *
-	 * React defers when a render pass owned by another integration enters a React
-	 * component boundary. That boundary is then resolved later through the marker
-	 * graph stage using the React renderer.
-	 *
-	 * @param input Boundary metadata for the active render pass.
-	 * @returns `true` when the boundary should be deferred into the marker pass.
-	 */
-	override shouldDeferComponentBoundary(input: ComponentBoundaryPolicyInput): boolean {
-		return input.targetIntegration === this.name && input.currentIntegration !== this.name;
-	}
-}
-
-/**
- * Factory function to create a React plugin instance
- * @param options Configuration options for the React plugin
- * @returns A new ReactPlugin instance
- */
-export function reactPlugin(options?: ReactPluginOptions): ReactPlugin {
-	return new ReactPlugin(options);
-}