@ecopages/react 0.2.0-alpha.9 → 0.2.0-beta.1

package/src/react.plugin.ts

@@ -1,276 +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 { 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();
-	private runtimeDependenciesInitialized = false;
-	/**
-	 * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
-	 */
-	private explicitGraphEnabled: boolean;
-
-	constructor(options?: Omit<ReactPluginOptions, 'name'>) {
-		const { extensions: _ignoredExtensions, ...restOptions } = options ?? {};
-		const extensions = [...(options?.extensions ?? ['.tsx'])];
-		const mdxExtensions = options?.mdx?.extensions ?? ['.mdx'];
-
-		if (options?.mdx?.enabled) {
-			for (const extension of mdxExtensions) {
-				if (!extensions.includes(extension)) {
-					extensions.push(extension);
-				}
-			}
-		} 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,
-			...restOptions,
-		});
-
-		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;
-	}
-
-	private ensureRuntimeDependencies(): void {
-		if (this.runtimeDependenciesInitialized) {
-			return;
-		}
-
-		this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
-		this.runtimeDependenciesInitialized = true;
-	}
-
-	override get plugins(): EcoBuildPlugin[] {
-		if (this.mdxLoaderPlugin) {
-			return [this.mdxLoaderPlugin];
-		}
-		return [];
-	}
-
-	/**
-	 * Ensures the optional React MDX loader exists before either config-time
-	 * manifest sealing or runtime setup needs it.
-	 */
-	private async ensureMdxLoaderPlugin(): Promise<void> {
-		if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
-			return;
-		}
-
-		const { createReactMdxLoaderPlugin } = await import('./utils/react-mdx-loader-plugin.ts');
-		this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
-	}
-
-	/**
-	 * Prepares React's build-facing loader contributions before config build seals
-	 * the app manifest.
-	 */
-	override async prepareBuildContributions(): Promise<void> {
-		this.ensureRuntimeDependencies();
-		await this.ensureMdxLoaderPlugin();
-	}
-
-	/**
-	 * Performs runtime-only React setup after build contributions are already
-	 * materialized.
-	 */
-	override async setup(): Promise<void> {
-		this.ensureRuntimeDependencies();
-		await this.ensureMdxLoaderPlugin();
-		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.extensions,
-			this.appConfig.templatesExt,
-			this.explicitGraphEnabled,
-		);
-	}
-
-	override getRuntimeSpecifierMap(): Record<string, string> {
-		return 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);
-}

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 through the runtime bare-specifier map.
-		 * @example ['react', 'react-dom', 'react/jsx-runtime']
-		 */
-		externals: string[];
-	};
-
-	/**
-	 * Bare specifier for the runtime mapping 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,108 +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 {
-	buildReactRuntimeSpecifierMap,
-	getReactClientGraphAllowSpecifiers,
-	getReactRuntimeExternalSpecifiers,
-} from '../utils/react-runtime-specifier-map.ts';
-import { createUseSyncExternalStoreShimPlugin } from '../utils/use-sync-external-store-shim-plugin.ts';
-import { createRuntimeSpecifierAliasPlugin } from '@ecopages/core/build/runtime-specifier-alias-plugin';
-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;
-	private readonly config: ReactBundleServiceConfig;
-
-	constructor(config: ReactBundleServiceConfig) {
-		this.config = config;
-		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 runtimeSpecifierMap = buildReactRuntimeSpecifierMap(runtimeImports, this.config.routerAdapter);
-		const options: Record<string, unknown> = {
-			external: getReactRuntimeExternalSpecifiers(),
-			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: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter),
-		});
-
-		const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeSpecifierMap);
-		const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
-			name: 'react-renderer-use-sync-external-store-shim',
-			namespace: 'ecopages-react-renderer-shim',
-		});
-
-		if (isMdx && this.config.mdxCompilerOptions) {
-			const { createReactMdxLoaderPlugin } = await import('../utils/react-mdx-loader-plugin.ts');
-			const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
-			options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin];
-		} else {
-			options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, useSyncExternalStoreShimPlugin];
-		}
-
-		return options;
-	}
-
-	/**
-	 * Creates the esbuild plugin that rewrites bare React specifiers
-	 * to their runtime asset URLs.
-	 */
-	createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>) {
-		return createRuntimeSpecifierAliasPlugin(runtimeSpecifierMap, { name: 'react-runtime-import-alias' });
-	}
-}

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;
-	}
-}