@ecopages/react 0.2.0-alpha.51 → 0.2.0-alpha.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.51",
+  "version": "0.2.0-alpha.53",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -69,14 +69,14 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.51",
+    "@ecopages/core": "0.2.0-alpha.53",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.51",
+    "@ecopages/file-system": "0.2.0-alpha.53",
     "@ecopages/logger": "^0.2.3",
     "@mdx-js/esbuild": "^3.1.1",
     "@mdx-js/mdx": "^3.1.1",

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

@@ -100,11 +100,21 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private isRouteTemplate;
     private resolveTemplateExtension;
     private ownsWatchedEntrypoint;
+    private configContainsFile;
+    private pageModuleRequiresLayoutRefresh;
+    private hasLayoutOwnedDependencyTarget;
     /**
      * Determines if the file is a React/MDX entrypoint that's registered for HMR.
      *
+     * Uses a three-way decision strategy for selective invalidation:
+     * 1. If the file is a watched entrypoint, check if React owns it
+     * 2. If the file is a dependency of watched entrypoints (via dependency graph),
+     *    check if any affected entrypoints are React-owned. Returns false if hits
+     *    exist but none are owned (prevents unnecessary rebuilds).
+     * 3. Otherwise, check if the file itself is a React entrypoint template
+     *
      * @param filePath - Absolute path to the changed file
-     * @returns True if this is a registered React or MDX entrypoint
+     * @returns True if this file should trigger React HMR rebuilds
      */
     matches(filePath: string): boolean;
     /**
@@ -123,7 +133,6 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private getEntrypointOutput;
     private getGroupedTempOutputPattern;
     private collectReactPageBuildTargets;
-    private getRequestedTargets;
     /**
      * Expands one HMR request into the full React page build cohort when needed.
      *
@@ -135,12 +144,17 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private resolveBuildTargets;
     private partitionBuildTargets;
     /**
-     * Processes a React file change by rebuilding all React entrypoints.
+     * Processes a React file change by rebuilding affected React entrypoints.
+     *
+     * Uses a three-way decision strategy for selective invalidation:
+     * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
+     * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
+     *    If hits exist but none map to React-owned entrypoints, return 'none' to
+     *    prevent unnecessary rebuilds.
+     * 3. Dependency graph miss: fall back to rebuilding all watched 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)
@@ -149,11 +163,26 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     /**
      * Bundles a single React/MDX entrypoint with HMR support.
      *
+     * After successful bundling, populates the entrypoint dependency graph with
+     * the build's dependency metadata. This enables selective invalidation on
+     * subsequent file changes, so only entrypoints affected by a changed
+     * dependency are rebuilt.
+     *
      * @param entrypointPath - Absolute path to the source file
      * @param outputUrl - URL path for the bundled file
      * @returns True if bundling was successful
      */
     private bundleReactEntrypoint;
+    /**
+     * Bundles multiple React/MDX entrypoints in a single build pass.
+     *
+     * Uses code splitting to share common dependencies across entrypoints.
+     * After successful bundling, populates the entrypoint dependency graph with
+     * the build's dependency metadata for selective invalidation.
+     *
+     * @param entrypoints - Array of entrypoint paths and their output URLs
+     * @returns Array of output URLs that were successfully built
+     */
     private bundleReactEntrypoints;
     private resolveTempOutputPath;
     /**

package/src/react-hmr-strategy.js

@@ -7,6 +7,7 @@ import { Logger } from "@ecopages/logger";
 import { injectHmrHandler } from "./utils/hmr-scripts.js";
 import { createClientGraphBoundaryPlugin } from "./utils/client-graph-boundary-plugin.js";
 import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from "./utils/declared-modules.js";
+import { someInConfigTree } from "./utils/component-config-traversal.js";
 import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
 import { getReactClientGraphAllowSpecifiers } from "./utils/react-runtime-alias-map.js";
 const appLogger = new Logger("[ReactHmrStrategy]");
@@ -103,11 +104,44 @@ class ReactHmrStrategy extends HmrStrategy {
   ownsWatchedEntrypoint(filePath) {
     return this.pageMetadataCache.ownsEntrypoint(filePath);
   }
+  configContainsFile(config, filePath) {
+    const resolvedFilePath = path.resolve(filePath);
+    return someInConfigTree(config, (node) => {
+      if (!node.__eco?.file) {
+        return false;
+      }
+      return path.resolve(node.__eco.file) === resolvedFilePath;
+    });
+  }
+  pageModuleRequiresLayoutRefresh(pageModule, filePath) {
+    return [pageModule.default?.config, pageModule.config].some((config) => {
+      return this.configContainsFile(config?.layout?.config, filePath);
+    });
+  }
+  async hasLayoutOwnedDependencyTarget(changedFilePath, requestedTargets) {
+    for (const target of requestedTargets) {
+      if (!this.isPageEntrypoint(target.entrypointPath)) {
+        continue;
+      }
+      const pageModule = await this.importNodePageModule(target.entrypointPath);
+      if (this.pageModuleRequiresLayoutRefresh(pageModule, changedFilePath)) {
+        return true;
+      }
+    }
+    return false;
+  }
   /**
    * Determines if the file is a React/MDX entrypoint that's registered for HMR.
    *
+   * Uses a three-way decision strategy for selective invalidation:
+   * 1. If the file is a watched entrypoint, check if React owns it
+   * 2. If the file is a dependency of watched entrypoints (via dependency graph),
+   *    check if any affected entrypoints are React-owned. Returns false if hits
+   *    exist but none are owned (prevents unnecessary rebuilds).
+   * 3. Otherwise, check if the file itself is a React entrypoint template
+   *
    * @param filePath - Absolute path to the changed file
-   * @returns True if this is a registered React or MDX entrypoint
+   * @returns True if this file should trigger React HMR rebuilds
    */
   matches(filePath) {
     const watchedFiles = this.context.getWatchedFiles();
@@ -118,6 +152,15 @@ class ReactHmrStrategy extends HmrStrategy {
     if (watchedFiles.has(filePath)) {
       return this.ownsWatchedEntrypoint(filePath);
     }
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
+    if (dependencyHits.size > 0) {
+      for (const entrypoint of dependencyHits) {
+        if (this.ownsWatchedEntrypoint(entrypoint)) {
+          return true;
+        }
+      }
+      return false;
+    }
     return this.isReactEntrypoint(filePath);
   }
   /**
@@ -180,13 +223,6 @@ class ReactHmrStrategy extends HmrStrategy {
       (left, right) => left.entrypointPath.localeCompare(right.entrypointPath)
     );
   }
-  getRequestedTargets(changedFilePath, changedEntrypointOutput, watchedFiles) {
-    const requestedEntries = changedEntrypointOutput ? [[changedFilePath, changedEntrypointOutput]] : Array.from(watchedFiles.entries());
-    return requestedEntries.map(([entrypointPath, outputUrl]) => ({
-      entrypointPath,
-      outputUrl
-    }));
-  }
   /**
    * Expands one HMR request into the full React page build cohort when needed.
    *
@@ -225,12 +261,17 @@ class ReactHmrStrategy extends HmrStrategy {
     };
   }
   /**
-   * Processes a React file change by rebuilding all React entrypoints.
+   * Processes a React file change by rebuilding affected React entrypoints.
+   *
+   * Uses a three-way decision strategy for selective invalidation:
+   * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
+   * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
+   *    If hits exist but none map to React-owned entrypoints, return 'none' to
+   *    prevent unnecessary rebuilds.
+   * 3. Dependency graph miss: fall back to rebuilding all watched 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)
@@ -243,6 +284,7 @@ class ReactHmrStrategy extends HmrStrategy {
       return { type: "none" };
     }
     const isLayout = this.isLayoutFile(_filePath);
+    const isChangedPageEntrypoint = this.isPageEntrypoint(_filePath);
     if (isLayout) {
       appLogger.debug(`Detected layout file change: ${_filePath}`);
     }
@@ -251,9 +293,42 @@ class ReactHmrStrategy extends HmrStrategy {
       appLogger.debug(`Skipping non-React watched entrypoint: ${_filePath}`);
       return { type: "none" };
     }
-    const requestedTargets = this.getRequestedTargets(_filePath, changedEntrypointOutput, watchedFiles);
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(_filePath);
+    const hasDependencyHits = dependencyHits.size > 0;
+    const affectedEntrypoints = /* @__PURE__ */ new Map();
+    let hasOwnedLayoutDependencyHit = false;
+    let layoutOwnedPageTargets = [];
+    let hasLayoutOwnedRequestedTarget = false;
+    if (hasDependencyHits && !changedEntrypointOutput) {
+      for (const entrypoint of dependencyHits) {
+        const outputUrl = watchedFiles.get(entrypoint);
+        if (outputUrl && this.ownsWatchedEntrypoint(entrypoint)) {
+          affectedEntrypoints.set(entrypoint, outputUrl);
+          continue;
+        }
+        if (this.isLayoutFile(entrypoint) && this.ownsWatchedEntrypoint(entrypoint)) {
+          hasOwnedLayoutDependencyHit = true;
+        }
+      }
+      if (affectedEntrypoints.size === 0 && !hasOwnedLayoutDependencyHit) {
+        appLogger.debug(`Dependency hits found but none map to React-owned watched entrypoints`);
+        return { type: "none" };
+      }
+    }
+    if (changedEntrypointOutput && !isLayout && !isChangedPageEntrypoint) {
+      layoutOwnedPageTargets = await this.collectReactPageBuildTargets();
+      hasLayoutOwnedRequestedTarget = await this.hasLayoutOwnedDependencyTarget(
+        _filePath,
+        layoutOwnedPageTargets
+      );
+    }
+    const requestedTargets = changedEntrypointOutput ? hasLayoutOwnedRequestedTarget ? [{ entrypointPath: _filePath, outputUrl: changedEntrypointOutput }, ...layoutOwnedPageTargets] : [{ entrypointPath: _filePath, outputUrl: changedEntrypointOutput }] : hasOwnedLayoutDependencyHit ? await this.collectReactPageBuildTargets() : hasDependencyHits ? Array.from(affectedEntrypoints, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl })) : Array.from(watchedFiles, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl }));
     const groupedPageTargets = await this.resolveBuildTargets(requestedTargets, _filePath);
     const { pageTargets, nonPageTargets } = this.partitionBuildTargets(requestedTargets, groupedPageTargets);
+    if (!changedEntrypointOutput) {
+      hasLayoutOwnedRequestedTarget = await this.hasLayoutOwnedDependencyTarget(_filePath, requestedTargets);
+    }
+    const requiresLayoutRefresh = isLayout || hasOwnedLayoutDependencyHit || hasLayoutOwnedRequestedTarget;
     const updates = [];
     const requestedOutputUrls = new Set(requestedTargets.map((target) => target.outputUrl));
     if (pageTargets.length > 1) {
@@ -284,7 +359,7 @@ class ReactHmrStrategy extends HmrStrategy {
       }
     }
     if (updates.length > 0) {
-      if (isLayout) {
+      if (requiresLayoutRefresh) {
         appLogger.debug(`Layout update detected, sending layout-update event`);
         return {
           type: "broadcast",
@@ -311,6 +386,11 @@ class ReactHmrStrategy extends HmrStrategy {
   /**
    * Bundles a single React/MDX entrypoint with HMR support.
    *
+   * After successful bundling, populates the entrypoint dependency graph with
+   * the build's dependency metadata. This enables selective invalidation on
+   * subsequent file changes, so only entrypoints affected by a changed
+   * dependency are rebuilt.
+   *
    * @param entrypointPath - Absolute path to the source file
    * @param outputUrl - URL path for the bundled file
    * @returns True if bundling was successful
@@ -338,6 +418,12 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`Failed to build ${entrypointPath}:`, result.logs);
         return false;
       }
+      if (result.dependencyGraph?.entrypoints) {
+        const dependencyGraph = this.context.getEntrypointDependencyGraph();
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencyGraph.setEntrypointDependencies(entrypoint, deps);
+        }
+      }
       const tempFile = result.outputs[0]?.path;
       if (!tempFile) {
         appLogger.error(`No output file generated for ${entrypointPath}`);
@@ -355,6 +441,16 @@ class ReactHmrStrategy extends HmrStrategy {
       return false;
     }
   }
+  /**
+   * Bundles multiple React/MDX entrypoints in a single build pass.
+   *
+   * Uses code splitting to share common dependencies across entrypoints.
+   * After successful bundling, populates the entrypoint dependency graph with
+   * the build's dependency metadata for selective invalidation.
+   *
+   * @param entrypoints - Array of entrypoint paths and their output URLs
+   * @returns Array of output URLs that were successfully built
+   */
   async bundleReactEntrypoints(entrypoints) {
     try {
       const declaredModules = /* @__PURE__ */ new Set();
@@ -387,6 +483,12 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`Failed to build grouped React entrypoints:`, result.logs);
         return [];
       }
+      if (result.dependencyGraph?.entrypoints) {
+        const dependencyGraph = this.context.getEntrypointDependencyGraph();
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencyGraph.setEntrypointDependencies(entrypoint, deps);
+        }
+      }
       const updatedOutputs = [];
       for (const { entrypointPath, outputUrl } of entrypoints) {
         const { outputPath } = this.getEntrypointOutput(entrypointPath);