@ecopages/react 0.2.0-alpha.4 → 0.2.0-alpha.5

package/CHANGELOG.md

@@ -46,6 +46,11 @@ All notable changes to `@ecopages/react` are documented here.
 - 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`).
+- Fixed shared React barrel handling so client-reachable server-only re-exports now fail the build instead of being silently pruned (`unreleased`).
+
+### Documentation
+
+- Documented the React integration server/client graph contract for shared modules and barrel exports (`unreleased`).
 
 ### Tests
 

package/README.md

@@ -63,3 +63,23 @@ Current behavior:
 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.
+
+## Server And Client Graph Contract
+
+The React integration supports Node.js modules and server-only code, but only on the server execution graph.
+
+- Server rendering can import and execute `node:*` modules, database clients, filesystem utilities, and `*.server.*` modules.
+- Client-hydrated React code must resolve to browser-safe modules only.
+- Shared files and barrel files are allowed when the exports that become client-reachable are browser-safe.
+- If a server-only import becomes client-reachable, the client build fails instead of silently replacing the import.
+
+In practice, this means you can keep server helpers close to your React code, but the browser bundle boundary is strict:
+
+```ts
+export { Button } from './button';
+export { db } from './db.server';
+```
+
+If a client entry only reaches `Button`, the `db` re-export is removed from the browser transform. If a client entry reaches `db`, the build fails because the server-only export crossed into the client graph.
+
+This contract keeps SSR and server functions free to use Node.js while ensuring the final browser bundle contains no client-reachable server-only code.

package/package.json

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

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

@@ -54,6 +54,17 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private mdxCompilerOptions?;
     private readonly knownEntrypoints;
     private importNodePageModule;
+    /**
+     * Redirects `use-sync-external-store/shim` imports to React's built-in
+     * `useSyncExternalStore`.
+     *
+     * Libraries like React Aria still list `use-sync-external-store` as a
+     * dependency to support React 16/17. On React 18+ the `/shim` export is
+     * already a pass-through, but without this plugin esbuild would bundle
+     * the full CJS shim (including `process.env` branching) into the browser
+     * bundle. The plugin short-circuits the resolution so only a single clean
+     * ESM re-export is emitted.
+     */
     private createUseSyncExternalStoreShimPlugin;
     /**
      * Creates a new React HMR strategy instance.

package/src/react-hmr-strategy.js

@@ -61,6 +61,17 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     return await import(pathToFileURL(compiledOutput).href);
   }
+  /**
+   * Redirects `use-sync-external-store/shim` imports to React's built-in
+   * `useSyncExternalStore`.
+   *
+   * Libraries like React Aria still list `use-sync-external-store` as a
+   * dependency to support React 16/17. On React 18+ the `/shim` export is
+   * already a pass-through, but without this plugin esbuild would bundle
+   * the full CJS shim (including `process.env` branching) into the browser
+   * bundle. The plugin short-circuits the resolution so only a single clean
+   * ESM re-export is emitted.
+   */
   createUseSyncExternalStoreShimPlugin() {
     return {
       name: "react-hmr-use-sync-external-store-shim",

package/src/react-hmr-strategy.ts

@@ -108,6 +108,17 @@ export class ReactHmrStrategy extends HmrStrategy {
 		};
 	}
 
+	/**
+	 * Redirects `use-sync-external-store/shim` imports to React's built-in
+	 * `useSyncExternalStore`.
+	 *
+	 * Libraries like React Aria still list `use-sync-external-store` as a
+	 * dependency to support React 16/17. On React 18+ the `/shim` export is
+	 * already a pass-through, but without this plugin esbuild would bundle
+	 * the full CJS shim (including `process.env` branching) into the browser
+	 * bundle. The plugin short-circuits the resolution so only a single clean
+	 * ESM re-export is emitted.
+	 */
 	private createUseSyncExternalStoreShimPlugin(): EcoBuildPlugin {
 		return {
 			name: 'react-hmr-use-sync-external-store-shim',

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

@@ -59,10 +59,15 @@ export declare class ReactBundleService {
         }): 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`.
+     * Redirects `use-sync-external-store/shim` imports to React's built-in
+     * `useSyncExternalStore`.
+     *
+     * Libraries like React Aria still list `use-sync-external-store` as a
+     * dependency to support React 16/17. On React 18+ the `/shim` export is
+     * already a pass-through, but without this plugin esbuild would bundle
+     * the full CJS shim (including `process.env` branching) into the browser
+     * bundle. The plugin short-circuits the resolution so only a single clean
+     * ESM re-export is emitted.
      */
     private createSyncExternalStorePlugin;
 }

package/src/services/react-bundle.service.js

@@ -52,9 +52,9 @@ class ReactBundleService {
     if (isMdx && this.config.mdxCompilerOptions) {
       const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
       const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
-      options.plugins = [runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin];
     } else {
-      options.plugins = [runtimeAliasPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, useSyncExternalStoreShimPlugin];
     }
     return options;
   }
@@ -94,10 +94,15 @@ class ReactBundleService {
     };
   }
   /**
-   * 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`.
+   * Redirects `use-sync-external-store/shim` imports to React's built-in
+   * `useSyncExternalStore`.
+   *
+   * Libraries like React Aria still list `use-sync-external-store` as a
+   * dependency to support React 16/17. On React 18+ the `/shim` export is
+   * already a pass-through, but without this plugin esbuild would bundle
+   * the full CJS shim (including `process.env` branching) into the browser
+   * bundle. The plugin short-circuits the resolution so only a single clean
+   * ESM re-export is emitted.
    */
   createSyncExternalStorePlugin() {
     return {

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

@@ -85,9 +85,9 @@ export class ReactBundleService {
 		if (isMdx && this.config.mdxCompilerOptions) {
 			const { createReactMdxLoaderPlugin } = await import('../utils/react-mdx-loader-plugin.ts');
 			const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
-			options.plugins = [runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+			options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin];
 		} else {
-			options.plugins = [runtimeAliasPlugin, useSyncExternalStoreShimPlugin, graphBoundaryPlugin];
+			options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, useSyncExternalStoreShimPlugin];
 		}
 
 		return options;
@@ -144,10 +144,15 @@ export class ReactBundleService {
 	}
 
 	/**
-	 * 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`.
+	 * Redirects `use-sync-external-store/shim` imports to React's built-in
+	 * `useSyncExternalStore`.
+	 *
+	 * Libraries like React Aria still list `use-sync-external-store` as a
+	 * dependency to support React 16/17. On React 18+ the `/shim` export is
+	 * already a pass-through, but without this plugin esbuild would bundle
+	 * the full CJS shim (including `process.env` branching) into the browser
+	 * bundle. The plugin short-circuits the resolution so only a single clean
+	 * ESM re-export is emitted.
 	 */
 	private createSyncExternalStorePlugin() {
 		return {

package/src/utils/client-graph-boundary-plugin.js

@@ -12,6 +12,10 @@ function isBareSpecifier(specifier) {
 function isProjectAliasSpecifier(specifier) {
   return specifier.startsWith("@/") || specifier.startsWith("~/") || specifier.startsWith("ecopages:");
 }
+function isServerOnlySpecifier(specifier) {
+  if (specifier.startsWith("node:")) return true;
+  return /(?:^|[/])[^/]+\.server(?:$|\.)/.test(specifier);
+}
 function toModuleBaseSpecifier(specifier) {
   if (!isBareSpecifier(specifier) || specifier.startsWith("node:")) {
     return specifier;
@@ -82,7 +86,37 @@ function parserLanguageForFile(filename) {
   if (extension === ".jsx") return "jsx";
   return "js";
 }
-function transformModuleImports(source, filename, globallyAllowed) {
+function normalizeRequestedExportsKey(pathname) {
+  let normalized = pathname.replace(/\\/g, "/");
+  normalized = normalized.replace(/\.(tsx?|jsx?)$/i, "");
+  if (normalized.endsWith("/index")) {
+    normalized = normalized.slice(0, -"/index".length);
+  }
+  return normalized;
+}
+function resolveRequestedExportsKey(importer, specifier) {
+  if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
+    return void 0;
+  }
+  const resolved = specifier.startsWith("/") ? specifier : resolve(dirname(importer), specifier);
+  return normalizeRequestedExportsKey(resolved);
+}
+function mergeRequestedExportRules(registry, moduleKey, rules) {
+  const existing = registry.get(moduleKey);
+  if (existing === "*") return;
+  if (rules === "*") {
+    registry.set(moduleKey, "*");
+    return;
+  }
+  if (!existing) {
+    registry.set(moduleKey, new Set(rules));
+    return;
+  }
+  for (const rule of rules) {
+    existing.add(rule);
+  }
+}
+function transformModuleImports(source, filename, globallyAllowed, requestedExports) {
   let result;
   try {
     result = parseSync(filename, source, {
@@ -116,12 +150,35 @@ function transformModuleImports(source, filename, globallyAllowed) {
   walk(program);
   const locallyAllowed = parseDeclaredModules(localDeclared);
   const allowedMap = mergeDeclaredModulesMap(globallyAllowed, locallyAllowed);
-  const reachability = analyzeReachability(source, filename, program);
+  const explicitRequestedExports = requestedExports.get(normalizeRequestedExportsKey(filename));
+  const reachability = analyzeReachability(source, filename, program, explicitRequestedExports);
+  for (const statement of program.body) {
+    if (statement.type === "ImportDeclaration") {
+      const reachableRules = reachability.reachableImports.get(statement.source.value);
+      const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value);
+      if (!requestedModuleKey || !reachableRules) continue;
+      mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+      continue;
+    }
+    if (statement.type === "ExportNamedDeclaration" && statement.source) {
+      const reachableRules = reachability.reachableImports.get(statement.source.value);
+      const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value);
+      if (!requestedModuleKey || !reachableRules) continue;
+      mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+      continue;
+    }
+    if (statement.type === "ExportAllDeclaration" && statement.source) {
+      const reachableRules = reachability.reachableImports.get(statement.source.value);
+      const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value);
+      if (!requestedModuleKey || !reachableRules) continue;
+      mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+    }
+  }
   const edits = [];
   function processSpecifier(specifier) {
     const moduleBase = toModuleBaseSpecifier(specifier);
     const explicitRules = allowedMap.get(moduleBase);
-    if (specifier.startsWith("node:") || specifier.includes(".server.")) {
+    if (isServerOnlySpecifier(specifier)) {
       if (explicitRules) {
         return { allowed: true, rules: explicitRules };
       }
@@ -208,9 +265,10 @@ function transformModuleImports(source, filename, globallyAllowed) {
       const specifier = node.source.value;
       const { allowed } = processSpecifier(specifier);
       if (!allowed) {
-        if (!reachability.isFallbackRoots) {
+        const reachableRules = reachability.reachableImports.get(specifier);
+        if (reachableRules && !reachability.isFallbackRoots) {
           throw new Error(
-            `[Ecopages Client Reachability] Forbidden client export from '${specifier}' at ${filename}:${node.start}.`
+            `[Ecopages Client Reachability] Forbidden client export from '${specifier}' at ${filename}:${node.start}. This export is explicitly reachable from the React render function.`
           );
         } else {
           edits.push({ start: node.start, end: node.end, replacement: "" });
@@ -222,9 +280,10 @@ function transformModuleImports(source, filename, globallyAllowed) {
       const specifier = node.source.value;
       const { allowed } = processSpecifier(specifier);
       if (!allowed) {
-        if (!reachability.isFallbackRoots) {
+        const reachableRules = reachability.reachableImports.get(specifier);
+        if (reachableRules && !reachability.isFallbackRoots) {
           throw new Error(
-            `[Ecopages Client Reachability] Forbidden client export * from '${specifier}' at ${filename}:${node.start}.`
+            `[Ecopages Client Reachability] Forbidden client export * from '${specifier}' at ${filename}:${node.start}. This export is explicitly reachable from the React render function.`
           );
         } else {
           edits.push({ start: node.start, end: node.end, replacement: "" });
@@ -297,6 +356,7 @@ function createClientGraphBoundaryPlugin(options) {
     setup(build) {
       const absWorkingDir = options?.absWorkingDir ?? process.cwd();
       const globallyDeclaredSources = parseDeclaredModules(options?.declaredModules);
+      const requestedExports = /* @__PURE__ */ new Map();
       for (const alwaysAllow of options?.alwaysAllowSpecifiers ?? []) {
         globallyDeclaredSources.set(toModuleBaseSpecifier(alwaysAllow), "*");
       }
@@ -338,7 +398,8 @@ function createClientGraphBoundaryPlugin(options) {
         const { transformed: oxcTransformed, modified: importsModified } = transformModuleImports(
           transformed,
           args.path,
-          globallyDeclaredSources
+          globallyDeclaredSources,
+          requestedExports
         );
         if (importsModified) {
           modified = true;

package/src/utils/client-graph-boundary-plugin.ts

@@ -64,6 +64,20 @@ function isProjectAliasSpecifier(specifier: string): boolean {
 	return specifier.startsWith('@/') || specifier.startsWith('~/') || specifier.startsWith('ecopages:');
 }
 
+/**
+ * Determines whether a specifier should be treated as server-only.
+ *
+ * This covers Node built-ins as well as local module conventions such as
+ * `.server.ts` and extensionless imports that resolve to `.server.*` files.
+ *
+ * @param specifier - Raw import specifier from the module source.
+ * @returns True when the import must never become client-reachable.
+ */
+function isServerOnlySpecifier(specifier: string): boolean {
+	if (specifier.startsWith('node:')) return true;
+	return /(?:^|[/])[^/]+\.server(?:$|\.)/.test(specifier);
+}
+
 /**
  * Strips down a deep path module specifier to its foundational root package name.
  *
@@ -191,6 +205,81 @@ function parserLanguageForFile(filename: string): 'js' | 'jsx' | 'ts' | 'tsx' {
 	return 'js';
 }
 
+/**
+ * Tracks the subset of exports that a downstream local module is allowed to expose.
+ *
+ * `'*'` means the full module namespace is reachable, while a `Set` limits the
+ * consumer to specific named exports.
+ */
+type RequestedExportRules = Set<string> | '*';
+
+/**
+ * Normalizes a file path into a registry key used for requested-export propagation.
+ *
+ * The normalization strips JS/TS extensions and collapses `/index` suffixes so
+ * equivalent local import forms resolve to the same key.
+ *
+ * @param pathname - Absolute or resolved local module path.
+ * @returns Stable registry key for `requestedExports`.
+ */
+function normalizeRequestedExportsKey(pathname: string): string {
+	let normalized = pathname.replace(/\\/g, '/');
+	normalized = normalized.replace(/\.(tsx?|jsx?)$/i, '');
+	if (normalized.endsWith('/index')) {
+		normalized = normalized.slice(0, -'/index'.length);
+	}
+	return normalized;
+}
+
+/**
+ * Resolves a local import specifier into a requested-export registry key.
+ *
+ * Bare package specifiers and project aliases are intentionally ignored because
+ * requested-export propagation is only used for cross-file local reachability.
+ *
+ * @param importer - Absolute path of the importing module.
+ * @param specifier - Raw import or re-export specifier.
+ * @returns Registry key for a local dependency, or `undefined` when not applicable.
+ */
+function resolveRequestedExportsKey(importer: string, specifier: string): string | undefined {
+	if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
+		return undefined;
+	}
+
+	const resolved = specifier.startsWith('/') ? specifier : resolve(dirname(importer), specifier);
+	return normalizeRequestedExportsKey(resolved);
+}
+
+/**
+ * Merges newly discovered requested-export rules into the local propagation registry.
+ *
+ * Once a module is promoted to `'*'`, it stays fully reachable for the remainder
+ * of the transform pass.
+ *
+ * @param registry - Cross-module requested-export registry.
+ * @param moduleKey - Normalized local module key.
+ * @param rules - Newly observed reachable export rules for the module.
+ */
+function mergeRequestedExportRules(
+	registry: Map<string, RequestedExportRules>,
+	moduleKey: string,
+	rules: Set<string> | '*',
+) {
+	const existing = registry.get(moduleKey);
+	if (existing === '*') return;
+	if (rules === '*') {
+		registry.set(moduleKey, '*');
+		return;
+	}
+	if (!existing) {
+		registry.set(moduleKey, new Set(rules));
+		return;
+	}
+	for (const rule of rules) {
+		existing.add(rule);
+	}
+}
+
 /**
  * Parses a module using Oxc AST and surgically removes forbidden imports.
  * Filters down to the exact specifiers requested via `{namedImport}` syntax.
@@ -198,12 +287,14 @@ function parserLanguageForFile(filename: string): 'js' | 'jsx' | 'ts' | 'tsx' {
  * @param source - The raw string source content of the module.
  * @param filename - The absolute path of the module.
  * @param globallyAllowed - A map of modules declared globally allowable by the build configuration.
+ * @param requestedExports - Local requested-export registry used to propagate named reachability across files.
  * @returns An object containing the transformed string and a boolean indicating if changes occurred.
  */
 function transformModuleImports(
 	source: string,
 	filename: string,
 	globallyAllowed: Map<string, Set<string> | '*'>,
+	requestedExports: Map<string, RequestedExportRules>,
 ): { transformed: string; modified: boolean } {
 	/**
 	 * Parse the source
@@ -273,7 +364,36 @@ function transformModuleImports(
 	 */
 	const locallyAllowed = parseDeclaredModules(localDeclared);
 	const allowedMap = mergeDeclaredModulesMap(globallyAllowed, locallyAllowed);
-	const reachability = analyzeReachability(source, filename, program);
+	const explicitRequestedExports = requestedExports.get(normalizeRequestedExportsKey(filename));
+	const reachability = analyzeReachability(source, filename, program, explicitRequestedExports);
+
+	for (const statement of program.body) {
+		if (statement.type === 'ImportDeclaration') {
+			const reachableRules = reachability.reachableImports.get(statement.source.value as string);
+			const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value as string);
+			if (!requestedModuleKey || !reachableRules) continue;
+
+			mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+			continue;
+		}
+
+		if (statement.type === 'ExportNamedDeclaration' && statement.source) {
+			const reachableRules = reachability.reachableImports.get(statement.source.value as string);
+			const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value as string);
+			if (!requestedModuleKey || !reachableRules) continue;
+
+			mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+			continue;
+		}
+
+		if (statement.type === 'ExportAllDeclaration' && statement.source) {
+			const reachableRules = reachability.reachableImports.get(statement.source.value as string);
+			const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value as string);
+			if (!requestedModuleKey || !reachableRules) continue;
+
+			mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+		}
+	}
 
 	/**
 	 * Build the edit list
@@ -294,7 +414,7 @@ function transformModuleImports(
 		const moduleBase = toModuleBaseSpecifier(specifier);
 		const explicitRules = allowedMap.get(moduleBase);
 
-		if (specifier.startsWith('node:') || specifier.includes('.server.')) {
+		if (isServerOnlySpecifier(specifier)) {
 			if (explicitRules) {
 				return { allowed: true, rules: explicitRules };
 			}
@@ -405,14 +525,11 @@ function transformModuleImports(
 			const specifier = node.source.value as string;
 			const { allowed } = processSpecifier(specifier);
 
-			/**
-			 * We skip checking reachability of re-exports for now to avoid false negatives.
-			 * But we MUST check security.
-			 */
 			if (!allowed) {
-				if (!reachability.isFallbackRoots) {
+				const reachableRules = reachability.reachableImports.get(specifier);
+				if (reachableRules && !reachability.isFallbackRoots) {
 					throw new Error(
-						`[Ecopages Client Reachability] Forbidden client export from '${specifier}' at ${filename}:${node.start}.`,
+						`[Ecopages Client Reachability] Forbidden client export from '${specifier}' at ${filename}:${node.start}. This export is explicitly reachable from the React render function.`,
 					);
 				} else {
 					edits.push({ start: node.start, end: node.end, replacement: '' });
@@ -425,9 +542,10 @@ function transformModuleImports(
 			const specifier = node.source.value as string;
 			const { allowed } = processSpecifier(specifier);
 			if (!allowed) {
-				if (!reachability.isFallbackRoots) {
+				const reachableRules = reachability.reachableImports.get(specifier);
+				if (reachableRules && !reachability.isFallbackRoots) {
 					throw new Error(
-						`[Ecopages Client Reachability] Forbidden client export * from '${specifier}' at ${filename}:${node.start}.`,
+						`[Ecopages Client Reachability] Forbidden client export * from '${specifier}' at ${filename}:${node.start}. This export is explicitly reachable from the React render function.`,
 					);
 				} else {
 					edits.push({ start: node.start, end: node.end, replacement: '' });
@@ -516,6 +634,7 @@ export function createClientGraphBoundaryPlugin(options?: ClientGraphBoundaryOpt
 		setup(build) {
 			const absWorkingDir = options?.absWorkingDir ?? process.cwd();
 			const globallyDeclaredSources = parseDeclaredModules(options?.declaredModules);
+			const requestedExports = new Map<string, RequestedExportRules>();
 			for (const alwaysAllow of options?.alwaysAllowSpecifiers ?? []) {
 				globallyDeclaredSources.set(toModuleBaseSpecifier(alwaysAllow), '*');
 			}
@@ -573,6 +692,7 @@ export function createClientGraphBoundaryPlugin(options?: ClientGraphBoundaryOpt
 					transformed,
 					args.path,
 					globallyDeclaredSources,
+					requestedExports,
 				);
 
 				if (importsModified) {

package/src/utils/reachability-analyzer.d.ts

@@ -42,6 +42,15 @@ export type ReachabilityResult = {
      */
     analyzed: boolean;
 };
+/**
+ * Optional export filter supplied by the client graph boundary when a local
+ * module is imported through a narrower named-export surface.
+ *
+ * `'*'` means the whole module namespace is considered reachable, while a
+ * `Set` restricts analysis to the named exports that are actually requested by
+ * downstream client-reachable modules.
+ */
+type ExplicitlyRequestedExports = Set<string> | '*';
 /**
  * Analyzes a module using Oxc AST and extracts a strict reachability graph
  * starting from client roots (`render`, `errorBoundary`, `loadingFallback` of `eco.page` or `eco.component`).
@@ -50,6 +59,8 @@ export type ReachabilityResult = {
  * @param filename - Absolute or relative path to the module file.
  * @param program - Optional pre-parsed Oxc program AST. When supplied, the
  *   internal `parseSync` call is skipped entirely (avoids double-parsing).
+ * @param explicitlyRequestedExports - Optional named export filter propagated
+ *   from a downstream importer when this module is only partially reachable.
  */
-export declare function analyzeReachability(source: string, filename: string, program?: ReturnType<typeof parseSync>['program']): ReachabilityResult;
+export declare function analyzeReachability(source: string, filename: string, program?: ReturnType<typeof parseSync>['program'], explicitlyRequestedExports?: ExplicitlyRequestedExports): ReachabilityResult;
 export {};

package/src/utils/reachability-analyzer.js

@@ -7,7 +7,7 @@ function parserLanguageForFile(filename) {
   if (extension === ".jsx") return "jsx";
   return "js";
 }
-function analyzeReachability(source, filename, program) {
+function analyzeReachability(source, filename, program, explicitlyRequestedExports) {
   let resolvedProgram;
   if (program) {
     resolvedProgram = program;
@@ -114,12 +114,86 @@ function analyzeReachability(source, filename, program) {
       potentialClientRoots.push(node);
     }
   }
+  function getExportedName(specifier) {
+    if (specifier?.exported?.type === "Identifier") return specifier.exported.name;
+    if (typeof specifier?.exported?.value === "string") return specifier.exported.value;
+    if (specifier?.local?.type === "Identifier") return specifier.local.name;
+    if (typeof specifier?.local?.value === "string") return specifier.local.value;
+    return void 0;
+  }
+  function getReexportedImportName(specifier) {
+    if (specifier?.local?.type === "Identifier") return specifier.local.name;
+    if (typeof specifier?.local?.value === "string") return specifier.local.value;
+    if (specifier?.imported?.type === "Identifier") return specifier.imported.name;
+    if (typeof specifier?.imported?.value === "string") return specifier.imported.value;
+    return getExportedName(specifier);
+  }
+  function getLocalExportName(specifier) {
+    if (specifier?.local?.type === "Identifier") return specifier.local.name;
+    if (typeof specifier?.local?.value === "string") return specifier.local.value;
+    return void 0;
+  }
+  function isExplicitlyRequestedExport(name) {
+    if (explicitlyRequestedExports === "*") return true;
+    return explicitlyRequestedExports?.has(name) ?? false;
+  }
   let isFallbackRoots = false;
   if (potentialClientRoots.length === 0) {
-    isFallbackRoots = true;
-    for (const node of resolvedProgram.body) {
-      if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") {
-        potentialClientRoots.push(node);
+    if (explicitlyRequestedExports) {
+      for (const node of resolvedProgram.body) {
+        if (node.type === "ExportNamedDeclaration") {
+          const exportNode = node;
+          if (exportNode.source && exportNode.specifiers?.length) {
+            const hasRequestedReexport = exportNode.specifiers.some((specifier) => {
+              const exportedName = getExportedName(specifier);
+              return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
+            });
+            if (hasRequestedReexport) {
+              potentialClientRoots.push(node);
+            }
+            continue;
+          }
+          if (exportNode.declaration?.type === "FunctionDeclaration" || exportNode.declaration?.type === "ClassDeclaration") {
+            const declarationName = exportNode.declaration.id?.name;
+            if (declarationName && isExplicitlyRequestedExport(declarationName)) {
+              potentialClientRoots.push(node);
+            }
+            continue;
+          }
+          if (exportNode.declaration?.type === "VariableDeclaration") {
+            const hasRequestedDeclaration = exportNode.declaration.declarations.some(
+              (declaration) => declaration.id?.type === "Identifier" && isExplicitlyRequestedExport(declaration.id.name)
+            );
+            if (hasRequestedDeclaration) {
+              potentialClientRoots.push(node);
+            }
+            continue;
+          }
+          if (exportNode.specifiers?.length) {
+            const hasRequestedSpecifier = exportNode.specifiers.some((specifier) => {
+              const exportedName = getExportedName(specifier);
+              return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
+            });
+            if (hasRequestedSpecifier) {
+              potentialClientRoots.push(node);
+            }
+          }
+        } else if (node.type === "ExportDefaultDeclaration") {
+          if (isExplicitlyRequestedExport("default")) {
+            potentialClientRoots.push(node);
+          }
+        } else if (node.type === "ExportAllDeclaration") {
+          if (explicitlyRequestedExports === "*") {
+            potentialClientRoots.push(node);
+          }
+        }
+      }
+    } else {
+      isFallbackRoots = true;
+      for (const node of resolvedProgram.body) {
+        if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") {
+          potentialClientRoots.push(node);
+        }
       }
     }
   }
@@ -167,6 +241,28 @@ function analyzeReachability(source, filename, program) {
       markImportReachable(node.source.value, "*");
       return;
     }
+    if (node.type === "ExportNamedDeclaration" && typeof node.source?.value === "string") {
+      for (const specifier of node.specifiers ?? []) {
+        const importedName = getReexportedImportName(specifier);
+        if (importedName) {
+          markImportReachable(node.source.value, importedName);
+        }
+      }
+      return;
+    }
+    if (node.type === "ExportNamedDeclaration" && !node.source && explicitlyRequestedExports && node.specifiers?.length) {
+      for (const specifier of node.specifiers) {
+        const exportedName = getExportedName(specifier);
+        if (!exportedName || !isExplicitlyRequestedExport(exportedName)) {
+          continue;
+        }
+        const localName = getLocalExportName(specifier);
+        if (localName && !currentScope.has(localName)) {
+          checkIdentifier(localName);
+        }
+      }
+      return;
+    }
     if (node.type === "Identifier" || node.type === "JSXIdentifier" && /^[A-Z]/.test(node.name)) {
       if (!currentScope.has(node.name)) {
         checkIdentifier(node.name);

package/src/utils/reachability-analyzer.ts

@@ -58,6 +58,16 @@ export type ReachabilityResult = {
 	analyzed: boolean;
 };
 
+/**
+ * Optional export filter supplied by the client graph boundary when a local
+ * module is imported through a narrower named-export surface.
+ *
+ * `'*'` means the whole module namespace is considered reachable, while a
+ * `Set` restricts analysis to the named exports that are actually requested by
+ * downstream client-reachable modules.
+ */
+type ExplicitlyRequestedExports = Set<string> | '*';
+
 /**
  * Analyzes a module using Oxc AST and extracts a strict reachability graph
  * starting from client roots (`render`, `errorBoundary`, `loadingFallback` of `eco.page` or `eco.component`).
@@ -66,11 +76,14 @@ export type ReachabilityResult = {
  * @param filename - Absolute or relative path to the module file.
  * @param program - Optional pre-parsed Oxc program AST. When supplied, the
  *   internal `parseSync` call is skipped entirely (avoids double-parsing).
+ * @param explicitlyRequestedExports - Optional named export filter propagated
+ *   from a downstream importer when this module is only partially reachable.
  */
 export function analyzeReachability(
 	source: string,
 	filename: string,
 	program?: ReturnType<typeof parseSync>['program'],
+	explicitlyRequestedExports?: ExplicitlyRequestedExports,
 ): ReachabilityResult {
 	/**
 	 * AST Resolution
@@ -242,6 +255,57 @@ export function analyzeReachability(
 		}
 	}
 
+	/**
+	 * Resolves the externally visible export name from an export specifier.
+	 *
+	 * @param specifier - Oxc export specifier node.
+	 * @returns The exported binding name when available.
+	 */
+	function getExportedName(specifier: any): string | undefined {
+		if (specifier?.exported?.type === 'Identifier') return specifier.exported.name;
+		if (typeof specifier?.exported?.value === 'string') return specifier.exported.value;
+		if (specifier?.local?.type === 'Identifier') return specifier.local.name;
+		if (typeof specifier?.local?.value === 'string') return specifier.local.value;
+		return undefined;
+	}
+
+	/**
+	 * Resolves the imported binding name represented by a re-export specifier.
+	 *
+	 * @param specifier - Oxc export specifier node.
+	 * @returns The source-module binding name that should be marked reachable.
+	 */
+	function getReexportedImportName(specifier: any): string | undefined {
+		if (specifier?.local?.type === 'Identifier') return specifier.local.name;
+		if (typeof specifier?.local?.value === 'string') return specifier.local.value;
+		if (specifier?.imported?.type === 'Identifier') return specifier.imported.name;
+		if (typeof specifier?.imported?.value === 'string') return specifier.imported.value;
+		return getExportedName(specifier);
+	}
+
+	/**
+	 * Resolves the local identifier used by a local export list entry.
+	 *
+	 * @param specifier - Oxc export specifier node.
+	 * @returns The local symbol name referenced by the export list.
+	 */
+	function getLocalExportName(specifier: any): string | undefined {
+		if (specifier?.local?.type === 'Identifier') return specifier.local.name;
+		if (typeof specifier?.local?.value === 'string') return specifier.local.value;
+		return undefined;
+	}
+
+	/**
+	 * Checks whether a named export is part of the explicitly requested subset.
+	 *
+	 * @param name - Export name to test.
+	 * @returns True when the export should seed or continue traversal.
+	 */
+	function isExplicitlyRequestedExport(name: string): boolean {
+		if (explicitlyRequestedExports === '*') return true;
+		return explicitlyRequestedExports?.has(name) ?? false;
+	}
+
 	/**
 	 * Client root resolution (fallback mode)
 	 *
@@ -255,14 +319,73 @@ export function analyzeReachability(
 	 */
 	let isFallbackRoots = false;
 	if (potentialClientRoots.length === 0) {
-		isFallbackRoots = true;
-		for (const node of resolvedProgram.body) {
-			if (
-				(node as { type: string }).type === 'ExportNamedDeclaration' ||
-				(node as { type: string }).type === 'ExportDefaultDeclaration' ||
-				(node as { type: string }).type === 'ExportAllDeclaration'
-			) {
-				potentialClientRoots.push(node);
+		if (explicitlyRequestedExports) {
+			for (const node of resolvedProgram.body) {
+				if ((node as { type: string }).type === 'ExportNamedDeclaration') {
+					const exportNode = node as any;
+					if (exportNode.source && exportNode.specifiers?.length) {
+						const hasRequestedReexport = exportNode.specifiers.some((specifier: any) => {
+							const exportedName = getExportedName(specifier);
+							return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
+						});
+						if (hasRequestedReexport) {
+							potentialClientRoots.push(node);
+						}
+						continue;
+					}
+
+					if (
+						exportNode.declaration?.type === 'FunctionDeclaration' ||
+						exportNode.declaration?.type === 'ClassDeclaration'
+					) {
+						const declarationName = exportNode.declaration.id?.name;
+						if (declarationName && isExplicitlyRequestedExport(declarationName)) {
+							potentialClientRoots.push(node);
+						}
+						continue;
+					}
+
+					if (exportNode.declaration?.type === 'VariableDeclaration') {
+						const hasRequestedDeclaration = exportNode.declaration.declarations.some(
+							(declaration: any) =>
+								declaration.id?.type === 'Identifier' &&
+								isExplicitlyRequestedExport(declaration.id.name),
+						);
+						if (hasRequestedDeclaration) {
+							potentialClientRoots.push(node);
+						}
+						continue;
+					}
+
+					if (exportNode.specifiers?.length) {
+						const hasRequestedSpecifier = exportNode.specifiers.some((specifier: any) => {
+							const exportedName = getExportedName(specifier);
+							return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
+						});
+						if (hasRequestedSpecifier) {
+							potentialClientRoots.push(node);
+						}
+					}
+				} else if ((node as { type: string }).type === 'ExportDefaultDeclaration') {
+					if (isExplicitlyRequestedExport('default')) {
+						potentialClientRoots.push(node);
+					}
+				} else if ((node as { type: string }).type === 'ExportAllDeclaration') {
+					if (explicitlyRequestedExports === '*') {
+						potentialClientRoots.push(node);
+					}
+				}
+			}
+		} else {
+			isFallbackRoots = true;
+			for (const node of resolvedProgram.body) {
+				if (
+					(node as { type: string }).type === 'ExportNamedDeclaration' ||
+					(node as { type: string }).type === 'ExportDefaultDeclaration' ||
+					(node as { type: string }).type === 'ExportAllDeclaration'
+				) {
+					potentialClientRoots.push(node);
+				}
 			}
 		}
 	}
@@ -353,6 +476,36 @@ export function analyzeReachability(
 			return;
 		}
 
+		if (node.type === 'ExportNamedDeclaration' && typeof node.source?.value === 'string') {
+			for (const specifier of node.specifiers ?? []) {
+				const importedName = getReexportedImportName(specifier);
+				if (importedName) {
+					markImportReachable(node.source.value as string, importedName);
+				}
+			}
+			return;
+		}
+
+		if (
+			node.type === 'ExportNamedDeclaration' &&
+			!node.source &&
+			explicitlyRequestedExports &&
+			node.specifiers?.length
+		) {
+			for (const specifier of node.specifiers) {
+				const exportedName = getExportedName(specifier);
+				if (!exportedName || !isExplicitlyRequestedExport(exportedName)) {
+					continue;
+				}
+
+				const localName = getLocalExportName(specifier);
+				if (localName && !currentScope.has(localName)) {
+					checkIdentifier(localName);
+				}
+			}
+			return;
+		}
+
 		if (node.type === 'Identifier' || (node.type === 'JSXIdentifier' && /^[A-Z]/.test(node.name))) {
 			if (!currentScope.has(node.name)) {
 				checkIdentifier(node.name);