@ecopages/react 0.2.0-alpha.1

package/src/react-hmr-strategy.ts

@@ -0,0 +1,444 @@
+/**
+ * React HMR Strategy
+ *
+ * Handles hot module replacement for React components.
+ * Triggers module invalidation on changes to ensure fresh component re-renders.
+ *
+ * @module
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import { defaultBuildAdapter } from '@ecopages/core/build/build-adapter';
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { FileNotFoundError, fileSystem } from '@ecopages/file-system';
+import { Logger } from '@ecopages/logger';
+import type { DefaultHmrContext, EcoComponentConfig } from '@ecopages/core';
+import type { CompileOptions } from '@mdx-js/mdx';
+import { injectHmrHandler } from './utils/hmr-scripts.ts';
+import { createClientGraphBoundaryPlugin } from './utils/client-graph-boundary-plugin.ts';
+import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from './utils/declared-modules.ts';
+import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.ts';
+
+const appLogger = new Logger('[ReactHmrStrategy]');
+
+/**
+ * Strategy for handling React component HMR updates.
+ *
+ * This strategy provides React-specific HMR handling by rebuilding entrypoints
+ * and injecting HMR acceptance handlers that trigger module invalidation.
+ *
+ * The processing steps are:
+ * 1. Check if any React entrypoints are registered
+ * 2. Rebuild all React entrypoints (the changed file could be a dependency)
+ * 3. Replace bare specifiers with runtime URLs
+ * 4. Inject HMR acceptance handler
+ * 5. Broadcast update events for each rebuilt entrypoint
+ *
+ * @remarks
+ * This strategy has higher priority than generic JsHmrStrategy, allowing it
+ * to handle React files specially while falling back to generic handling for
+ * non-React files.
+ *
+ * Future enhancement: Track dependencies using Bun's transpiler API to only
+ * rebuild affected entrypoints instead of all of them.
+ *
+ * @see https://bun.sh/docs/runtime/transpiler
+ *
+ * @example
+ * ```typescript
+ * const context = {
+ *   getWatchedFiles: () => watchedFilesMap,
+ *   getSpecifierMap: () => specifierMap,
+ *   getDistDir: () => '/path/to/dist/_hmr',
+ *   getPlugins: () => [],
+ *   getSrcDir: () => '/path/to/src',
+ *   getLayoutsDir: () => '/path/to/src/layouts'
+ * };
+ * const strategy = new ReactHmrStrategy(context);
+ * ```
+ */
+export class ReactHmrStrategy extends HmrStrategy {
+	readonly type = HmrStrategyType.INTEGRATION;
+	private mdxCompilerOptions?: CompileOptions;
+	private readonly knownEntrypoints = new Set<string>();
+
+	private async importNodePageModule(entrypointPath: string): Promise<{
+		default?: { config?: EcoComponentConfig };
+		config?: EcoComponentConfig;
+	}> {
+		const srcDir = this.context.getSrcDir();
+		const rootDir = path.dirname(srcDir);
+		const outdir = path.join(path.resolve(this.context.getDistDir(), '..', '..'), '.server-modules');
+		const fileBaseName = path.basename(entrypointPath, path.extname(entrypointPath));
+		const fileHash = fileSystem.hash(entrypointPath);
+		const outputFileName = `${fileBaseName}-${fileHash}.js`;
+
+		const buildResult = await defaultBuildAdapter.build({
+			entrypoints: [entrypointPath],
+			root: rootDir,
+			outdir,
+			target: 'node',
+			format: 'esm',
+			sourcemap: 'none',
+			splitting: false,
+			minify: false,
+			naming: outputFileName,
+		});
+
+		if (!buildResult.success) {
+			const details = buildResult.logs.map((log) => log.message).join(' | ');
+			throw new Error(`Error transpiling React HMR 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 transpiled output generated for React HMR page module: ${entrypointPath}`);
+		}
+
+		return (await import(pathToFileURL(compiledOutput).href)) as {
+			default?: { config?: EcoComponentConfig };
+			config?: EcoComponentConfig;
+		};
+	}
+
+	private createUseSyncExternalStoreShimPlugin(): EcoBuildPlugin {
+		return {
+			name: 'react-hmr-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-hmr-shim',
+				}));
+
+				build.onLoad(
+					{ filter: /^use-sync-external-store\/shim$/, namespace: 'ecopages-react-hmr-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',
+					}),
+				);
+			},
+		};
+	}
+
+	/**
+	 * Creates a new React HMR strategy instance.
+	 *
+	 * @param context - The HMR context providing access to watched files, plugins, build directories,
+	 *                  and the layouts directory for detecting layout file changes that require full
+	 *                  page reloads instead of module-level HMR updates.
+	 * @param pageMetadataCache - React-only cache of declared browser modules discovered during
+	 *                            server rendering. This avoids re-importing unchanged page modules
+	 *                            during save-time Fast Refresh rebuilds.
+	 * @param mdxCompilerOptions - Optional MDX compiler options for processing .mdx files
+	 * @param explicitGraphEnabled - Enables explicit graph mode for React HMR bundling.
+	 * In explicit mode, HMR builds omit AST server-only stripping plugins in React paths.
+	 */
+	constructor(
+		private context: DefaultHmrContext,
+		private pageMetadataCache: ReactHmrPageMetadataCache,
+		mdxCompilerOptions?: CompileOptions,
+		private explicitGraphEnabled = false,
+	) {
+		super();
+		this.mdxCompilerOptions = mdxCompilerOptions;
+	}
+
+	/**
+	 * Returns build plugins for React HMR bundling.
+	 *
+	 * Includes the client graph boundary plugin to prevent undeclared imports
+	 * (including `node:*`) from breaking the browser bundle.
+	 */
+	private getBuildPlugins(declaredModules?: string[]): EcoBuildPlugin[] {
+		const allowSpecifiers = [
+			'@ecopages/core',
+			'react',
+			'react-dom',
+			'react/jsx-runtime',
+			'react/jsx-dev-runtime',
+			'react-dom/client',
+			...Array.from(this.context.getSpecifierMap().keys()),
+		];
+
+		return [
+			createClientGraphBoundaryPlugin({
+				absWorkingDir: path.dirname(this.context.getSrcDir()),
+				alwaysAllowSpecifiers: allowSpecifiers,
+				declaredModules,
+			}),
+			...this.context.getPlugins(),
+			this.createUseSyncExternalStoreShimPlugin(),
+		];
+	}
+
+	private isReactEntrypoint(filePath: string): boolean {
+		if (filePath.endsWith('.tsx')) {
+			return true;
+		}
+
+		return filePath.endsWith('.mdx') && this.mdxCompilerOptions !== undefined;
+	}
+
+	/**
+	 * Determines if the file is a React/MDX entrypoint that's registered for HMR.
+	 *
+	 * @param filePath - Absolute path to the changed file
+	 * @returns True if this is a registered React or MDX entrypoint
+	 */
+	matches(filePath: string): boolean {
+		const watchedFiles = this.context.getWatchedFiles();
+		appLogger.debug(`Checking ${filePath}. Watched: ${watchedFiles.size}`);
+		if (watchedFiles.size === 0) {
+			return false;
+		}
+
+		return this.isReactEntrypoint(filePath);
+	}
+
+	/**
+	 * Checks if a file is a layout file.
+	 *
+	 * Layout files require special HMR handling because they wrap multiple pages and affect
+	 * the entire page structure. When a layout changes, we trigger a 'layout-update' event
+	 * instead of a regular 'update' event, which instructs the browser to perform a full
+	 * page reload (or clear cache and re-render) rather than attempting module-level HMR.
+	 *
+	 * @param filePath - Absolute path to the file
+	 * @returns True if the file is in the layouts directory
+	 */
+	private isLayoutFile(filePath: string): boolean {
+		return filePath.startsWith(this.context.getLayoutsDir());
+	}
+
+	/**
+	 * Processes a React file change by rebuilding all React entrypoints.
+	 *
+	 * For layout files, broadcasts a 'layout-update' event to trigger full page reload.
+	 * For regular components/pages, broadcasts 'update' events for module-level HMR.
+	 * When a page entrypoint is first registered, only that entrypoint is built.
+	 * Subsequent file updates rebuild all watched React entrypoints as usual.
+	 *
+	 * @param _filePath - Absolute path to the changed file
+	 * @returns Action to broadcast update events (layout-update for layouts, update for components)
+	 */
+	async process(_filePath: string): Promise<HmrAction> {
+		appLogger.debug(`Processing ${_filePath}`);
+		const watchedFiles = this.context.getWatchedFiles();
+
+		if (watchedFiles.size === 0) {
+			appLogger.debug(`No watched files`);
+			return { type: 'none' };
+		}
+
+		const isLayout = this.isLayoutFile(_filePath);
+		if (isLayout) {
+			appLogger.debug(`Detected layout file change: ${_filePath}`);
+		}
+
+		const entrypointsToBuild =
+			!this.knownEntrypoints.has(_filePath) && watchedFiles.has(_filePath)
+				? [[_filePath, watchedFiles.get(_filePath)!]]
+				: watchedFiles.entries();
+		this.knownEntrypoints.add(_filePath);
+
+		const updates: string[] = [];
+		for (const [entrypoint, outputUrl] of entrypointsToBuild) {
+			if (!this.isReactEntrypoint(entrypoint)) {
+				continue;
+			}
+
+			appLogger.debug(`Bundling ${entrypoint}`);
+			const success = await this.bundleReactEntrypoint(entrypoint, outputUrl);
+			if (success) {
+				updates.push(outputUrl);
+			}
+		}
+
+		if (updates.length > 0) {
+			if (isLayout) {
+				appLogger.debug(`Layout update detected, sending layout-update event`);
+				return {
+					type: 'broadcast',
+					events: [
+						{
+							type: 'layout-update',
+						},
+					],
+				};
+			}
+
+			appLogger.debug(`Broadcasting ${updates.length} updates`);
+			return {
+				type: 'broadcast',
+				events: updates.map((path) => ({
+					type: 'update',
+					path,
+					timestamp: Date.now(),
+				})),
+			};
+		}
+
+		appLogger.debug(`No updates generated`);
+		return { type: 'none' };
+	}
+
+	/**
+	 * Bundles a single React/MDX entrypoint with HMR support.
+	 *
+	 * @param entrypointPath - Absolute path to the source file
+	 * @param outputUrl - URL path for the bundled file
+	 * @returns True if bundling was successful
+	 */
+	private async bundleReactEntrypoint(entrypointPath: string, outputUrl: string): Promise<boolean> {
+		try {
+			const isMdx = entrypointPath.endsWith('.mdx');
+			const srcDir = this.context.getSrcDir();
+			const relativePath = path.relative(srcDir, entrypointPath);
+			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx)$/, '.js');
+			const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+			const outputPath = path.join(this.context.getDistDir(), encodedPathJs);
+			const tempDir = path.dirname(outputPath);
+
+			const declaredModules = this.pageMetadataCache.getDeclaredModules(entrypointPath)
+				? this.pageMetadataCache.getDeclaredModules(entrypointPath)!
+				: isMdx
+					? await collectPageDeclaredModules(entrypointPath)
+					: collectPageDeclaredModulesFromModule(await this.importNodePageModule(entrypointPath));
+			const plugins = this.getBuildPlugins(declaredModules);
+
+			if (isMdx && this.mdxCompilerOptions) {
+				const { createReactMdxLoaderPlugin } = await import('./utils/react-mdx-loader-plugin.ts');
+				const mdxPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+				plugins.unshift(mdxPlugin);
+			}
+
+			const result = await defaultBuildAdapter.build({
+				entrypoints: [entrypointPath],
+				outdir: tempDir,
+				naming: `[name].[hash].tmp`,
+				target: 'browser',
+				format: 'esm',
+				sourcemap: 'none',
+				plugins,
+				minify: false,
+				external: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom/client'],
+			});
+
+			if (!result.success) {
+				appLogger.error(`Failed to build ${entrypointPath}:`, result.logs);
+				return false;
+			}
+
+			const tempFile = result.outputs[0]?.path;
+			if (!tempFile) {
+				appLogger.error(`No output file generated for ${entrypointPath}`);
+				return false;
+			}
+
+			const processed = await this.processOutput(tempFile, outputPath, outputUrl);
+			return processed;
+		} catch (error) {
+			appLogger.error(`Error bundling ${entrypointPath}:`, error as Error);
+			return false;
+		}
+	}
+
+	/**
+	 * Encodes dynamic route segments (brackets) in file paths.
+	 * Converts `[slug]` to `_slug_` to avoid filesystem issues.
+	 */
+	private encodeDynamicSegments(filepath: string): string {
+		return filepath.replace(/\[([^\]]+)\]/g, '_$1_');
+	}
+
+	/**
+	 * Processes bundled output by replacing specifiers and injecting HMR handler.
+	 * Writes to temp file first, then renames atomically to avoid conflicts.
+	 *
+	 * @param tempPath - Path to the temporary bundled file
+	 * @param finalPath - Final destination path
+	 * @param url - URL path for logging
+	 * @returns True if processing was successful
+	 */
+	private async processOutput(tempPath: string, finalPath: string, url: string): Promise<boolean> {
+		if (!fileSystem.exists(tempPath)) {
+			appLogger.debug(`Skipping stale temp output for ${url}: ${tempPath}`);
+			return false;
+		}
+
+		try {
+			let code = await fileSystem.readFile(tempPath);
+
+			code = this.replaceBareSpecifiers(code);
+			code = injectHmrHandler(code);
+
+			await fileSystem.writeAsync(finalPath, code);
+			await fileSystem.removeAsync(tempPath).catch(() => {});
+
+			appLogger.debug(`Processed ${url} with HMR handler`);
+			return true;
+		} catch (error) {
+			if (
+				error instanceof FileNotFoundError ||
+				(error instanceof Error && error.message.includes('not found')) ||
+				(error instanceof Error && 'code' in error && error.code === 'ENOENT')
+			) {
+				appLogger.debug(`Skipping stale temp output for ${url}: ${tempPath}`);
+				await fileSystem.removeAsync(tempPath).catch(() => {});
+				return false;
+			}
+
+			appLogger.error(`Error processing output for ${url}:`, error as Error);
+			await fileSystem.removeAsync(tempPath).catch(() => {});
+			return false;
+		}
+	}
+
+	/**
+	 * Replaces bare specifiers with runtime URLs.
+	 *
+	 * Handles both static imports and dynamic imports.
+	 *
+	 * @param code - The bundled code to transform
+	 * @returns The transformed code with runtime URLs
+	 */
+	private replaceBareSpecifiers(code: string): string {
+		const specifierMap = this.context.getSpecifierMap();
+
+		if (specifierMap.size === 0) {
+			return code;
+		}
+
+		let result = code;
+		for (const [bareSpec, runtimeUrl] of specifierMap.entries()) {
+			const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+			result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, 'g'), `from "${runtimeUrl}"`);
+			result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, 'g'), `import("${runtimeUrl}")`);
+		}
+
+		return result;
+	}
+}

package/src/react-renderer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * This module contains the React renderer
+ * @module
+ */
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
+import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
+import { type ReactNode } from 'react';
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { ReactRouterAdapter } from './router-adapter.js';
+import { ReactBundleService } from './services/react-bundle.service.js';
+import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+import { ReactPageModuleService } from './services/react-page-module.service.js';
+import { ReactHydrationAssetService } from './services/react-hydration-asset.service.js';
+/**
+ * Error thrown when an error occurs while rendering a React component.
+ */
+export declare class ReactRenderError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when an error occurs while bundling a React component.
+ */
+export declare class BundleError extends Error {
+    readonly logs: string[];
+    constructor(message: string, logs: string[]);
+}
+/**
+ * Renderer for React components.
+ * @extends IntegrationRenderer
+ */
+export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
+    name: string;
+    componentDirectory: string;
+    private componentRenderSequence;
+    static routerAdapter: ReactRouterAdapter | undefined;
+    static mdxCompilerOptions: CompileOptions | undefined;
+    static mdxExtensions: string[];
+    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: boolean;
+    /** @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;
+    });
+    protected shouldRenderPageComponent(): boolean;
+    /**
+     * 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.
+     */
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    /**
+     * 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;
+    /**
+     * 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 processMdxConfigDependencies;
+    buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
+    protected importPageFile(file: string): Promise<EcoPageFile<{
+        config?: EcoComponentConfig;
+    }>>;
+    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
+    /**
+     * 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;
+    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+}