@ecopages/react 0.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to `@ecopages/react` are documented here.
+
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+
+## [UNRELEASED] — TBD
+
+### Features
+
+#### Render Reachability Analysis
+
+- **Client render graph (Phase 1)** — Introduces a static reachability analysis step that builds an explicit graph of which components are rendered client-side (`cdfbd69e`).
+- **OXC-powered reachability analyzer** — `reachability-analyzer.ts` uses OXC to parse and walk component ASTs, building a `ClientRenderGraph` that maps exported components to their client-side reach (`5412df6b`).
+- **Explicit client graph boundaries** — Components must now declare explicit boundaries; the analyser enforces these to prevent over-hydration (`2912d6bd`).
+- **Declared modules utility** — `declared-modules.ts` tracks which modules are declared as client boundaries.
+
+#### Service Architecture Refactor
+
+- **`ReactRuntimeBundleService`** — Manages runtime assets and specifier mapping for the React integration (`cfd3cb05`).
+- **`ReactHydrationAssetService`** — Creates and manages hydration assets for client-side rendering (`cfd3cb05`).
+- **`ReactBundleService`** — Handles esbuild bundle configuration for React components (`cfd3cb05`).
+- **`ReactPageModuleService`** — Loads and compiles MDX/TSX page modules, including config resolution (`cfd3cb05`).
+- The integration no longer builds a monolithic renderer — each concern is handled by a focused service.
+
+#### HMR Improvements
+
+- **HMR page metadata caching** — Page metadata is now cached between HMR refreshes, preventing unnecessary re-fetches during Fast Refresh (`a663788c`).
+- **Stale temp module race fix** — HMR no longer incorrectly reads a stale temporary module during rapid refresh cycles (`b2cf8466`).
+- **Client graph HMR stability** — HMR reloads now correctly respect client graph boundaries to avoid partial hydration mismatches (`2912d6bd`).
+
+#### HTML Boundary Utilities
+
+- **`html-boundary.ts`** — New utility that wraps rendered output in explicit boundary markers for the cross-integration boundary rendering policy (`ec1e4d66`).
+- **`hydration-scripts.ts`** — Expanded with new helpers for generating and injecting hydration entry scripts.
+
+### Refactoring
+
+- Aligned React renderer to full orchestration mode — removed legacy rendering path (`fc07bdb0`).
+- Ambient module declarations cleaned up (`5f46ecc5`).
+- Client graph boundaries and runtime dependency wiring corrected (`4b6cd32e`).
+- Updated test suite for esbuild adapter and Node.js runtime compatibility (`31a44458`).
+
+### Bug Fixes
+
+- Inlined the React MDX loader so React apps no longer need to install `@ecopages/mdx` when enabling React MDX support (`unreleased`).
+- Fixed stale temp module race during Fast Refresh cycles (`b2cf8466`).
+- Fixed client graph boundary wiring for runtime dependencies (`4b6cd32e`).
+
+### Tests
+
+- Added `html-boundary.test.ts` covering boundary wrapping utilities.
+- Added `hydration-scripts.test.ts` with hydration script generation coverage.
+- Added `reachability-analyzer.test.ts` (187 lines) covering export declaration reachability.
+- Updated integration tests for esbuild adapter compatibility (`31a44458`).
+
+---
+
+## Migration Notes
+
+- The React integration now requires explicit client boundary declarations. Components that should be hydrated client-side must be marked at a boundary entry point.
+- The internal service layer (`ReactRuntimeBundleService`, `ReactBundleService`, etc.) is not part of the public API and may change between releases.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Andrea Zanenghi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Ecopages React Integration Plugin
+
+The `@ecopages/react` package introduces first-class integration with [React](https://reactjs.org/) version 19, enabling developers to leverage React's robust ecosystem and component model within the Ecopages platform. This integration provides a seamless experience for using React components in your Ecopages projects, combining React's declarative UI library with the flexibility and simplicity of Ecopages.
+
+## Install
+
+```bash
+bunx jsr add @ecopages/react
+```
+
+## Usage
+
+To incorporate the React integration into your Ecopages project, configure your project as follows:
+
+```ts
+import { ConfigBuilder } from '@ecopages/core';
+import { reactPlugin } from '@ecopages/react';
+
+const config = await new ConfigBuilder()
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setIntegrations([reactPlugin()])
+	.build();
+
+export default config;
+```
+
+## MDX Support
+
+The React plugin includes optional MDX support. When enabled, you can write `.mdx` pages alongside `.tsx` pages with unified client-side routing, hydration, and HMR.
+
+```ts
+import { ConfigBuilder } from '@ecopages/core';
+import { reactPlugin } from '@ecopages/react';
+
+const config = await new ConfigBuilder()
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setIntegrations([
+		reactPlugin({
+			mdx: {
+				enabled: true,
+				compilerOptions: {
+					// Optional: remark/rehype plugins
+				},
+			},
+		}),
+	])
+	.build();
+
+export default config;
+```
+
+This approach is recommended when using a client-side router (e.g., `@ecopages/react-router`) as it ensures consistent navigation between TSX and MDX pages.
+
+## Component-Level Islands
+
+Current behavior:
+
+- SSR output keeps the authored component DOM structure (no synthetic wrapper element).
+- A stable `data-eco-component-id` attribute is attached to the component SSR root when a single root element is available.
+- Client bootstrap resolves the component export and mounts with `createRoot()` into that root boundary.
+- Component assets are emitted through the shared dependency pipeline and deduplicated with other integrations.
+
+This design preserves global CSS/layout selectors while keeping runtime ownership isolated per island instance.
+
+For full React pages with client-side navigation, prefer [@ecopages/react-router](../react-router/README.md), where routing and hydration are handled by the React-specific runtime.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ecopages/react",
+  "version": "0.2.0-alpha.1",
+  "description": "React integration for Ecopages",
+  "keywords": [
+    "ecopages",
+    "react",
+    "plugin"
+  ],
+  "license": "MIT",
+  "main": "./src/react.plugin.js",
+  "types": "./src/react.plugin.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/react.plugin.js",
+      "types": "./src/react.plugin.d.ts"
+    },
+    "./declarations": {
+      "types": "./src/declarations.d.ts"
+    },
+    "./utils/dynamic": {
+      "types": "./src/utils/dynamic.d.ts",
+      "default": "./src/utils/dynamic.js"
+    },
+    "./utils/client-only": {
+      "types": "./src/utils/client-only.d.ts",
+      "default": "./src/utils/client-only.js"
+    },
+    "./router-adapter": {
+      "types": "./src/router-adapter.d.ts",
+      "default": "./src/router-adapter.js"
+    },
+    "./declarations.ts": {
+      "types": "./src/declarations.d.ts"
+    },
+    "./utils/dynamic.ts": {
+      "types": "./src/utils/dynamic.d.ts",
+      "default": "./src/utils/dynamic.js"
+    },
+    "./utils/client-only.ts": {
+      "types": "./src/utils/client-only.d.ts",
+      "default": "./src/utils/client-only.js"
+    },
+    "./router-adapter.ts": {
+      "types": "./src/router-adapter.d.ts",
+      "default": "./src/router-adapter.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/integrations/react"
+  },
+  "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.1",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "dependencies": {
+    "@ecopages/file-system": "0.2.0-alpha.1",
+    "@ecopages/logger": "latest",
+    "@mdx-js/esbuild": "^3.0.1",
+    "@mdx-js/mdx": "^3.1.0",
+    "oxc-parser": "^0.114.0",
+    "oxc-transform": "^0.114.0",
+    "source-map": "^0.7.6",
+    "vfile": "^6.0.3"
+  },
+  "overrides": {
+    "react": "^19",
+    "react-dom": "^19"
+  }
+}

package/src/declarations.d.ts

@@ -0,0 +1,6 @@
+declare module '*.mdx' {
+	import type { ComponentType } from 'react';
+
+	const MDXComponent: ComponentType<Record<string, unknown>>;
+	export default MDXComponent;
+}

package/src/react-hmr-strategy.d.ts

@@ -0,0 +1,143 @@
+/**
+ * React HMR Strategy
+ *
+ * Handles hot module replacement for React components.
+ * Triggers module invalidation on changes to ensure fresh component re-renders.
+ *
+ * @module
+ */
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import type { DefaultHmrContext } from '@ecopages/core';
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+/**
+ * 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 declare class ReactHmrStrategy extends HmrStrategy {
+    private context;
+    private pageMetadataCache;
+    private explicitGraphEnabled;
+    readonly type = HmrStrategyType.INTEGRATION;
+    private mdxCompilerOptions?;
+    private readonly knownEntrypoints;
+    private importNodePageModule;
+    private createUseSyncExternalStoreShimPlugin;
+    /**
+     * 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(context: DefaultHmrContext, pageMetadataCache: ReactHmrPageMetadataCache, mdxCompilerOptions?: CompileOptions, explicitGraphEnabled?: boolean);
+    /**
+     * 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;
+    private isReactEntrypoint;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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)
+     */
+    process(_filePath: string): Promise<HmrAction>;
+    /**
+     * 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 bundleReactEntrypoint;
+    /**
+     * Encodes dynamic route segments (brackets) in file paths.
+     * Converts `[slug]` to `_slug_` to avoid filesystem issues.
+     */
+    private encodeDynamicSegments;
+    /**
+     * 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 processOutput;
+    /**
+     * 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;
+}