@ecopages/react 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/react.constants.d.ts

@@ -0,0 +1 @@
+export declare const REACT_PLUGIN_NAME = "react";

package/src/react.constants.js

@@ -0,0 +1,4 @@
+const REACT_PLUGIN_NAME = "react";
+export {
+  REACT_PLUGIN_NAME
+};

package/src/react.plugin.d.ts

@@ -1,94 +1,10 @@
-/**
- * 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 type { CompileOptions } from '@mdx-js/mdx';
 import type React from 'react';
 import { ReactRenderer } from './react-renderer.js';
-import type { ReactRouterAdapter } from './router-adapter.js';
-import type { ComponentBoundaryPolicyInput } from '@ecopages/core/plugins/integration-plugin';
-/**
- * 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;
-};
+import type { ReactPluginOptions } from './react.types.js';
+export type { ReactMdxOptions, ReactPluginOptions, ReactRendererConfig } from './react.types.js';
 /**
  * The name of the React plugin
  */
@@ -99,19 +15,46 @@ export declare const PLUGIN_NAME = "react";
  */
 export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
     renderer: typeof ReactRenderer;
-    routerAdapter: ReactRouterAdapter | undefined;
-    private mdxEnabled;
-    private mdxCompilerOptions?;
-    private mdxExtensions;
+    private readonly routerAdapter;
+    private readonly mdxEnabled;
+    private readonly mdxCompilerOptions?;
+    private readonly mdxExtensions;
     private mdxLoaderPlugin;
-    private runtimeBundleService;
+    private readonly runtimeBundleService;
     private readonly hmrPageMetadataCache;
+    private runtimeDependenciesInitialized;
     /**
      * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
      */
-    private explicitGraphEnabled;
-    constructor(options?: Omit<ReactPluginOptions, 'name'>);
+    private readonly explicitGraphEnabled;
+    private readonly rendererConfig;
+    constructor(options?: ReactPluginOptions);
+    /**
+     * Creates a React renderer with instance-owned runtime configuration.
+     *
+     * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
+     * Keeping that state on the instance avoids cross-plugin static mutation while
+     * preserving the same runtime services the base initializer wires up.
+     */
+    initializeRenderer(options?: {
+        rendererModules?: unknown;
+    }): ReactRenderer;
+    private ensureRuntimeDependencies;
     get plugins(): EcoBuildPlugin[];
+    /**
+     * Ensures the optional React MDX loader exists before either config-time
+     * manifest sealing or runtime setup needs it.
+     */
+    private ensureMdxLoaderPlugin;
+    /**
+     * Prepares React's build-facing loader contributions before config build seals
+     * the app manifest.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Performs runtime-only React setup after build contributions are already
+     * materialized.
+     */
     setup(): Promise<void>;
     /**
      * Provides React-specific HMR strategy with Fast Refresh support.
@@ -123,21 +66,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
      * @returns ReactHmrStrategy instance for handling React component updates
      */
     getHmrStrategy(): HmrStrategy | undefined;
-    /**
-     * Override to register React-specific specifier mappings for HMR.
-     */
-    setHmrManager(hmrManager: IHmrManager): void;
-    /**
-     * 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.
-     */
-    shouldDeferComponentBoundary(input: ComponentBoundaryPolicyInput): boolean;
+    getRuntimeSpecifierMap(): Record<string, string>;
 }
 /**
  * Factory function to create a React plugin instance

package/src/react.plugin.js

@@ -1,11 +1,65 @@
 import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
 import { Logger } from "@ecopages/logger";
+import { REACT_PLUGIN_NAME } from "./react.constants.js";
 import { ReactRenderer } from "./react-renderer.js";
 import { ReactHmrStrategy } from "./react-hmr-strategy.js";
 import { ReactRuntimeBundleService } from "./services/react-runtime-bundle.service.js";
 import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
 const appLogger = new Logger("[ReactPlugin]");
-const PLUGIN_NAME = "react";
+const PLUGIN_NAME = REACT_PLUGIN_NAME;
+const mergePluginLists = (...lists) => {
+  const merged = lists.flatMap((list) => list ? [...list] : []);
+  return merged.length > 0 ? merged : void 0;
+};
+const appendMdxExtensions = (target, mdxExtensions) => {
+  for (const extension of mdxExtensions) {
+    if (!target.includes(extension)) {
+      target.push(extension);
+    }
+  }
+};
+const resolveReactMdxCompilerOptions = (mdxOptions) => {
+  const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
+  const resolved = {
+    ...compilerOptions,
+    jsxImportSource: "react",
+    jsxRuntime: "automatic",
+    development: process.env.NODE_ENV === "development"
+  };
+  const mergedRemark = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
+  const mergedRehype = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
+  const mergedRecma = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
+  if (mergedRemark) resolved.remarkPlugins = mergedRemark;
+  if (mergedRehype) resolved.rehypePlugins = mergedRehype;
+  if (mergedRecma) resolved.recmaPlugins = mergedRecma;
+  return resolved;
+};
+const resolveReactPluginOptions = (options) => {
+  const { extensions: userExtensions, router, mdx, explicitGraph, dependencies, ...baseConfig } = options ?? {};
+  const extensions = [...userExtensions ?? [".tsx"]];
+  const mdxEnabled = mdx?.enabled ?? false;
+  const mdxExtensions = mdx?.extensions ?? [".mdx"];
+  if (mdxEnabled) {
+    appendMdxExtensions(extensions, mdxExtensions);
+  } else if (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."
+    );
+  }
+  const rendererConfig = {
+    routerAdapter: router,
+    mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : void 0,
+    mdxExtensions,
+    hmrPageMetadataCache: new ReactHmrPageMetadataCache(),
+    explicitGraphEnabled: explicitGraph ?? false
+  };
+  return {
+    ...baseConfig,
+    extensions,
+    integrationDependencies: dependencies,
+    rendererConfig
+  };
+};
 class ReactPlugin extends IntegrationPlugin {
   renderer = ReactRenderer;
   routerAdapter;
@@ -14,52 +68,63 @@ class ReactPlugin extends IntegrationPlugin {
   mdxExtensions;
   mdxLoaderPlugin;
   runtimeBundleService;
-  hmrPageMetadataCache = new ReactHmrPageMetadataCache();
+  hmrPageMetadataCache;
+  runtimeDependenciesInitialized = false;
   /**
    * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
    */
   explicitGraphEnabled;
+  rendererConfig;
   constructor(options) {
-    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."
-      );
-    }
+    const config = resolveReactPluginOptions(options);
+    const { extensions, rendererConfig, integrationDependencies, ...baseConfig } = config;
     super({
       name: PLUGIN_NAME,
       extensions,
-      ...options
+      jsxImportSource: "react",
+      integrationDependencies,
+      ...baseConfig
     });
-    this.mdxEnabled = options?.mdx?.enabled ?? false;
-    this.mdxExtensions = mdxExtensions;
+    this.routerAdapter = rendererConfig.routerAdapter;
+    this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
+    this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
+    this.mdxExtensions = rendererConfig.mdxExtensions ?? [".mdx"];
+    this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new ReactHmrPageMetadataCache();
+    this.explicitGraphEnabled = rendererConfig.explicitGraphEnabled ?? false;
+    this.rendererConfig = {
+      ...rendererConfig,
+      mdxExtensions: this.mdxExtensions,
+      hmrPageMetadataCache: this.hmrPageMetadataCache,
+      explicitGraphEnabled: this.explicitGraphEnabled
+    };
     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;
+  }
+  /**
+   * Creates a React renderer with instance-owned runtime configuration.
+   *
+   * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
+   * Keeping that state on the instance avoids cross-plugin static mutation while
+   * preserving the same runtime services the base initializer wires up.
+   */
+  initializeRenderer(options) {
+    const renderer = new this.renderer({
+      ...this.createRendererOptions(options),
+      reactConfig: this.rendererConfig
+    });
+    return this.attachRendererRuntimeServices(renderer);
+  }
+  ensureRuntimeDependencies() {
+    if (this.runtimeDependenciesInitialized) {
+      return;
+    }
+    this.runtimeBundleService.setRootDir(this.appConfig?.rootDir);
     this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
+    this.runtimeDependenciesInitialized = true;
   }
   get plugins() {
     if (this.mdxLoaderPlugin) {
@@ -67,11 +132,32 @@ class ReactPlugin extends IntegrationPlugin {
     }
     return [];
   }
-  async setup() {
-    if (this.mdxEnabled && this.mdxCompilerOptions) {
-      const { createReactMdxLoaderPlugin } = await import("./utils/react-mdx-loader-plugin.js");
-      this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+  /**
+   * Ensures the optional React MDX loader exists before either config-time
+   * manifest sealing or runtime setup needs it.
+   */
+  async ensureMdxLoaderPlugin() {
+    if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
+      return;
     }
+    const { createReactMdxLoaderPlugin } = await import("./utils/react-mdx-loader-plugin.js");
+    this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
+  }
+  /**
+   * Prepares React's build-facing loader contributions before config build seals
+   * the app manifest.
+   */
+  async prepareBuildContributions() {
+    this.ensureRuntimeDependencies();
+    await this.ensureMdxLoaderPlugin();
+  }
+  /**
+   * Performs runtime-only React setup after build contributions are already
+   * materialized.
+   */
+  async setup() {
+    this.ensureRuntimeDependencies();
+    await this.ensureMdxLoaderPlugin();
     await super.setup();
   }
   /**
@@ -92,28 +178,13 @@ class ReactPlugin extends IntegrationPlugin {
       context,
       this.hmrPageMetadataCache,
       this.mdxCompilerOptions,
+      this.extensions,
+      this.appConfig.templatesExt,
       this.explicitGraphEnabled
     );
   }
-  /**
-   * Override to register React-specific specifier mappings for HMR.
-   */
-  setHmrManager(hmrManager) {
-    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.
-   */
-  shouldDeferComponentBoundary(input) {
-    return input.targetIntegration === this.name && input.currentIntegration !== this.name;
+  getRuntimeSpecifierMap() {
+    return this.runtimeBundleService.getSpecifierMap();
   }
 }
 function reactPlugin(options) {

package/src/react.types.d.ts

@@ -0,0 +1,88 @@
+import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { ReactRouterAdapter } from './router-adapter.js';
+import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+/**
+ * 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;
+};
+export type ReactRendererConfig = {
+    routerAdapter?: ReactRouterAdapter;
+    mdxCompilerOptions?: CompileOptions;
+    mdxExtensions?: string[];
+    hmrPageMetadataCache?: ReactHmrPageMetadataCache;
+    explicitGraphEnabled?: boolean;
+};

package/src/router-adapter.d.ts

@@ -46,13 +46,13 @@ export interface ReactRouterAdapter {
         outputName: string;
         /**
          * Packages to externalize when bundling.
-         * These should be available via import map.
+         * These should be available through the runtime bare-specifier map.
          * @example ['react', 'react-dom', 'react/jsx-runtime']
          */
         externals: string[];
     };
     /**
-     * Bare specifier for the import map entry.
+     * Bare specifier for the runtime mapping entry.
      * This is what the hydration script will import from.
      * @example '@ecopages/react-router'
      */

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

@@ -16,13 +16,15 @@ export interface ReactBundleServiceConfig {
     rootDir: string;
     routerAdapter?: ReactRouterAdapter;
     mdxCompilerOptions?: CompileOptions;
+    nonReactExtensions?: string[];
+    jsxImportSource?: string;
 }
 /**
  * Manages esbuild bundle configuration and plugin creation for React page/component builds.
  */
 export declare class ReactBundleService {
-    private readonly config;
     private readonly runtimeBundleService;
+    private readonly config;
     constructor(config: ReactBundleServiceConfig);
     /**
      * Returns resolved runtime import paths for the React runtime.
@@ -41,28 +43,5 @@ export declare class ReactBundleService {
      * Creates the esbuild plugin that rewrites bare React specifiers
      * to their runtime asset URLs.
      */
-    createRuntimeAliasPlugin(runtimeImports: ReactRuntimeImports): {
-        name: string;
-        setup(build: {
-            onResolve: (options: {
-                filter: RegExp;
-                namespace?: string;
-            }, callback: (args: {
-                path: string;
-                importer: string;
-                namespace: string;
-            }) => {
-                path?: string;
-                namespace?: string;
-                external?: boolean;
-            } | undefined) => void;
-        }): void;
-    };
-    /**
-     * 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;
+    createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>): import("@ecopages/core/build/build-types").EcoBuildPlugin | null;
 }