@ecopages/react 0.2.1 → 0.3.1

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 (167) hide show
  1. package/README.md +179 -35
  2. package/package.json +78 -33
  3. package/src/app/client-only.js +10 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  6. package/src/bundling/bootstrap-package-paths.js +5 -0
  7. package/src/bundling/bundle.d.ts +78 -0
  8. package/src/bundling/bundle.js +130 -0
  9. package/src/bundling/runtime-alias-map.d.ts +12 -0
  10. package/src/bundling/runtime-alias-map.js +110 -0
  11. package/src/bundling/runtime-bundle.d.ts +70 -0
  12. package/src/bundling/runtime-bundle.js +233 -0
  13. package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +1 -1
  14. package/src/bundling/runtime-interop-plugin.js +32 -0
  15. package/src/bundling/runtime-mode.d.ts +1 -0
  16. package/src/bundling/runtime-mode.js +10 -0
  17. package/src/bundling/runtime-modules.d.ts +21 -0
  18. package/src/bundling/runtime-modules.js +28 -0
  19. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  20. package/src/client-graph/ast-transform-eco-page.js +71 -0
  21. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  22. package/src/client-graph/ast-transform-import-edits.js +75 -0
  23. package/src/client-graph/ast-transform-walk-imports.d.ts +20 -0
  24. package/src/client-graph/ast-transform-walk-imports.js +105 -0
  25. package/src/client-graph/ast-transform.d.ts +12 -0
  26. package/src/client-graph/ast-transform.js +91 -0
  27. package/src/client-graph/ast-walk.d.ts +10 -0
  28. package/src/client-graph/ast-walk.js +26 -0
  29. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +7 -0
  30. package/src/client-graph/boundary-plugin-read-file-inline.js +43 -0
  31. package/src/client-graph/boundary-plugin-transform.d.ts +16 -0
  32. package/src/client-graph/boundary-plugin-transform.js +31 -0
  33. package/src/client-graph/boundary-plugin.d.ts +23 -0
  34. package/src/client-graph/boundary-plugin.js +177 -0
  35. package/src/client-graph/component-config-traversal.d.ts +36 -0
  36. package/src/client-graph/component-config-traversal.js +77 -0
  37. package/src/{utils → client-graph}/declared-modules.d.ts +1 -1
  38. package/src/client-graph/declared-modules.js +69 -0
  39. package/src/client-graph/module-classification.d.ts +3 -0
  40. package/src/client-graph/module-classification.js +43 -0
  41. package/src/client-graph/reachability-analyzer.d.ts +26 -0
  42. package/src/client-graph/reachability-analyzer.js +55 -0
  43. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  44. package/src/client-graph/reachability-client-roots.js +59 -0
  45. package/src/client-graph/reachability-export-names.d.ts +5 -0
  46. package/src/client-graph/reachability-export-names.js +34 -0
  47. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  48. package/src/client-graph/reachability-fallback-roots.js +71 -0
  49. package/src/client-graph/reachability-preload.d.ts +10 -0
  50. package/src/client-graph/reachability-preload.js +30 -0
  51. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  52. package/src/client-graph/reachability-top-level-index.js +93 -0
  53. package/src/client-graph/reachability-traverse.d.ts +7 -0
  54. package/src/client-graph/reachability-traverse.js +201 -0
  55. package/src/client-graph/specifier-classification.d.ts +74 -0
  56. package/src/client-graph/specifier-classification.js +191 -0
  57. package/src/content/collection-component-cache.d.ts +25 -0
  58. package/src/content/collection-component-cache.js +62 -0
  59. package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +7 -14
  60. package/src/contracts/router-adapter.js +6 -0
  61. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  62. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  63. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  64. package/src/hmr/hmr-strategy-process.js +83 -0
  65. package/src/hmr/hmr-strategy.d.ts +67 -0
  66. package/src/hmr/hmr-strategy.js +306 -0
  67. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +6 -2
  68. package/src/hmr/page-metadata-cache.js +44 -0
  69. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +22 -0
  70. package/src/hmr/react-hmr-dev-transform-plugins.js +19 -0
  71. package/src/hydration/bootstrap-imports.d.ts +25 -0
  72. package/src/hydration/bootstrap-imports.js +33 -0
  73. package/src/hydration/browser/island-hydration.d.ts +81 -0
  74. package/src/hydration/browser/island-hydration.js +247 -0
  75. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  76. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  77. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  78. package/src/hydration/browser/page-hydration-module.js +17 -0
  79. package/src/hydration/browser/page-hydration.d.ts +54 -0
  80. package/src/hydration/browser/page-hydration.js +177 -0
  81. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  82. package/src/hydration/compiled-page-hydration-options.js +1 -0
  83. package/src/hydration/hydration-asset.d.ts +128 -0
  84. package/src/hydration/hydration-asset.js +388 -0
  85. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  86. package/src/hydration/hydration-page-entry-source.js +87 -0
  87. package/src/hydration/hydration-script-compiler.d.ts +47 -0
  88. package/src/hydration/hydration-script-compiler.js +213 -0
  89. package/src/hydration/page-data-manifest.d.ts +58 -0
  90. package/src/hydration/page-data-manifest.js +97 -0
  91. package/src/hydration/page-data-reader.d.ts +17 -0
  92. package/src/hydration/page-data-reader.js +31 -0
  93. package/src/hydration/page-payload.d.ts +68 -0
  94. package/src/hydration/page-payload.js +106 -0
  95. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  96. package/src/hydration/serialize-page-data-script.js +30 -0
  97. package/src/mdx/mdx-config-dependency.d.ts +37 -0
  98. package/src/mdx/mdx-config-dependency.js +107 -0
  99. package/src/mdx/mdx-loader-plugin.d.ts +8 -0
  100. package/src/mdx/mdx-loader-plugin.js +11 -0
  101. package/src/page/page-module.d.ts +46 -0
  102. package/src/page/page-module.js +74 -0
  103. package/src/plugin/react.constants.d.ts +1 -0
  104. package/src/plugin/react.constants.js +1 -0
  105. package/src/plugin/react.plugin.d.ts +71 -0
  106. package/src/plugin/react.plugin.js +210 -0
  107. package/src/plugin/react.types.d.ts +106 -0
  108. package/src/plugin/react.types.js +1 -0
  109. package/src/render/component-ownership.d.ts +49 -0
  110. package/src/render/component-ownership.js +47 -0
  111. package/src/render/component-ssr.d.ts +59 -0
  112. package/src/render/component-ssr.js +76 -0
  113. package/src/render/eco-embed.d.ts +11 -0
  114. package/src/render/eco-embed.js +9 -0
  115. package/src/render/errors.d.ts +16 -0
  116. package/src/render/errors.js +23 -0
  117. package/src/render/html-boundary.js +59 -0
  118. package/src/render/layout-compose.d.ts +66 -0
  119. package/src/render/layout-compose.js +134 -0
  120. package/src/render/react-renderer.d.ts +114 -0
  121. package/src/render/react-renderer.js +490 -0
  122. package/src/render/react-runtime.d.ts +13 -0
  123. package/src/render/react-runtime.js +26 -0
  124. package/src/render/unified-layout-composition.d.ts +22 -0
  125. package/src/render/unified-layout-composition.js +31 -0
  126. package/src/runtime/use-sync-external-store-with-selector.d.ts +3 -0
  127. package/src/runtime/use-sync-external-store-with-selector.js +54 -0
  128. package/CHANGELOG.md +0 -29
  129. package/src/react-hmr-strategy.d.ts +0 -148
  130. package/src/react-hmr-strategy.js +0 -313
  131. package/src/react-renderer.d.ts +0 -213
  132. package/src/react-renderer.js +0 -654
  133. package/src/react.plugin.d.ts +0 -147
  134. package/src/react.plugin.js +0 -146
  135. package/src/router-adapter.js +0 -0
  136. package/src/services/react-bundle.service.d.ts +0 -47
  137. package/src/services/react-bundle.service.js +0 -93
  138. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  139. package/src/services/react-hydration-asset.service.d.ts +0 -76
  140. package/src/services/react-hydration-asset.service.js +0 -210
  141. package/src/services/react-page-module.service.d.ts +0 -83
  142. package/src/services/react-page-module.service.js +0 -162
  143. package/src/services/react-runtime-bundle.service.d.ts +0 -40
  144. package/src/services/react-runtime-bundle.service.js +0 -130
  145. package/src/utils/client-graph-boundary-plugin.d.ts +0 -43
  146. package/src/utils/client-graph-boundary-plugin.js +0 -494
  147. package/src/utils/client-only.js +0 -19
  148. package/src/utils/declared-modules.js +0 -59
  149. package/src/utils/dynamic.js +0 -12
  150. package/src/utils/hmr-scripts.d.ts +0 -18
  151. package/src/utils/hmr-scripts.js +0 -31
  152. package/src/utils/html-boundary.js +0 -55
  153. package/src/utils/hydration-scripts.d.ts +0 -86
  154. package/src/utils/hydration-scripts.js +0 -285
  155. package/src/utils/reachability-analyzer.d.ts +0 -66
  156. package/src/utils/reachability-analyzer.js +0 -339
  157. package/src/utils/react-dom-runtime-interop-plugin.js +0 -29
  158. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  159. package/src/utils/react-mdx-loader-plugin.js +0 -45
  160. package/src/utils/react-runtime-specifier-map.d.ts +0 -6
  161. package/src/utils/react-runtime-specifier-map.js +0 -37
  162. package/src/utils/use-sync-external-store-shim-plugin.d.ts +0 -5
  163. package/src/utils/use-sync-external-store-shim-plugin.js +0 -41
  164. /package/src/{utils → app}/client-only.d.ts +0 -0
  165. /package/src/{utils → app}/dynamic.d.ts +0 -0
  166. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  167. /package/src/{utils → render}/html-boundary.d.ts +0 -0
package/README.md CHANGED
@@ -5,7 +5,8 @@ First-class integration for [React 19](https://react.dev/) in Ecopages. This plu
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
- bunx jsr add @ecopages/react
8
+ bun add @ecopages/react react react-dom
9
+ bun add -d @types/react @types/react-dom
9
10
  ```
10
11
 
11
12
  ## Usage
@@ -13,51 +14,45 @@ bunx jsr add @ecopages/react
13
14
  Configure the plugin in your `eco.config.ts`:
14
15
 
15
16
  ```ts
16
- import { ConfigBuilder } from '@ecopages/core/config-builder';
17
+ import { defineConfig } from '@ecopages/core/config';
17
18
  import { reactPlugin } from '@ecopages/react';
18
19
 
19
- const config = await new ConfigBuilder()
20
- .setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
21
- .setIntegrations([reactPlugin()])
22
- .build();
23
-
24
- export default config;
20
+ export default defineConfig({ integrations: [reactPlugin()] });
25
21
  ```
26
22
 
27
23
  ## Component-Level Islands
28
24
 
29
- By default, Ecopages React acts in island mode:
25
+ For component-level islands, Ecopages React uses this contract:
30
26
 
31
27
  - SSR output preserves the authored DOM structure (no unnecessary wrapper elements).
32
- - A stable `data-eco-component-id` attribute is attached to the component SSR root.
33
- - The client bootstrap mounts the component via `createRoot()` strictly within that root boundary.
28
+ - 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`).
29
+ - During non-HMR runtime rendering, island and lazy-entry client modules are built together from the page client plan, in one grouped browser build during route preparation. Static production export contributes React hydration and lazy entries, every Integration's Page Browser Graph entries, and HTML Page and `html.html` shell module scripts to compatible app-wide browser build groups. Hydration scripts import the recorded output URLs. Same-integration Page, Layout, and includes are hydrated by the page bootstrap. The Html shell is not an island, even when its Integration differs from the page owner. Only a React component whose Integration differs from its parent's, on another owner's page, receives a per-component island script. SSR stamps the host and attaches those assets; it does not start a per-island build.
30
+ - Each island component gets its own hydration script, keyed by its component identity. A file that exports several island components is built once and its declared modules are merged, while each component's hosts hydrate the export whose identity matches.
31
+ - The island runtime keeps the SSR host and its children in place and hydrates that host with `hydrateRoot()`. The host uses `display: contents` so it does not introduce an extra layout box. Full-page hydration paths also use `hydrateRoot()`.
34
32
 
35
33
  > [!TIP]
36
34
  > **Full React SPA Routing:**
37
- > If you are building full React pages and want client-side navigation (SPA), use [@ecopages/react-router](../react-router/README.md) and pass it to the react plugin: `reactPlugin({ router: ecoRouter() })`.
35
+ > If you are building full React pages and want client-side navigation (SPA), use [@ecopages/react-router](../../react-router/README.md) and pass it to the react plugin: `reactPlugin({ router: ecoRouter() })`.
38
36
 
39
37
  ## MDX Support
40
38
 
41
- The React plugin includes built-in MDX support. When enabled, you can write `.mdx` pages alongside `.tsx` pages with unified client-side routing, hydration, and HMR.
39
+ The React plugin includes built-in MDX support. Add an `mdx` object to enable it; omit the property to disable MDX. You can write `.mdx` pages alongside `.tsx` pages with unified client-side routing, hydration, and HMR. Put `remarkPlugins`, `rehypePlugins`, and `recmaPlugins` next to `compilerOptions`, not inside it.
42
40
 
43
41
  ```ts
44
- import { ConfigBuilder } from '@ecopages/core/config-builder';
42
+ import { defineConfig } from '@ecopages/core/config';
45
43
  import { reactPlugin } from '@ecopages/react';
46
44
 
47
- const config = await new ConfigBuilder()
48
- .setIntegrations([
45
+ export default defineConfig({
46
+ integrations: [
49
47
  reactPlugin({
50
48
  mdx: {
51
- enabled: true,
52
- compilerOptions: {
53
- // Optional: remark/rehype plugins
54
- },
49
+ remarkPlugins: [],
50
+ rehypePlugins: [],
51
+ recmaPlugins: [],
55
52
  },
56
53
  }),
57
- ])
58
- .build();
59
-
60
- export default config;
54
+ ],
55
+ });
61
56
  ```
62
57
 
63
58
  ## Mixed Rendering
@@ -65,10 +60,20 @@ export default config;
65
60
  The React integration can participate in mixed-renderer apps in three ways:
66
61
 
67
62
  - React can own the page or view directly.
68
- - React can render nested component boundaries inside pages owned by another integration.
63
+ - React can render nested foreign subtrees inside pages owned by another integration.
69
64
  - React can render through non-React page, layout, or document shells when those shell components return strings.
70
65
 
71
- When a non-React render pass enters a React-owned boundary, Ecopages hands that boundary back to the React renderer. When React renders through a non-React shell, that shell must serialize to HTML so React can insert the result into the final response without escaping it.
66
+ When a non-React render pass reaches a React-owned foreign child, Ecopages hands that foreign subtree back to the React renderer. When React renders through a non-React shell, that shell must serialize to HTML so React can insert the result into the final response without escaping it.
67
+
68
+ Important:
69
+
70
+ - Components that may render foreign children must declare those children in `config.dependencies.components`.
71
+ - Ecopages validates mixed-renderer ownership from declared dependencies during render preparation. It does not infer every foreign subtree from rendered HTML alone.
72
+ - Route-level dependency resolvers can supply Components at request time; React includes those resolved roots when deciding whether a Foreign Subtree needs handoff.
73
+ - React still keeps its own child transport and hydration rules for React-owned subtrees.
74
+ - React renderers use the required core `AssetProcessingService` to process declared component and MDX config dependencies.
75
+
76
+ React uses the shared core route and document-shell pipeline. Its renderer hooks supply the browser-safe page payload, unified React layout composition, document contributions and router ownership attributes.
72
77
 
73
78
  ## Server and Client Graph Contract
74
79
 
@@ -80,6 +85,10 @@ The React integration supports Node.js modules and server-only code **only on th
80
85
 
81
86
  Keep server helpers close, but separate them physically or logically so they do not leak into the client bundle.
82
87
 
88
+ The `.server` naming rule comes from the browser-safe `@ecopages/core/build/contracts` entry. React applies it during import pruning before core's browser resolution guard runs. A Page that uses `.server.ts` imports only in server options such as `middleware` still builds: the imports and server options are removed before resolution.
89
+
90
+ For a hydratable Page that renders collection MDX, use `createCollectionComponentCache()` with the collection's `/browser` loader. Export `preload` from the Page so hydration, router navigation, and HMR load the current entry before synchronous render. The server may prime the same cache with `/server`'s `getComponent()` inside `staticProps`; `dependencies` remains server-only and is removed from the Page Browser Graph.
91
+
83
92
  ## Client Graph Boundary Architecture
84
93
 
85
94
  This section explains the internal contract used to keep the browser bundle minimal while preventing server-only code and request-only configuration from leaking into client output.
@@ -102,6 +111,16 @@ Think about each React page as two related graphs:
102
111
 
103
112
  The React integration builds the client graph conservatively. If a server-only module becomes reachable from the hydrated render path, the build should fail rather than silently shipping unsafe code.
104
113
 
114
+ The client-graph boundary analyzes project modules during each browser build and HMR rebuild; transform results and requested-export changes are not cached or replayed across builds. In grouped island builds, each entry file uses its own declared modules, while helper modules use the group's merged declarations because the build has one module instance for each helper. Set `ECO_AST_PROFILE=1` to emit one structured timing record per client-graph analysis while investigating a development rebuild.
115
+
116
+ ### `explicitGraph` option
117
+
118
+ `reactPlugin({ explicitGraph: true })` forces the page browser graph (hydration assets) to emit for every React page, even when the page does not declare `dependencies.modules` and no router is configured.
119
+
120
+ It does **not** disable the client-graph AST boundary. Server-only `eco.page(...)` options such as `middleware` and `requires` are still stripped from browser bundles. With a router adapter, page hydration is already always on, so the option is redundant for SPA apps.
121
+
122
+ The option name is historical — it forces hydration asset emission, it does not mean “skip graph transforms.”
123
+
105
124
  ### What Stays and What Goes
106
125
 
107
126
  The client bundle keeps:
@@ -109,7 +128,7 @@ The client bundle keeps:
109
128
  - The page component render path.
110
129
  - Client-safe component dependencies reachable from render.
111
130
  - Layout wiring needed for hydration.
112
- - Router runtime state needed by [@ecopages/react-router](../react-router/README.md) when SPA mode is enabled.
131
+ - Router runtime state needed by [@ecopages/react-router](../../react-router/README.md) when SPA mode is enabled.
113
132
 
114
133
  The client bundle removes or excludes:
115
134
 
@@ -124,7 +143,7 @@ Important:
124
143
 
125
144
  ### AST Pipeline Order
126
145
 
127
- The browser-bound transform in [packages/integrations/react/src/utils/client-graph-boundary-plugin.ts](packages/integrations/react/src/utils/client-graph-boundary-plugin.ts) follows this order:
146
+ The browser-bound transform in [src/client-graph/boundary-plugin.ts](src/client-graph/boundary-plugin.ts) follows this order:
128
147
 
129
148
  1. Parse the module and build a reachability view of the client render graph.
130
149
  2. Remove imports that are not allowed or not reachable from the client graph.
@@ -159,7 +178,7 @@ The fix is to strip server-only `eco.page(...)` options after import pruning, wh
159
178
 
160
179
  The browser must not receive arbitrary request-scoped data.
161
180
 
162
- The React renderer in [packages/integrations/react/src/react-renderer.ts](packages/integrations/react/src/react-renderer.ts) serializes only the top-level `locals` keys explicitly declared by `Page.requires`. If a page does not declare `requires`, no `locals` are serialized for hydration.
181
+ The React renderer in [src/render/react-renderer.ts](src/render/react-renderer.ts) serializes only the top-level `locals` keys explicitly declared by `Page.requires`. If a page does not declare `requires`, no `locals` are serialized for hydration.
163
182
 
164
183
  Example:
165
184
 
@@ -184,8 +203,8 @@ Hydration must rebuild the same tree the server rendered.
184
203
 
185
204
  That applies to both:
186
205
 
187
- - non-router hydration scripts in [packages/integrations/react/src/utils/hydration-scripts.ts](packages/integrations/react/src/utils/hydration-scripts.ts)
188
- - router-backed hydration in [packages/react-router/src/router.ts](packages/react-router/src/router.ts)
206
+ - page hydration lifecycle in [src/hydration/browser/page-hydration.ts](src/hydration/browser/page-hydration.ts)
207
+ - router-backed hydration in [../../react-router/src/router.ts](../../react-router/src/router.ts)
189
208
 
190
209
  If the page render receives `locals` on the server and the layout also depends on those values, the client must pass the same serialized `locals` into the layout during hydration. Otherwise React will detect a mismatch.
191
210
 
@@ -193,9 +212,134 @@ If the page render receives `locals` on the server and the layout also depends o
193
212
 
194
213
  The main regression coverage lives in:
195
214
 
196
- - [packages/integrations/react/src/utils/client-graph-boundary-plugin.test.ts](packages/integrations/react/src/utils/client-graph-boundary-plugin.test.ts): verifies server-only `eco.page(...)` options are stripped from browser bundles.
197
- - [packages/integrations/react/src/react-renderer.locals.test.ts](packages/integrations/react/src/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
198
- - [packages/integrations/react/src/utils/hydration-scripts.test.ts](packages/integrations/react/src/utils/hydration-scripts.test.ts): verifies non-router hydration passes serialized `locals` into layouts.
199
- - [packages/react-router/test/hmr-reload.test.browser.ts](packages/react-router/test/hmr-reload.test.browser.ts): verifies router-backed layout hydration receives `locals` with `persistLayouts` both enabled and disabled.
215
+ - [src/client-graph/boundary-plugin.test.ts](src/client-graph/boundary-plugin.test.ts): verifies server-only `eco.page(...)` options are stripped from browser bundles.
216
+ - [src/render/react-renderer.locals.test.ts](src/render/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
217
+ - [src/hydration/hydration-script-compiler.test.ts](src/hydration/hydration-script-compiler.test.ts): verifies editable browser sources compile to readable and minified entries.
218
+ - [../../react-router/test/layout-persistence.test.browser.ts](../../react-router/test/layout-persistence.test.browser.ts): verifies router-backed layout hydration receives `locals` with `persistLayouts` both enabled and disabled.
200
219
 
201
220
  If you change the AST transform or hydration flow, update the corresponding tests in the same change.
221
+
222
+ ### Nested layouts and unified SSR
223
+
224
+ Pages may declare `layout` as a single component or an **outer → inner** array on `eco.page()`. On the server, React-managed layout stacks compose through `composeDocumentShell` + `composeLayoutPageTree` so provider context reaches nested pages during SSR. On the client, `@ecopages/react-router` `PageContent` uses the same `composeLayoutPageTree` helper unless `persistLayouts` is enabled (then each tier is cached independently).
225
+
226
+ During SSR, `ReactRenderer` passes the app-resolved React runtime into `composeLayoutPageTree` via `options.react` so layout trees are built with the same module instance as `renderToString`. App code should import hooks and context from `react` normally; keep a single React version in the app dependency graph (avoid duplicate `react` copies in monorepos).
227
+
228
+ Layout prop factories receive `LayoutPropsContext` (`params`, `query`, `locals`). Route-scoped `locals` are passed to layout tiers via document-shell props during SSR; serialized `pageProps.locals` follow `Page.requires` and are intended for the page component.
229
+
230
+ - [src/render/layout-compose.ts](src/render/layout-compose.ts): shared client/SSR tree builder.
231
+ - [src/test/react-ssr-hydration-parity.test.tsx](src/test/react-ssr-hydration-parity.test.tsx): nested tier order parity between SSR and `composeLayoutPageTree`.
232
+ - [src/test/react-ssr-unified.test.tsx](src/test/react-ssr-unified.test.tsx): provider context through nested SSR layouts.
233
+
234
+ ### Shared runtime vendors (SPA + persisted layouts)
235
+
236
+ With `ecoRouter()`, Ecopages keeps outer layout tiers mounted across client navigation (`persistLayouts` defaults to `true`). Each Page chunk still loads separately, while its Layout tiers can stay alive in the DOM.
237
+
238
+ A package imported by both a persisted Layout and multiple Page chunks must resolve to one browser module instance. Otherwise, a library with module-level state such as React context can be duplicated, and navigation can fail with errors such as `No QueryClient set`.
239
+
240
+ Register shared packages explicitly with `reactPlugin({ runtimeModules })`. Each listed package is built once into `/assets/vendors/*.js`, and browser graphs import that vendor URL. React, React DOM, and the configured router are already shared. Layout files do not add packages to `runtimeModules` automatically.
241
+
242
+ 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`.
243
+
244
+ #### Register shared packages
245
+
246
+ List the package specifier that Page or Layout code imports:
247
+
248
+ ```ts
249
+ import { defineConfig } from '@ecopages/core/config';
250
+ import { reactPlugin } from '@ecopages/react';
251
+ import { ecoRouter } from '@ecopages/react-router';
252
+
253
+ export default defineConfig({
254
+ integrations: [
255
+ reactPlugin({
256
+ router: ecoRouter(),
257
+ runtimeModules: ['@tanstack/react-query'],
258
+ }),
259
+ ],
260
+ });
261
+ ```
262
+
263
+ Use the package root when all imports use that root. Import rewrites match exact specifiers, so add a separate entry for each package subpath used by app code.
264
+
265
+ **Migration from layout discovery:** remove `runtimeProvider` from layout options. Add each shared package the scanner previously supplied to `runtimeModules` using the exact specifier imported by app code.
266
+
267
+ `runtimeModules` also accepts objects with a custom vendor output name:
268
+
269
+ ```ts
270
+ reactPlugin({
271
+ router: ecoRouter(),
272
+ runtimeModules: ['@tanstack/react-query', { specifier: '@acme/ui', outputName: 'acme-ui' }],
273
+ });
274
+ ```
275
+
276
+ Each vendor entry is built from the package's browser ESM surface: Ecopages follows an `exports` import target when present and otherwise prefers a package's legacy `module` field over CJS `main`. ESM files are re-exported with `export *`. CJS files (including React's published `index.js` / `jsx-runtime`) emit explicit named exports from that same file so the vendor can provide `jsx`.
277
+
278
+ Each vendor bundles its package dependencies. Imports whose exact specifiers are registered in `runtimeModules` are rewritten to the corresponding shared vendor URL; React and the configured router are shared automatically.
279
+
280
+ #### Singleton packages (MobX, Redux, Query client, audio engines)
281
+
282
+ React context, MobX observables, Redux stores, TanStack Query clients, and audio runtimes (for example Tone.js) depend on one module instance. Register a singleton package in `runtimeModules` when Page and Layout code must share its state.
283
+
284
+ **Library packaging:** ship singleton dependencies as `peerDependencies` and keep them external in the library build so `dist/` retains `import … from "mobx"` (or equivalent) instead of inlining a private copy.
285
+
286
+ **Ecopages app config:** register each singleton and library package as its own `runtimeModules` entry. Imports between those vendors are rewritten to the shared vendor URLs when their specifiers match:
287
+
288
+ ```ts
289
+ reactPlugin({
290
+ router: ecoRouter(),
291
+ runtimeModules: [
292
+ { specifier: 'mobx', outputName: 'mobx' },
293
+ { specifier: 'mobx-react-lite', outputName: 'mobx-react-lite' },
294
+ { specifier: '@acme/store-ui', outputName: 'acme-store-ui' },
295
+ ],
296
+ });
297
+ ```
298
+
299
+ Registering only the library vendor or only the singleton is not enough when the published library still inlines the singleton. Peer the dependency in the library, externalize it in the library build, and register both the library and singleton specifiers in `runtimeModules`. Existing `externals` fields on runtime module entries should be removed; register each non-framework shared dependency as its own entry. React, React DOM, and the configured router are shared automatically. Rebuild vendors (and clear `.eco` / `dist/assets/vendors` in dev) after changing package entry points or `runtimeModules`.
300
+
301
+ #### Troubleshooting
302
+
303
+ | Symptom | Likely cause | Fix |
304
+ | --------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
305
+ | `No QueryClient set` after SPA navigation | Query client package is not shared by the Page and Layout graphs | Add `@tanstack/react-query` to `runtimeModules` and rebuild vendors |
306
+ | Duplicate React context / Tone init logs | Provider package is bundled through multiple client entrypoints | Import through the package root and register that root in `runtimeModules` |
307
+ | Store updates / `reaction` / `observer` no-op | Duplicate singleton (for example MobX) — a library inlines one copy and app code loads another | Peer the singleton in the library; register the library and singleton specifiers in `runtimeModules`; rebuild vendors |
308
+ | `@/` alias not followed | Missing or invalid tsconfig paths | Add `compilerOptions.paths`; ensure `include` globs are valid JSON (not broken by comment stripping) |
309
+ | Stale bootstrap script hash in dev | Rendered HTML cached before runtime vendors/bootstrap scripts changed | Rebuild or touch a route file; development HTML cache keys include browser-runtime generation |
310
+ | `MISSING_EXPORT` for names like `BasePlugin` | Vendor listed CJS enumerable keys that the ESM file does not export | Register the package root only; rebuild vendors. Subpath plugins are separate module contracts and must be bundled or declared themselves |
311
+ | `does not provide an export named 'jsx'` | Stale React vendor generated with `export *` from CJS `jsx-runtime` | Clear `.eco` / `dist/assets/vendors` and rebuild so the CJS entry lists `jsx` / `jsxs` explicitly |
312
+ | `Calling require for "/assets/vendors/…"` | A CJS vendor graph `require()`d another runtime module after URL rewrite | Prefer packages with an ESM/`module` entry; register sibling singletons as separate `runtimeModules` entries |
313
+
314
+ Use the dev toolbar **Deps** panel to inspect vendor URLs loaded by the active Page. See [Dev Toolbar](/docs/core/dev-toolbar).
315
+
316
+ #### Tests
317
+
318
+ - `src/bundling/runtime-modules.test.ts`: explicit entries, exact package specifiers, and vendor filename normalization.
319
+ - `src/bundling/runtime-bundle.test.ts`: vendor registration and manifest paths.
320
+ - `../../core/src/assets/asset-processing-service/browser-runtime-entry-resolution.test.ts`: ESM entry resolution and default-export policy for React vs TanStack Query.
321
+ - `../../../e2e/fixtures/react-router/persist-layouts.test.e2e.ts`: one QueryClient shared across Page navigation with an explicit `runtimeModules` entry.
322
+
323
+ ### Client-only code in SSR trees
324
+
325
+ Pages and layouts SSR through `renderToString`, which does not support `<Suspense>`. Do not use `React.lazy()` + `<Suspense>` in `eco.page()` or `eco.layout()` trees.
326
+
327
+ Wrap browser-only UI in `ClientOnly`:
328
+
329
+ ```tsx
330
+ import { eco } from '@ecopages/core';
331
+ import { ClientOnly } from '@ecopages/react/utils/client-only';
332
+
333
+ export const RootLayout = eco.layout({
334
+ render: ({ children }) => (
335
+ <>
336
+ {children}
337
+ <ClientOnly fallback={null}>
338
+ <DevtoolsPanel />
339
+ </ClientOnly>
340
+ </>
341
+ ),
342
+ });
343
+ ```
344
+
345
+ For code-split client-only modules, `import()` inside `useEffect` within `ClientOnly` — not `lazy()`. `dynamic({ ssr: false })` must also stay inside `ClientOnly`; it renders `null` on the server and `lazy()` in the browser.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecopages/react",
3
- "version": "0.2.1",
3
+ "version": "0.3.1",
4
4
  "description": "React integration for Ecopages",
5
5
  "keywords": [
6
6
  "ecopages",
@@ -8,69 +8,114 @@
8
8
  "plugin"
9
9
  ],
10
10
  "license": "MIT",
11
- "main": "./src/react.plugin.js",
12
- "types": "./src/react.plugin.d.ts",
11
+ "main": "./src/plugin/react.plugin.js",
12
+ "types": "./src/plugin/react.plugin.d.ts",
13
13
  "type": "module",
14
+ "publishConfig": {
15
+ "access": "public"
16
+ },
14
17
  "exports": {
15
18
  ".": {
16
- "default": "./src/react.plugin.js",
17
- "types": "./src/react.plugin.d.ts"
19
+ "default": "./src/plugin/react.plugin.js",
20
+ "types": "./src/plugin/react.plugin.d.ts"
21
+ },
22
+ "./eco-embed": {
23
+ "default": "./src/render/eco-embed.js",
24
+ "types": "./src/render/eco-embed.d.ts"
18
25
  },
19
26
  "./declarations": {
20
- "types": "./src/declarations.d.ts"
27
+ "types": "./src/contracts/declarations.d.ts"
21
28
  },
22
29
  "./utils/dynamic": {
23
- "types": "./src/utils/dynamic.d.ts",
24
- "default": "./src/utils/dynamic.js"
30
+ "types": "./src/app/dynamic.d.ts",
31
+ "default": "./src/app/dynamic.js"
25
32
  },
26
33
  "./utils/client-only": {
27
- "types": "./src/utils/client-only.d.ts",
28
- "default": "./src/utils/client-only.js"
34
+ "types": "./src/app/client-only.d.ts",
35
+ "default": "./src/app/client-only.js"
36
+ },
37
+ "./runtime/use-sync-external-store-with-selector": {
38
+ "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
39
+ "default": "./src/runtime/use-sync-external-store-with-selector.js"
29
40
  },
30
41
  "./router-adapter": {
31
- "types": "./src/router-adapter.d.ts",
32
- "default": "./src/router-adapter.js"
42
+ "types": "./src/contracts/router-adapter.d.ts",
43
+ "default": "./src/contracts/router-adapter.js"
44
+ },
45
+ "./layout-compose": {
46
+ "types": "./src/render/layout-compose.d.ts",
47
+ "default": "./src/render/layout-compose.js"
48
+ },
49
+ "./collection-component-cache": {
50
+ "types": "./src/content/collection-component-cache.d.ts",
51
+ "default": "./src/content/collection-component-cache.js"
52
+ },
53
+ "./serialize-page-data-script": {
54
+ "types": "./src/hydration/serialize-page-data-script.d.ts",
55
+ "default": "./src/hydration/serialize-page-data-script.js"
56
+ },
57
+ "./page-data-reader": {
58
+ "types": "./src/hydration/page-data-reader.d.ts",
59
+ "default": "./src/hydration/page-data-reader.js"
60
+ },
61
+ "./eco-embed.ts": {
62
+ "default": "./src/render/eco-embed.js",
63
+ "types": "./src/render/eco-embed.d.ts"
33
64
  },
34
65
  "./declarations.ts": {
35
- "types": "./src/declarations.d.ts"
66
+ "types": "./src/contracts/declarations.d.ts"
36
67
  },
37
68
  "./utils/dynamic.ts": {
38
- "types": "./src/utils/dynamic.d.ts",
39
- "default": "./src/utils/dynamic.js"
69
+ "types": "./src/app/dynamic.d.ts",
70
+ "default": "./src/app/dynamic.js"
40
71
  },
41
72
  "./utils/client-only.ts": {
42
- "types": "./src/utils/client-only.d.ts",
43
- "default": "./src/utils/client-only.js"
73
+ "types": "./src/app/client-only.d.ts",
74
+ "default": "./src/app/client-only.js"
75
+ },
76
+ "./runtime/use-sync-external-store-with-selector.ts": {
77
+ "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
78
+ "default": "./src/runtime/use-sync-external-store-with-selector.js"
44
79
  },
45
80
  "./router-adapter.ts": {
46
- "types": "./src/router-adapter.d.ts",
47
- "default": "./src/router-adapter.js"
81
+ "types": "./src/contracts/router-adapter.d.ts",
82
+ "default": "./src/contracts/router-adapter.js"
83
+ },
84
+ "./layout-compose.ts": {
85
+ "types": "./src/render/layout-compose.d.ts",
86
+ "default": "./src/render/layout-compose.js"
87
+ },
88
+ "./collection-component-cache.ts": {
89
+ "types": "./src/content/collection-component-cache.d.ts",
90
+ "default": "./src/content/collection-component-cache.js"
91
+ },
92
+ "./serialize-page-data-script.ts": {
93
+ "types": "./src/hydration/serialize-page-data-script.d.ts",
94
+ "default": "./src/hydration/serialize-page-data-script.js"
95
+ },
96
+ "./page-data-reader.ts": {
97
+ "types": "./src/hydration/page-data-reader.d.ts",
98
+ "default": "./src/hydration/page-data-reader.js"
48
99
  }
49
100
  },
50
101
  "repository": {
51
102
  "type": "git",
52
- "url": "https://github.com/ecopages/ecopages.git",
103
+ "url": "git+https://github.com/ecopages/ecopages.git",
53
104
  "directory": "packages/integrations/react"
54
105
  },
55
106
  "peerDependencies": {
56
- "@ecopages/core": "0.2.1",
107
+ "@ecopages/core": "0.3.1",
57
108
  "@types/react": "^19",
58
109
  "@types/react-dom": "^19",
59
110
  "react": "^19",
60
111
  "react-dom": "^19"
61
112
  },
62
113
  "dependencies": {
63
- "@ecopages/file-system": "0.2.1",
114
+ "@ecopages/file-system": "0.3.1",
64
115
  "@ecopages/logger": "^0.2.3",
65
- "@mdx-js/esbuild": "^3.0.1",
66
- "@mdx-js/mdx": "^3.1.0",
67
- "oxc-parser": "^0.124.0",
68
- "oxc-transform": "^0.124.0",
69
- "source-map": "^0.7.6",
70
- "vfile": "^6.0.3"
71
- },
72
- "overrides": {
73
- "react": "^19",
74
- "react-dom": "^19"
116
+ "@ecopages/mdx": "0.3.1",
117
+ "@mdx-js/mdx": "^3.1.1",
118
+ "oxc-parser": "^0.141.0",
119
+ "rolldown": "^1.1.0"
75
120
  }
76
- }
121
+ }
@@ -0,0 +1,10 @@
1
+ import { useSyncExternalStore } from 'react';
2
+ const emptySubscribe = () => () => { };
3
+ export const useIsClient = () => useSyncExternalStore(emptySubscribe, () => true, () => false);
4
+ export const ClientOnly = ({ children, fallback = null }) => {
5
+ const isClient = useIsClient();
6
+ if (!isClient) {
7
+ return fallback;
8
+ }
9
+ return children;
10
+ };
@@ -0,0 +1,9 @@
1
+ import { lazy } from 'react';
2
+ const NullComponent = () => null;
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
+ }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Bare package specifiers for React page hydration bootstrap helpers.
3
+ */
4
+ export declare const PAGE_LAYOUT_NORMALIZATION_PACKAGE = "@ecopages/core/client";
5
+ export declare const LAYOUT_COMPOSE_PACKAGE = "@ecopages/react/layout-compose";
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Bare package specifiers for React page hydration bootstrap helpers.
3
+ */
4
+ export const PAGE_LAYOUT_NORMALIZATION_PACKAGE = '@ecopages/core/client';
5
+ export const LAYOUT_COMPOSE_PACKAGE = '@ecopages/react/layout-compose';
@@ -0,0 +1,78 @@
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 type { EcoBuildPlugin, IntegrationRuntimeContext } from '@ecopages/core/integration';
10
+ import type { AssetProcessingIntegration, AssetProcessingService } from '@ecopages/core/integration';
11
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
12
+ import { type ReactRuntimeImports } from './runtime-bundle.js';
13
+ import type { ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
14
+ /**
15
+ * Configuration for the BundleService.
16
+ */
17
+ export interface BundleServiceConfig {
18
+ rootDir: string;
19
+ appConfig: IntegrationRuntimeContext['appConfig'];
20
+ assetProcessingIntegration?: AssetProcessingIntegration;
21
+ hostIntegrationName: string;
22
+ routerAdapter?: ReactRouterAdapter;
23
+ runtimeModules?: ResolvedReactPluginRuntimeModule[];
24
+ getMdxLoaderPlugin?: () => EcoBuildPlugin;
25
+ }
26
+ /**
27
+ * Optional flags that adjust how a React client entry is bundled.
28
+ */
29
+ export interface ReactClientBundleOptions {
30
+ /**
31
+ * When `true`, bundle React runtime dependencies into the emitted entry instead of
32
+ * rewriting them to external runtime specifiers.
33
+ */
34
+ includeRuntime?: boolean;
35
+ /**
36
+ * When set, overrides the build adapter chunk splitting mode for this entry.
37
+ */
38
+ splitting?: boolean;
39
+ }
40
+ /**
41
+ * Manages bundle configuration and plugin creation for React page/component builds.
42
+ */
43
+ export declare class BundleService {
44
+ private readonly runtimeBundleService;
45
+ private readonly config;
46
+ private readonly foreignJsxOverridePlugin;
47
+ private readonly runtimeRewritePlugin;
48
+ private pageLayoutNormalizationVendorPromise;
49
+ private mdxLoaderPlugin;
50
+ constructor(config: BundleServiceConfig);
51
+ /**
52
+ * Returns resolved runtime import paths for the React runtime.
53
+ */
54
+ getRuntimeImports(): ReactRuntimeImports;
55
+ /**
56
+ * Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
57
+ *
58
+ * @remarks
59
+ * Concurrent callers share the same in-flight promise. Asset processing itself caches
60
+ * by dependency key, so repeats after success remain cheap.
61
+ */
62
+ ensurePageLayoutNormalizationVendorProcessed(assetProcessingService: Pick<AssetProcessingService, 'processDependencies'>): Promise<void>;
63
+ /**
64
+ * Creates bundle options for a page or component entry.
65
+ *
66
+ * @remarks
67
+ * React derives runtime specifier mappings from the core browser runtime manifest
68
+ * so ESM imports resolve to concrete runtime asset URLs during module loading.
69
+ *
70
+ * @param componentName - Generated unique component name for output naming
71
+ * @param isMdx - Whether the source file is an MDX file
72
+ * @param declaredModules - Explicitly declared browser module specifiers
73
+ * @returns Bundle options object for the build adapter
74
+ */
75
+ createBundleOptions(componentName: string, isMdx: boolean, declaredModules: string[], bundleOptions?: ReactClientBundleOptions, entrypointFile?: string, groupedEntrypointFiles?: readonly string[], groupedDeclaredModules?: readonly string[]): Promise<Record<string, unknown>>;
76
+ private createClientBuildPlugins;
77
+ private getMdxLoaderPlugin;
78
+ }