@ecopages/react 0.2.0-beta.31 → 0.2.0-beta.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +5 -1
  2. package/package.json +4 -4
  3. package/src/app/client-only.js +13 -17
  4. package/src/app/dynamic.js +7 -10
  5. package/src/app/dynamic.test.browser.js +27 -29
  6. package/src/bundling/bootstrap-package-paths.js +5 -6
  7. package/src/bundling/bundle.js +115 -114
  8. package/src/bundling/discover-layout-runtime-modules.js +166 -155
  9. package/src/bundling/runtime-alias-map.d.ts +4 -1
  10. package/src/bundling/runtime-alias-map.js +107 -95
  11. package/src/bundling/runtime-bundle.js +250 -274
  12. package/src/bundling/runtime-interop-plugin.js +31 -35
  13. package/src/bundling/runtime-mode.js +10 -5
  14. package/src/bundling/runtime-modules.js +46 -35
  15. package/src/client-graph/ast-transform.js +415 -305
  16. package/src/client-graph/boundary-cache.js +146 -104
  17. package/src/client-graph/boundary-plugin.js +122 -104
  18. package/src/client-graph/component-config-traversal.js +70 -49
  19. package/src/client-graph/declared-modules.js +63 -41
  20. package/src/client-graph/reachability-analyzer.js +506 -313
  21. package/src/client-graph/specifier-classification.js +209 -141
  22. package/src/contracts/router-adapter.js +6 -0
  23. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  24. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  25. package/src/hmr/hmr-scripts.js +22 -9
  26. package/src/hmr/hmr-strategy.d.ts +12 -181
  27. package/src/hmr/hmr-strategy.js +321 -650
  28. package/src/hmr/page-metadata-cache.js +43 -40
  29. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  30. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  31. package/src/hydration/assert-no-bare-ecopages-imports.js +6 -6
  32. package/src/hydration/bootstrap-imports.js +30 -20
  33. package/src/hydration/hydration-asset.js +216 -213
  34. package/src/hydration/hydration-scripts.d.ts +4 -0
  35. package/src/hydration/hydration-scripts.js +199 -66
  36. package/src/hydration/hydration-scripts.test.browser.js +163 -168
  37. package/src/hydration/page-data-manifest.js +89 -45
  38. package/src/hydration/page-data-reader.js +45 -32
  39. package/src/hydration/page-payload.js +101 -99
  40. package/src/hydration/serialize-page-data-script.js +27 -28
  41. package/src/mdx/mdx-config-dependency.js +108 -112
  42. package/src/mdx/mdx-loader-plugin.js +7 -10
  43. package/src/page/page-module.js +72 -66
  44. package/src/plugin/react.constants.js +1 -4
  45. package/src/plugin/react.plugin.d.ts +1 -0
  46. package/src/plugin/react.plugin.js +227 -216
  47. package/src/plugin/react.types.js +1 -0
  48. package/src/render/component-ownership.js +42 -18
  49. package/src/render/component-ssr.js +168 -190
  50. package/src/render/eco-embed.js +8 -10
  51. package/src/render/errors.js +21 -16
  52. package/src/render/html-boundary.js +55 -51
  53. package/src/render/layout-compose.js +122 -94
  54. package/src/render/react-renderer.js +433 -468
  55. package/src/render/react-runtime.js +25 -20
  56. package/src/render/unified-layout-composition.js +74 -85
  57. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
package/README.md CHANGED
@@ -30,7 +30,7 @@ export default config;
30
30
  For component-level islands, Ecopages React uses this contract:
31
31
 
32
32
  - SSR output preserves the authored DOM structure (no unnecessary wrapper elements).
33
- - A stable `data-eco-component-id` attribute is attached to the component SSR root.
33
+ - A stable island host contract is stamped on the component SSR root via core (`data-eco-island`, `data-eco-island-integration`, `data-eco-component-id`, optional `data-eco-component-key` / `data-eco-props`).
34
34
  - The island runtime replaces the SSR host with a dedicated client-owned container and mounts it with `createRoot()`. Full-page hydration paths use `hydrateRoot()`.
35
35
 
36
36
  > [!TIP]
@@ -237,6 +237,10 @@ That creates a module identity problem: if TanStack Query (or any shared provide
237
237
 
238
238
  The fix is **shared browser runtime vendors**: selected npm packages are built once into `/assets/vendors/*.js` and every page chunk imports the same public URL. React, React DOM, the router bundle, and auto-discovered layout runtime packages all follow this path.
239
239
 
240
+ In `ecopages dev`, page modules are served from `/assets/__eco_dev__/` and should import `/assets/vendors/*` for shared packages instead of inlining `node_modules`. Kitchen-sink routes `/vendor-share/a` and `/vendor-share/b` (with `runtimeModules: ['zod']`) are the reference fixture; see `playground/kitchen-sink/e2e/shared-vendors.test.e2e.ts`.
241
+
242
+ The Ecopages dev toolbar **Islands** app inspects `data-eco-island`, `data-eco-component-id`, `data-eco-props`, and `window.__ECO_PAGES__.islandRoots` during development.
243
+
240
244
  Auto-discovery removes the need to hand-maintain `runtimeModules` for the common case — a query-client layout that imports `@tanstack/react-query` is enough when discovery is configured correctly.
241
245
 
242
246
  #### When auto-discovery runs
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecopages/react",
3
- "version": "0.2.0-beta.31",
3
+ "version": "0.2.0-beta.33",
4
4
  "description": "React integration for Ecopages",
5
5
  "keywords": [
6
6
  "ecopages",
@@ -93,16 +93,16 @@
93
93
  "directory": "packages/integrations/react"
94
94
  },
95
95
  "peerDependencies": {
96
- "@ecopages/core": "0.2.0-beta.31",
96
+ "@ecopages/core": "0.2.0-beta.33",
97
97
  "@types/react": "^19",
98
98
  "@types/react-dom": "^19",
99
99
  "react": "^19",
100
100
  "react-dom": "^19"
101
101
  },
102
102
  "dependencies": {
103
- "@ecopages/file-system": "0.2.0-beta.31",
103
+ "@ecopages/file-system": "0.2.0-beta.33",
104
104
  "@ecopages/logger": "^0.2.3",
105
- "@ecopages/mdx": "0.2.0-beta.31",
105
+ "@ecopages/mdx": "0.2.0-beta.33",
106
106
  "@mdx-js/mdx": "^3.1.1",
107
107
  "oxc-parser": "^0.124.0",
108
108
  "oxc-transform": "^0.124.0",
@@ -1,19 +1,15 @@
1
- import { useEffect, useState } from "react";
2
- const useIsClient = () => {
3
- const [isClient, setIsClient] = useState(false);
4
- useEffect(() => {
5
- setIsClient(true);
6
- }, []);
7
- return isClient;
1
+ import { useEffect, useState } from 'react';
2
+ export const useIsClient = () => {
3
+ const [isClient, setIsClient] = useState(false);
4
+ useEffect(() => {
5
+ setIsClient(true);
6
+ }, []);
7
+ return isClient;
8
8
  };
9
- const ClientOnly = ({ children, fallback = null }) => {
10
- const isClient = useIsClient();
11
- if (!isClient) {
12
- return fallback;
13
- }
14
- return children;
15
- };
16
- export {
17
- ClientOnly,
18
- useIsClient
9
+ export const ClientOnly = ({ children, fallback = null }) => {
10
+ const isClient = useIsClient();
11
+ if (!isClient) {
12
+ return fallback;
13
+ }
14
+ return children;
19
15
  };
@@ -1,12 +1,9 @@
1
- import { lazy } from "react";
1
+ import { lazy } from 'react';
2
2
  const NullComponent = () => null;
3
- function dynamic(importFn, options = {}) {
4
- const { ssr = false } = options;
5
- if (ssr || typeof window !== "undefined") {
6
- return lazy(importFn);
7
- }
8
- return NullComponent;
3
+ export function dynamic(importFn, options = {}) {
4
+ const { ssr = false } = options;
5
+ if (ssr || typeof window !== 'undefined') {
6
+ return lazy(importFn);
7
+ }
8
+ return NullComponent;
9
9
  }
10
- export {
11
- dynamic
12
- };
@@ -1,33 +1,31 @@
1
- import { jsx } from "react/jsx-runtime";
2
- import { Suspense } from "react";
3
- import { afterEach, describe, expect, it } from "vitest";
4
- import { cleanup, render, screen } from "@testing-library/react";
5
- import { dynamic } from "./dynamic.js";
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { Suspense } from 'react';
3
+ import { afterEach, describe, expect, it } from 'vitest';
4
+ import { cleanup, render, screen } from '@testing-library/react';
5
+ import { dynamic } from './dynamic.js';
6
6
  function createDeferredImport() {
7
- let resolve;
8
- const promise = new Promise((innerResolve) => {
9
- resolve = innerResolve;
10
- });
11
- return {
12
- promise,
13
- resolve
14
- };
7
+ let resolve;
8
+ const promise = new Promise((innerResolve) => {
9
+ resolve = innerResolve;
10
+ });
11
+ return {
12
+ promise,
13
+ resolve,
14
+ };
15
15
  }
16
- describe("dynamic", () => {
17
- afterEach(() => {
18
- cleanup();
19
- });
20
- it("returns a browser lazy component that resolves through Suspense", async () => {
21
- const deferredImport = createDeferredImport();
22
- const DynamicComponent = dynamic(() => deferredImport.promise);
23
- render(
24
- /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx("span", { children: "Loading dynamic component" }), children: /* @__PURE__ */ jsx(DynamicComponent, {}) })
25
- );
26
- expect(screen.getByText("Loading dynamic component")).toBeTruthy();
27
- deferredImport.resolve({
28
- default: () => /* @__PURE__ */ jsx("span", { children: "Dynamic content" })
16
+ describe('dynamic', () => {
17
+ afterEach(() => {
18
+ cleanup();
19
+ });
20
+ it('returns a browser lazy component that resolves through Suspense', async () => {
21
+ const deferredImport = createDeferredImport();
22
+ const DynamicComponent = dynamic(() => deferredImport.promise);
23
+ render(_jsx(Suspense, { fallback: _jsx("span", { children: "Loading dynamic component" }), children: _jsx(DynamicComponent, {}) }));
24
+ expect(screen.getByText('Loading dynamic component')).toBeTruthy();
25
+ deferredImport.resolve({
26
+ default: () => _jsx("span", { children: "Dynamic content" }),
27
+ });
28
+ expect(await screen.findByText('Dynamic content')).toBeTruthy();
29
+ expect(screen.queryByText('Loading dynamic component')).toBeNull();
29
30
  });
30
- expect(await screen.findByText("Dynamic content")).toBeTruthy();
31
- expect(screen.queryByText("Loading dynamic component")).toBeNull();
32
- });
33
31
  });
@@ -1,6 +1,5 @@
1
- const PAGE_LAYOUT_NORMALIZATION_PACKAGE = "@ecopages/core/eco/page-layout-normalization";
2
- const LAYOUT_COMPOSE_PACKAGE = "@ecopages/react/layout-compose";
3
- export {
4
- LAYOUT_COMPOSE_PACKAGE,
5
- PAGE_LAYOUT_NORMALIZATION_PACKAGE
6
- };
1
+ /**
2
+ * Bare package specifiers for React page hydration bootstrap helpers.
3
+ */
4
+ export const PAGE_LAYOUT_NORMALIZATION_PACKAGE = '@ecopages/core/eco/page-layout-normalization';
5
+ export const LAYOUT_COMPOSE_PACKAGE = '@ecopages/react/layout-compose';
@@ -1,118 +1,119 @@
1
- import { createClientGraphBoundaryPlugin } from "../client-graph/boundary-plugin.js";
2
- import { getReactClientGraphAllowSpecifiers, getReactRuntimeExternalSpecifiers } from "./runtime-alias-map.js";
3
- import { createBrowserRuntimePlugin } from "@ecopages/core/build/browser-runtime-plugin";
4
- import { getHostScopedJsxOwnershipPlugins } from "@ecopages/core/build/jsx-ownership-plugins";
5
- import { RuntimeBundleService } from "./runtime-bundle.js";
6
- import { createReactMdxLoaderPlugin } from "../mdx/mdx-loader-plugin.js";
7
- import { isReactProductionRuntime } from "./runtime-mode.js";
8
- class BundleService {
9
- runtimeBundleService;
10
- config;
11
- pageLayoutNormalizationVendorPromise;
12
- constructor(config) {
13
- this.config = config;
14
- this.runtimeBundleService = new RuntimeBundleService({
15
- rootDir: config.rootDir,
16
- routerAdapter: config.routerAdapter,
17
- runtimeModules: config.runtimeModules
18
- });
19
- }
20
- /**
21
- * Returns resolved runtime import paths for the React runtime.
22
- */
23
- getRuntimeImports() {
24
- return this.runtimeBundleService.getRuntimeImports();
25
- }
26
- /**
27
- * Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
28
- *
29
- * @remarks
30
- * Concurrent callers share the same in-flight promise. Asset processing itself caches
31
- * by dependency key, so repeats after success remain cheap.
32
- */
33
- async ensurePageLayoutNormalizationVendorProcessed(assetProcessingService) {
34
- if (!this.pageLayoutNormalizationVendorPromise) {
35
- this.pageLayoutNormalizationVendorPromise = assetProcessingService.processDependencies(
36
- this.runtimeBundleService.getPageLayoutNormalizationDependencies(),
37
- "react:page-layout-normalization"
38
- ).then(() => void 0).catch((error) => {
39
- this.pageLayoutNormalizationVendorPromise = void 0;
40
- throw error;
41
- });
1
+ /**
2
+ * Bundle configuration service for React integration.
3
+ *
4
+ * Encapsulates all build plugin creation and bundle options
5
+ * for client-side React component builds.
6
+ *
7
+ * @module
8
+ */
9
+ import { createClientGraphBoundaryPlugin } from '../client-graph/boundary-plugin.js';
10
+ import { getReactClientGraphAllowSpecifiers, getReactRuntimeExternalSpecifiers } from './runtime-alias-map.js';
11
+ import { createBrowserRuntimePlugin } from '@ecopages/core/build/browser-runtime-plugin';
12
+ import { getHostScopedJsxOwnershipPlugins } from '@ecopages/core/build/jsx-ownership-plugins';
13
+ import { RuntimeBundleService } from './runtime-bundle.js';
14
+ import { createReactMdxLoaderPlugin } from '../mdx/mdx-loader-plugin.js';
15
+ import { isReactProductionRuntime } from './runtime-mode.js';
16
+ /**
17
+ * Manages bundle configuration and plugin creation for React page/component builds.
18
+ */
19
+ export class BundleService {
20
+ runtimeBundleService;
21
+ config;
22
+ pageLayoutNormalizationVendorPromise;
23
+ constructor(config) {
24
+ this.config = config;
25
+ this.runtimeBundleService = new RuntimeBundleService({
26
+ rootDir: config.rootDir,
27
+ routerAdapter: config.routerAdapter,
28
+ runtimeModules: config.runtimeModules,
29
+ });
42
30
  }
43
- await this.pageLayoutNormalizationVendorPromise;
44
- }
45
- /**
46
- * Creates bundle options for a page or component entry.
47
- *
48
- * @remarks
49
- * React derives runtime specifier mappings from the core browser runtime manifest
50
- * so ESM imports resolve to concrete runtime asset URLs during module loading.
51
- *
52
- * @param componentName - Generated unique component name for output naming
53
- * @param isMdx - Whether the source file is an MDX file
54
- * @param declaredModules - Explicitly declared browser module specifiers
55
- * @returns Bundle options object for the build adapter
56
- */
57
- async createBundleOptions(componentName, isMdx, declaredModules, bundleOptions = {}) {
58
- const runtimeImports = this.getRuntimeImports();
59
- const options = {
60
- mainFields: ["module", "browser", "main"],
61
- naming: `${componentName}.[ext]`,
62
- ...isReactProductionRuntime() && {
63
- minify: true,
64
- treeshaking: true
65
- },
66
- ...bundleOptions.splitting === void 0 ? {} : { splitting: bundleOptions.splitting }
67
- };
68
- if (!bundleOptions.includeRuntime) {
69
- const reactRuntimeSpecifiers = new Set(getReactRuntimeExternalSpecifiers());
70
- options.external = [
71
- ...Object.values(runtimeImports).filter(
72
- (specifier) => Boolean(specifier) && !reactRuntimeSpecifiers.has(
73
- specifier
74
- )
75
- )
76
- ];
31
+ /**
32
+ * Returns resolved runtime import paths for the React runtime.
33
+ */
34
+ getRuntimeImports() {
35
+ return this.runtimeBundleService.getRuntimeImports();
77
36
  }
78
- const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
79
- projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
80
- absWorkingDir: this.config.rootDir,
81
- declaredModules,
82
- alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(
83
- this.runtimeBundleService.getConfiguredRuntimeModuleSpecifiers(),
84
- this.config.routerAdapter
85
- )
86
- });
87
- const [foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(
88
- this.config.appConfig,
89
- this.config.hostIntegrationName,
90
- { name: "react-renderer-foreign-jsx-override" }
91
- );
92
- const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
93
- const runtimeRewritePlugin = createBrowserRuntimePlugin({
94
- name: "react-renderer-runtime-import-rewrite",
95
- manifest: runtimeManifest
96
- });
97
- const runtimePlugins = bundleOptions.includeRuntime ? [] : [runtimeRewritePlugin].filter((plugin) => plugin !== null);
98
- if (isMdx && this.config.mdxCompilerOptions) {
99
- const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
100
- options.plugins = [
101
- ...foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : [],
102
- graphBoundaryPlugin,
103
- ...runtimePlugins,
104
- mdxPlugin
105
- ];
106
- } else {
107
- options.plugins = [
108
- ...foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : [],
109
- graphBoundaryPlugin,
110
- ...runtimePlugins
111
- ];
37
+ /**
38
+ * Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
39
+ *
40
+ * @remarks
41
+ * Concurrent callers share the same in-flight promise. Asset processing itself caches
42
+ * by dependency key, so repeats after success remain cheap.
43
+ */
44
+ async ensurePageLayoutNormalizationVendorProcessed(assetProcessingService) {
45
+ if (!this.pageLayoutNormalizationVendorPromise) {
46
+ this.pageLayoutNormalizationVendorPromise = assetProcessingService
47
+ .processDependencies(this.runtimeBundleService.getPageLayoutNormalizationDependencies(), 'react:page-layout-normalization')
48
+ .then(() => undefined)
49
+ .catch((error) => {
50
+ this.pageLayoutNormalizationVendorPromise = undefined;
51
+ throw error;
52
+ });
53
+ }
54
+ await this.pageLayoutNormalizationVendorPromise;
55
+ }
56
+ /**
57
+ * Creates bundle options for a page or component entry.
58
+ *
59
+ * @remarks
60
+ * React derives runtime specifier mappings from the core browser runtime manifest
61
+ * so ESM imports resolve to concrete runtime asset URLs during module loading.
62
+ *
63
+ * @param componentName - Generated unique component name for output naming
64
+ * @param isMdx - Whether the source file is an MDX file
65
+ * @param declaredModules - Explicitly declared browser module specifiers
66
+ * @returns Bundle options object for the build adapter
67
+ */
68
+ async createBundleOptions(componentName, isMdx, declaredModules, bundleOptions = {}) {
69
+ const runtimeImports = this.getRuntimeImports();
70
+ const options = {
71
+ mainFields: ['module', 'browser', 'main'],
72
+ naming: `${componentName}.[ext]`,
73
+ ...(isReactProductionRuntime() && {
74
+ minify: true,
75
+ treeshaking: true,
76
+ }),
77
+ ...(bundleOptions.splitting === undefined ? {} : { splitting: bundleOptions.splitting }),
78
+ };
79
+ if (!bundleOptions.includeRuntime) {
80
+ const reactRuntimeSpecifiers = new Set(getReactRuntimeExternalSpecifiers());
81
+ options.external = [
82
+ ...Object.values(runtimeImports).filter((specifier) => Boolean(specifier) &&
83
+ !reactRuntimeSpecifiers.has(specifier)),
84
+ ];
85
+ }
86
+ const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
87
+ projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
88
+ absWorkingDir: this.config.rootDir,
89
+ declaredModules,
90
+ alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(this.runtimeBundleService.getConfiguredRuntimeModuleSpecifiers(), this.config.routerAdapter),
91
+ });
92
+ const [foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(this.config.appConfig, this.config.hostIntegrationName, { name: 'react-renderer-foreign-jsx-override' });
93
+ const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
94
+ const runtimeRewritePlugin = createBrowserRuntimePlugin({
95
+ name: 'react-renderer-runtime-import-rewrite',
96
+ manifest: runtimeManifest,
97
+ });
98
+ const runtimePlugins = bundleOptions.includeRuntime
99
+ ? []
100
+ : [runtimeRewritePlugin].filter((plugin) => plugin !== null);
101
+ if (isMdx && this.config.mdxCompilerOptions) {
102
+ const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
103
+ options.plugins = [
104
+ ...(foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : []),
105
+ graphBoundaryPlugin,
106
+ ...runtimePlugins,
107
+ mdxPlugin,
108
+ ];
109
+ }
110
+ else {
111
+ options.plugins = [
112
+ ...(foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : []),
113
+ graphBoundaryPlugin,
114
+ ...runtimePlugins,
115
+ ];
116
+ }
117
+ return options;
112
118
  }
113
- return options;
114
- }
115
119
  }
116
- export {
117
- BundleService
118
- };