@ecopages/react 0.2.0-beta.3 → 0.2.0-beta.31
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.
- package/README.md +168 -6
- package/package.json +51 -26
- package/src/bundling/bootstrap-package-paths.d.ts +5 -0
- package/src/bundling/bootstrap-package-paths.js +6 -0
- package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +21 -8
- package/src/{services/react-bundle.service.js → bundling/bundle.js} +53 -21
- package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
- package/src/bundling/discover-layout-runtime-modules.js +180 -0
- package/src/bundling/runtime-alias-map.d.ts +10 -0
- package/src/{utils/react-runtime-alias-map.js → bundling/runtime-alias-map.js} +13 -2
- package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +30 -5
- package/src/{services/react-runtime-bundle.service.js → bundling/runtime-bundle.js} +104 -8
- package/src/bundling/runtime-mode.d.ts +9 -0
- package/src/bundling/runtime-mode.js +6 -0
- package/src/bundling/runtime-modules.d.ts +29 -0
- package/src/bundling/runtime-modules.js +38 -0
- package/src/client-graph/ast-transform.d.ts +18 -0
- package/src/{utils/client-graph-boundary-plugin.js → client-graph/ast-transform.js} +15 -232
- package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +0 -5
- package/src/{utils/client-graph-boundary-cache.js → client-graph/boundary-cache.js} +1 -3
- package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
- package/src/client-graph/boundary-plugin.js +107 -0
- package/src/{utils → client-graph}/component-config-traversal.js +4 -2
- package/src/{utils → client-graph}/reachability-analyzer.d.ts +2 -2
- package/src/{utils → client-graph}/reachability-analyzer.js +4 -1
- package/src/client-graph/specifier-classification.d.ts +75 -0
- package/src/client-graph/specifier-classification.js +155 -0
- package/src/{react-hmr-strategy.d.ts → hmr/hmr-strategy.d.ts} +19 -6
- package/src/{react-hmr-strategy.js → hmr/hmr-strategy.js} +154 -133
- package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
- package/src/{services/react-hmr-page-metadata-cache.js → hmr/page-metadata-cache.js} +8 -2
- package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
- package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
- package/src/hydration/bootstrap-imports.d.ts +25 -0
- package/src/hydration/bootstrap-imports.js +23 -0
- package/src/{services/react-hydration-asset.service.d.ts → hydration/hydration-asset.d.ts} +33 -33
- package/src/{services/react-hydration-asset.service.js → hydration/hydration-asset.js} +63 -56
- package/src/hydration/hydration-scripts.d.ts +100 -0
- package/src/hydration/hydration-scripts.js +350 -0
- package/src/{utils → hydration}/hydration-scripts.test.browser.js +11 -5
- package/src/hydration/page-data-manifest.d.ts +58 -0
- package/src/hydration/page-data-manifest.js +53 -0
- package/src/hydration/page-data-reader.d.ts +31 -0
- package/src/hydration/page-data-reader.js +64 -0
- package/src/hydration/page-payload.d.ts +67 -0
- package/src/hydration/page-payload.js +104 -0
- package/src/hydration/serialize-page-data-script.d.ts +27 -0
- package/src/hydration/serialize-page-data-script.js +31 -0
- package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +5 -5
- package/src/{services/react-mdx-config-dependency.service.js → mdx/mdx-config-dependency.js} +8 -10
- package/src/mdx/mdx-loader-plugin.d.ts +2 -0
- package/src/mdx/mdx-loader-plugin.js +11 -0
- package/src/page/page-module.d.ts +46 -0
- package/src/page/page-module.js +72 -0
- package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +8 -3
- package/src/{react.plugin.js → plugin/react.plugin.js} +78 -54
- package/src/plugin/react.types.d.ts +149 -0
- package/src/render/component-ownership.d.ts +50 -0
- package/src/render/component-ownership.js +23 -0
- package/src/render/component-ssr.d.ts +113 -0
- package/src/render/component-ssr.js +202 -0
- package/src/render/errors.d.ts +16 -0
- package/src/render/errors.js +18 -0
- package/src/render/layout-compose.d.ts +66 -0
- package/src/render/layout-compose.js +106 -0
- package/src/render/react-renderer.d.ts +138 -0
- package/src/render/react-renderer.js +481 -0
- package/src/render/react-runtime.d.ts +13 -0
- package/src/render/react-runtime.js +21 -0
- package/src/render/unified-layout-composition.d.ts +53 -0
- package/src/render/unified-layout-composition.js +89 -0
- package/src/react-renderer.d.ts +0 -233
- package/src/react-renderer.js +0 -622
- package/src/react.types.d.ts +0 -88
- package/src/services/pages-index.d.ts +0 -64
- package/src/services/pages-index.js +0 -73
- package/src/services/react-page-module.service.d.ts +0 -88
- package/src/services/react-page-module.service.js +0 -166
- package/src/services/react-page-payload.service.d.ts +0 -46
- package/src/services/react-page-payload.service.js +0 -67
- package/src/utils/hydration-scripts.d.ts +0 -92
- package/src/utils/hydration-scripts.js +0 -358
- package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
- package/src/utils/react-mdx-loader-plugin.js +0 -45
- package/src/utils/react-runtime-alias-map.d.ts +0 -8
- /package/src/{utils → app}/client-only.d.ts +0 -0
- /package/src/{utils → app}/client-only.js +0 -0
- /package/src/{utils → app}/dynamic.d.ts +0 -0
- /package/src/{utils → app}/dynamic.js +0 -0
- /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
- /package/src/{utils → app}/dynamic.test.browser.js +0 -0
- /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
- /package/src/{utils/react-dom-runtime-interop-plugin.js → bundling/runtime-interop-plugin.js} +0 -0
- /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
- /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
- /package/src/{utils → client-graph}/declared-modules.js +0 -0
- /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
- /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
- /package/src/{router-adapter.js → contracts/router-adapter.js} +0 -0
- /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
- /package/src/{utils → hmr}/hmr-scripts.js +0 -0
- /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
- /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
- /package/src/{react.constants.js → plugin/react.constants.js} +0 -0
- /package/src/{react.types.js → plugin/react.types.js} +0 -0
- /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
- /package/src/{eco-embed.js → render/eco-embed.js} +0 -0
- /package/src/{utils → render}/html-boundary.d.ts +0 -0
- /package/src/{utils → render}/html-boundary.js +0 -0
package/README.md
CHANGED
|
@@ -109,6 +109,14 @@ Think about each React page as two related graphs:
|
|
|
109
109
|
|
|
110
110
|
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.
|
|
111
111
|
|
|
112
|
+
### `explicitGraph` option
|
|
113
|
+
|
|
114
|
+
`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.
|
|
115
|
+
|
|
116
|
+
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.
|
|
117
|
+
|
|
118
|
+
The option name is historical — it forces hydration asset emission, it does not mean “skip graph transforms.”
|
|
119
|
+
|
|
112
120
|
### What Stays and What Goes
|
|
113
121
|
|
|
114
122
|
The client bundle keeps:
|
|
@@ -131,7 +139,7 @@ Important:
|
|
|
131
139
|
|
|
132
140
|
### AST Pipeline Order
|
|
133
141
|
|
|
134
|
-
The browser-bound transform in [src/
|
|
142
|
+
The browser-bound transform in [src/client-graph/boundary-plugin.ts](src/client-graph/boundary-plugin.ts) follows this order:
|
|
135
143
|
|
|
136
144
|
1. Parse the module and build a reachability view of the client render graph.
|
|
137
145
|
2. Remove imports that are not allowed or not reachable from the client graph.
|
|
@@ -166,7 +174,7 @@ The fix is to strip server-only `eco.page(...)` options after import pruning, wh
|
|
|
166
174
|
|
|
167
175
|
The browser must not receive arbitrary request-scoped data.
|
|
168
176
|
|
|
169
|
-
The React renderer in [src/react-renderer.ts](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.
|
|
177
|
+
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.
|
|
170
178
|
|
|
171
179
|
Example:
|
|
172
180
|
|
|
@@ -191,7 +199,7 @@ Hydration must rebuild the same tree the server rendered.
|
|
|
191
199
|
|
|
192
200
|
That applies to both:
|
|
193
201
|
|
|
194
|
-
- non-router hydration scripts in [src/
|
|
202
|
+
- non-router hydration scripts in [src/hydration/hydration-scripts.ts](src/hydration/hydration-scripts.ts)
|
|
195
203
|
- router-backed hydration in [../../react-router/src/router.ts](../../react-router/src/router.ts)
|
|
196
204
|
|
|
197
205
|
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.
|
|
@@ -200,9 +208,163 @@ If the page render receives `locals` on the server and the layout also depends o
|
|
|
200
208
|
|
|
201
209
|
The main regression coverage lives in:
|
|
202
210
|
|
|
203
|
-
- [src/
|
|
204
|
-
- [src/react-renderer.locals.test.ts](src/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
|
|
205
|
-
- [src/
|
|
211
|
+
- [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.
|
|
212
|
+
- [src/render/react-renderer.locals.test.ts](src/render/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
|
|
213
|
+
- [src/hydration/hydration-scripts.test.ts](src/hydration/hydration-scripts.test.ts): verifies non-router hydration passes serialized `locals` into layouts.
|
|
206
214
|
- [../../react-router/test/hmr-reload.test.browser.ts](../../react-router/test/hmr-reload.test.browser.ts): verifies router-backed layout hydration receives `locals` with `persistLayouts` both enabled and disabled.
|
|
207
215
|
|
|
208
216
|
If you change the AST transform or hydration flow, update the corresponding tests in the same change.
|
|
217
|
+
|
|
218
|
+
### Nested layouts and unified SSR
|
|
219
|
+
|
|
220
|
+
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).
|
|
221
|
+
|
|
222
|
+
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).
|
|
223
|
+
|
|
224
|
+
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.
|
|
225
|
+
|
|
226
|
+
- [src/render/layout-compose.ts](src/render/layout-compose.ts): shared client/SSR tree builder.
|
|
227
|
+
- [src/test/react-ssr-hydration-parity.test.tsx](src/test/react-ssr-hydration-parity.test.tsx): nested tier order parity between SSR and `composeLayoutPageTree`.
|
|
228
|
+
- [src/test/react-ssr-unified.test.tsx](src/test/react-ssr-unified.test.tsx): provider context through nested SSR layouts.
|
|
229
|
+
|
|
230
|
+
### Shared runtime vendors (SPA + persisted layouts)
|
|
231
|
+
|
|
232
|
+
#### Mental model
|
|
233
|
+
|
|
234
|
+
With `ecoRouter()`, Ecopages keeps outer layout tiers mounted across client navigation (`persistLayouts` defaults to `true`). Each page chunk still loads separately, but provider layouts stay alive in the DOM.
|
|
235
|
+
|
|
236
|
+
That creates a module identity problem: if TanStack Query (or any shared provider library) is bundled into every page chunk separately, each chunk gets its own copy of the library and its own React context. Navigation then breaks with errors such as `No QueryClient set`, even though the provider component is still mounted.
|
|
237
|
+
|
|
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
|
+
|
|
240
|
+
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
|
+
|
|
242
|
+
#### When auto-discovery runs
|
|
243
|
+
|
|
244
|
+
Auto-discovery runs at plugin setup when **both** are true:
|
|
245
|
+
|
|
246
|
+
- `router` is passed to `reactPlugin()`
|
|
247
|
+
- The app config exposes `absolutePaths.projectDir`, `layoutsDir`, and `componentsDir`
|
|
248
|
+
|
|
249
|
+
Without `router`, only explicit `runtimeModules` entries are vendored.
|
|
250
|
+
|
|
251
|
+
#### Discovery modes
|
|
252
|
+
|
|
253
|
+
| Mode | Trigger | Layout roots scanned | npm packages collected |
|
|
254
|
+
| ---------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- |
|
|
255
|
+
| **Runtime-provider** (recommended) | At least one layout sets `runtimeProvider: true` | Only flagged layouts | Every reachable npm package in that layout's `render` graph |
|
|
256
|
+
| **Provider-scoped fallback** | No layout sets `runtimeProvider: true` | All `eco.layout(` files under `layouts/` and `components/` | npm packages imported from provider/context modules only |
|
|
257
|
+
|
|
258
|
+
The fallback exists for backward compatibility. Ecopages logs a debug message when fallback mode is active. Prefer explicit `runtimeProvider: true` on provider root layouts (for example a query-client tier) and omit it from shell-only layouts.
|
|
259
|
+
|
|
260
|
+
#### What gets discovered
|
|
261
|
+
|
|
262
|
+
1. Select layout entry files using the mode above.
|
|
263
|
+
2. From each root layout's **`render` client graph** (reachability analysis), follow relative imports and tsconfig path aliases. Type-only imports and `.server.ts` modules are skipped.
|
|
264
|
+
3. Collect npm package roots (for example `@tanstack/react-query`, not `@tanstack/react-query/devtools`).
|
|
265
|
+
4. Register each discovered package as a shared vendor.
|
|
266
|
+
|
|
267
|
+
**Excluded automatically:** React, React DOM, jsx runtimes, the router bundle, `@ecopages/*`, workspace packages under `@techn.es/*`, `*-devtools` packages, and packages already vendored by the React plugin.
|
|
268
|
+
|
|
269
|
+
Path aliases resolve from `tsconfig.json` `compilerOptions.paths` (oxc-resolver), same as the Ecopages alias resolver plugin.
|
|
270
|
+
|
|
271
|
+
#### Recommended setup
|
|
272
|
+
|
|
273
|
+
Plugin config — no manual vendor list when provider layouts are flagged:
|
|
274
|
+
|
|
275
|
+
```ts
|
|
276
|
+
import { ConfigBuilder } from '@ecopages/core/config-builder';
|
|
277
|
+
import { reactPlugin } from '@ecopages/react';
|
|
278
|
+
import { ecoRouter } from '@ecopages/react-router';
|
|
279
|
+
|
|
280
|
+
const config = await new ConfigBuilder().setIntegrations([reactPlugin({ router: ecoRouter() })]).build();
|
|
281
|
+
|
|
282
|
+
export default config;
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Provider root layout — set `runtimeProvider: true` on the tier that mounts shared client state:
|
|
286
|
+
|
|
287
|
+
```tsx
|
|
288
|
+
import type { ReactNode } from 'react';
|
|
289
|
+
import { eco } from '@ecopages/core';
|
|
290
|
+
import { QueryProvider } from '@/shared/query/query-provider';
|
|
291
|
+
|
|
292
|
+
export const QueryRootLayout = eco.layout<ReactNode>({
|
|
293
|
+
runtimeProvider: true,
|
|
294
|
+
render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
|
|
295
|
+
});
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Shell layouts that do not mount shared runtime state omit the flag:
|
|
299
|
+
|
|
300
|
+
```tsx
|
|
301
|
+
export const AppShellLayout = eco.layout({
|
|
302
|
+
render: ({ children }) => <AppShell>{children}</AppShell>,
|
|
303
|
+
});
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Stack provider roots before shell tiers in page `layout` arrays so context wraps the shell on both SSR and persisted client navigation.
|
|
307
|
+
|
|
308
|
+
Requires matching tsconfig paths when using aliases:
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{
|
|
312
|
+
"compilerOptions": {
|
|
313
|
+
"paths": {
|
|
314
|
+
"@/*": ["./src/*"]
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
#### Overrides and escape hatches
|
|
321
|
+
|
|
322
|
+
Use explicit `runtimeModules` when discovery misses a package, when `router` is not enabled, or when you need custom vendor output names or externals:
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
reactPlugin({
|
|
326
|
+
router: ecoRouter(),
|
|
327
|
+
runtimeModules: ['@tanstack/react-query', { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] }],
|
|
328
|
+
});
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Manual entries **override** auto-discovered entries for the same specifier.
|
|
332
|
+
|
|
333
|
+
#### Troubleshooting
|
|
334
|
+
|
|
335
|
+
| Symptom | Likely cause | Fix |
|
|
336
|
+
| ------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
337
|
+
| `No QueryClient set` after SPA navigation | Provider library bundled per page chunk | Ensure `router` is enabled; add `runtimeProvider: true` on the provider layout; rebuild vendors |
|
|
338
|
+
| Wrong packages vendored (slow dev startup) | Shell layout scanned as discovery root | Set `runtimeProvider: true` only on provider roots; keep shell layouts unflagged |
|
|
339
|
+
| Package not discovered | Layout outside `layouts/` / `components/`, or import not reachable from `render` | Move layout file or add explicit `runtimeModules` entry |
|
|
340
|
+
| `@/` alias not followed | Missing or invalid tsconfig paths | Add `compilerOptions.paths`; ensure `include` globs are valid JSON (not broken by comment stripping) |
|
|
341
|
+
|
|
342
|
+
#### Tests
|
|
343
|
+
|
|
344
|
+
- [src/bundling/discover-layout-runtime-modules.test.ts](src/bundling/discover-layout-runtime-modules.test.ts): discovery modes, provider scoping, tsconfig aliases, stacked layouts.
|
|
345
|
+
- [src/bundling/runtime-bundle.test.ts](src/bundling/runtime-bundle.test.ts): vendor registration and manifest paths.
|
|
346
|
+
- [../../core/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.test.ts](../../core/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.test.ts): ESM entry resolution and default-export policy for React vs TanStack Query.
|
|
347
|
+
|
|
348
|
+
### Client-only code in SSR trees
|
|
349
|
+
|
|
350
|
+
Pages and layouts SSR through `renderToString`, which does not support `<Suspense>`. Do not use `React.lazy()` + `<Suspense>` in `eco.page()` or `eco.layout()` trees.
|
|
351
|
+
|
|
352
|
+
Wrap browser-only UI in `ClientOnly`:
|
|
353
|
+
|
|
354
|
+
```tsx
|
|
355
|
+
import { eco } from '@ecopages/core';
|
|
356
|
+
import { ClientOnly } from '@ecopages/react/utils/client-only';
|
|
357
|
+
|
|
358
|
+
export const RootLayout = eco.layout({
|
|
359
|
+
render: ({ children }) => (
|
|
360
|
+
<>
|
|
361
|
+
{children}
|
|
362
|
+
<ClientOnly fallback={null}>
|
|
363
|
+
<DevtoolsPanel />
|
|
364
|
+
</ClientOnly>
|
|
365
|
+
</>
|
|
366
|
+
),
|
|
367
|
+
});
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
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.0-beta.
|
|
3
|
+
"version": "0.2.0-beta.31",
|
|
4
4
|
"description": "React integration for Ecopages",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ecopages",
|
|
@@ -8,76 +8,101 @@
|
|
|
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
14
|
"exports": {
|
|
15
15
|
".": {
|
|
16
|
-
"default": "./src/react.plugin.js",
|
|
17
|
-
"types": "./src/react.plugin.d.ts"
|
|
16
|
+
"default": "./src/plugin/react.plugin.js",
|
|
17
|
+
"types": "./src/plugin/react.plugin.d.ts"
|
|
18
18
|
},
|
|
19
19
|
"./eco-embed": {
|
|
20
|
-
"default": "./src/eco-embed.js",
|
|
21
|
-
"types": "./src/eco-embed.d.ts"
|
|
20
|
+
"default": "./src/render/eco-embed.js",
|
|
21
|
+
"types": "./src/render/eco-embed.d.ts"
|
|
22
22
|
},
|
|
23
23
|
"./declarations": {
|
|
24
|
-
"types": "./src/declarations.d.ts"
|
|
24
|
+
"types": "./src/contracts/declarations.d.ts"
|
|
25
25
|
},
|
|
26
26
|
"./utils/dynamic": {
|
|
27
|
-
"types": "./src/
|
|
28
|
-
"default": "./src/
|
|
27
|
+
"types": "./src/app/dynamic.d.ts",
|
|
28
|
+
"default": "./src/app/dynamic.js"
|
|
29
29
|
},
|
|
30
30
|
"./utils/client-only": {
|
|
31
|
-
"types": "./src/
|
|
32
|
-
"default": "./src/
|
|
31
|
+
"types": "./src/app/client-only.d.ts",
|
|
32
|
+
"default": "./src/app/client-only.js"
|
|
33
33
|
},
|
|
34
34
|
"./runtime/use-sync-external-store-with-selector": {
|
|
35
35
|
"types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
|
|
36
36
|
"default": "./src/runtime/use-sync-external-store-with-selector.js"
|
|
37
37
|
},
|
|
38
38
|
"./router-adapter": {
|
|
39
|
-
"types": "./src/router-adapter.d.ts",
|
|
40
|
-
"default": "./src/router-adapter.js"
|
|
39
|
+
"types": "./src/contracts/router-adapter.d.ts",
|
|
40
|
+
"default": "./src/contracts/router-adapter.js"
|
|
41
|
+
},
|
|
42
|
+
"./layout-compose": {
|
|
43
|
+
"types": "./src/render/layout-compose.d.ts",
|
|
44
|
+
"default": "./src/render/layout-compose.js"
|
|
45
|
+
},
|
|
46
|
+
"./serialize-page-data-script": {
|
|
47
|
+
"types": "./src/hydration/serialize-page-data-script.d.ts",
|
|
48
|
+
"default": "./src/hydration/serialize-page-data-script.js"
|
|
49
|
+
},
|
|
50
|
+
"./page-data-reader": {
|
|
51
|
+
"types": "./src/hydration/page-data-reader.d.ts",
|
|
52
|
+
"default": "./src/hydration/page-data-reader.js"
|
|
41
53
|
},
|
|
42
54
|
"./eco-embed.ts": {
|
|
43
|
-
"default": "./src/eco-embed.js",
|
|
44
|
-
"types": "./src/eco-embed.d.ts"
|
|
55
|
+
"default": "./src/render/eco-embed.js",
|
|
56
|
+
"types": "./src/render/eco-embed.d.ts"
|
|
45
57
|
},
|
|
46
58
|
"./declarations.ts": {
|
|
47
|
-
"types": "./src/declarations.d.ts"
|
|
59
|
+
"types": "./src/contracts/declarations.d.ts"
|
|
48
60
|
},
|
|
49
61
|
"./utils/dynamic.ts": {
|
|
50
|
-
"types": "./src/
|
|
51
|
-
"default": "./src/
|
|
62
|
+
"types": "./src/app/dynamic.d.ts",
|
|
63
|
+
"default": "./src/app/dynamic.js"
|
|
52
64
|
},
|
|
53
65
|
"./utils/client-only.ts": {
|
|
54
|
-
"types": "./src/
|
|
55
|
-
"default": "./src/
|
|
66
|
+
"types": "./src/app/client-only.d.ts",
|
|
67
|
+
"default": "./src/app/client-only.js"
|
|
56
68
|
},
|
|
57
69
|
"./runtime/use-sync-external-store-with-selector.ts": {
|
|
58
70
|
"types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
|
|
59
71
|
"default": "./src/runtime/use-sync-external-store-with-selector.js"
|
|
60
72
|
},
|
|
61
73
|
"./router-adapter.ts": {
|
|
62
|
-
"types": "./src/router-adapter.d.ts",
|
|
63
|
-
"default": "./src/router-adapter.js"
|
|
74
|
+
"types": "./src/contracts/router-adapter.d.ts",
|
|
75
|
+
"default": "./src/contracts/router-adapter.js"
|
|
76
|
+
},
|
|
77
|
+
"./layout-compose.ts": {
|
|
78
|
+
"types": "./src/render/layout-compose.d.ts",
|
|
79
|
+
"default": "./src/render/layout-compose.js"
|
|
80
|
+
},
|
|
81
|
+
"./serialize-page-data-script.ts": {
|
|
82
|
+
"types": "./src/hydration/serialize-page-data-script.d.ts",
|
|
83
|
+
"default": "./src/hydration/serialize-page-data-script.js"
|
|
84
|
+
},
|
|
85
|
+
"./page-data-reader.ts": {
|
|
86
|
+
"types": "./src/hydration/page-data-reader.d.ts",
|
|
87
|
+
"default": "./src/hydration/page-data-reader.js"
|
|
64
88
|
}
|
|
65
89
|
},
|
|
66
90
|
"repository": {
|
|
67
91
|
"type": "git",
|
|
68
|
-
"url": "https://github.com/ecopages/ecopages.git",
|
|
92
|
+
"url": "git+https://github.com/ecopages/ecopages.git",
|
|
69
93
|
"directory": "packages/integrations/react"
|
|
70
94
|
},
|
|
71
95
|
"peerDependencies": {
|
|
72
|
-
"@ecopages/core": "0.2.0-beta.
|
|
96
|
+
"@ecopages/core": "0.2.0-beta.31",
|
|
73
97
|
"@types/react": "^19",
|
|
74
98
|
"@types/react-dom": "^19",
|
|
75
99
|
"react": "^19",
|
|
76
100
|
"react-dom": "^19"
|
|
77
101
|
},
|
|
78
102
|
"dependencies": {
|
|
79
|
-
"@ecopages/file-system": "0.2.0-beta.
|
|
103
|
+
"@ecopages/file-system": "0.2.0-beta.31",
|
|
80
104
|
"@ecopages/logger": "^0.2.3",
|
|
105
|
+
"@ecopages/mdx": "0.2.0-beta.31",
|
|
81
106
|
"@mdx-js/mdx": "^3.1.1",
|
|
82
107
|
"oxc-parser": "^0.124.0",
|
|
83
108
|
"oxc-transform": "^0.124.0",
|
|
@@ -6,18 +6,22 @@
|
|
|
6
6
|
*
|
|
7
7
|
* @module
|
|
8
8
|
*/
|
|
9
|
-
import type {
|
|
9
|
+
import type { EcoPagesAppConfig } from '@ecopages/core';
|
|
10
|
+
import type { AssetProcessingService } from '@ecopages/core/services/asset-processing-service';
|
|
11
|
+
import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
|
|
10
12
|
import type { CompileOptions } from '@mdx-js/mdx';
|
|
11
|
-
import { type ReactRuntimeImports } from './
|
|
13
|
+
import { type ReactRuntimeImports } from './runtime-bundle.js';
|
|
14
|
+
import type { ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
|
|
12
15
|
/**
|
|
13
|
-
* Configuration for the
|
|
16
|
+
* Configuration for the BundleService.
|
|
14
17
|
*/
|
|
15
|
-
export interface
|
|
18
|
+
export interface BundleServiceConfig {
|
|
16
19
|
rootDir: string;
|
|
20
|
+
appConfig: EcoPagesAppConfig;
|
|
21
|
+
hostIntegrationName: string;
|
|
17
22
|
routerAdapter?: ReactRouterAdapter;
|
|
23
|
+
runtimeModules?: ResolvedReactPluginRuntimeModule[];
|
|
18
24
|
mdxCompilerOptions?: CompileOptions;
|
|
19
|
-
nonReactExtensions?: string[];
|
|
20
|
-
jsxImportSource?: string;
|
|
21
25
|
}
|
|
22
26
|
/**
|
|
23
27
|
* Optional flags that adjust how a React client entry is bundled.
|
|
@@ -36,14 +40,23 @@ export interface ReactClientBundleOptions {
|
|
|
36
40
|
/**
|
|
37
41
|
* Manages bundle configuration and plugin creation for React page/component builds.
|
|
38
42
|
*/
|
|
39
|
-
export declare class
|
|
43
|
+
export declare class BundleService {
|
|
40
44
|
private readonly runtimeBundleService;
|
|
41
45
|
private readonly config;
|
|
42
|
-
|
|
46
|
+
private pageLayoutNormalizationVendorPromise;
|
|
47
|
+
constructor(config: BundleServiceConfig);
|
|
43
48
|
/**
|
|
44
49
|
* Returns resolved runtime import paths for the React runtime.
|
|
45
50
|
*/
|
|
46
51
|
getRuntimeImports(): ReactRuntimeImports;
|
|
52
|
+
/**
|
|
53
|
+
* Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
|
|
54
|
+
*
|
|
55
|
+
* @remarks
|
|
56
|
+
* Concurrent callers share the same in-flight promise. Asset processing itself caches
|
|
57
|
+
* by dependency key, so repeats after success remain cheap.
|
|
58
|
+
*/
|
|
59
|
+
ensurePageLayoutNormalizationVendorProcessed(assetProcessingService: Pick<AssetProcessingService, 'processDependencies'>): Promise<void>;
|
|
47
60
|
/**
|
|
48
61
|
* Creates bundle options for a page or component entry.
|
|
49
62
|
*
|
|
@@ -1,20 +1,20 @@
|
|
|
1
|
-
import { createClientGraphBoundaryPlugin } from "../
|
|
2
|
-
import {
|
|
3
|
-
getReactClientGraphAllowSpecifiers,
|
|
4
|
-
getReactRuntimeExternalSpecifiers
|
|
5
|
-
} from "../utils/react-runtime-alias-map.js";
|
|
1
|
+
import { createClientGraphBoundaryPlugin } from "../client-graph/boundary-plugin.js";
|
|
2
|
+
import { getReactClientGraphAllowSpecifiers, getReactRuntimeExternalSpecifiers } from "./runtime-alias-map.js";
|
|
6
3
|
import { createBrowserRuntimePlugin } from "@ecopages/core/build/browser-runtime-plugin";
|
|
7
|
-
import {
|
|
8
|
-
import {
|
|
9
|
-
import { createReactMdxLoaderPlugin } from "../
|
|
10
|
-
|
|
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 {
|
|
11
9
|
runtimeBundleService;
|
|
12
10
|
config;
|
|
11
|
+
pageLayoutNormalizationVendorPromise;
|
|
13
12
|
constructor(config) {
|
|
14
13
|
this.config = config;
|
|
15
|
-
this.runtimeBundleService = new
|
|
14
|
+
this.runtimeBundleService = new RuntimeBundleService({
|
|
16
15
|
rootDir: config.rootDir,
|
|
17
|
-
routerAdapter: config.routerAdapter
|
|
16
|
+
routerAdapter: config.routerAdapter,
|
|
17
|
+
runtimeModules: config.runtimeModules
|
|
18
18
|
});
|
|
19
19
|
}
|
|
20
20
|
/**
|
|
@@ -23,6 +23,25 @@ class ReactBundleService {
|
|
|
23
23
|
getRuntimeImports() {
|
|
24
24
|
return this.runtimeBundleService.getRuntimeImports();
|
|
25
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
|
+
});
|
|
42
|
+
}
|
|
43
|
+
await this.pageLayoutNormalizationVendorPromise;
|
|
44
|
+
}
|
|
26
45
|
/**
|
|
27
46
|
* Creates bundle options for a page or component entry.
|
|
28
47
|
*
|
|
@@ -40,7 +59,7 @@ class ReactBundleService {
|
|
|
40
59
|
const options = {
|
|
41
60
|
mainFields: ["module", "browser", "main"],
|
|
42
61
|
naming: `${componentName}.[ext]`,
|
|
43
|
-
...
|
|
62
|
+
...isReactProductionRuntime() && {
|
|
44
63
|
minify: true,
|
|
45
64
|
treeshaking: true
|
|
46
65
|
},
|
|
@@ -57,15 +76,19 @@ class ReactBundleService {
|
|
|
57
76
|
];
|
|
58
77
|
}
|
|
59
78
|
const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
|
|
79
|
+
projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
|
|
60
80
|
absWorkingDir: this.config.rootDir,
|
|
61
81
|
declaredModules,
|
|
62
|
-
alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
hostJsxImportSource: this.config.jsxImportSource ?? "react",
|
|
67
|
-
foreignExtensions: this.config.nonReactExtensions ?? []
|
|
82
|
+
alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(
|
|
83
|
+
this.runtimeBundleService.getConfiguredRuntimeModuleSpecifiers(),
|
|
84
|
+
this.config.routerAdapter
|
|
85
|
+
)
|
|
68
86
|
});
|
|
87
|
+
const [foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(
|
|
88
|
+
this.config.appConfig,
|
|
89
|
+
this.config.hostIntegrationName,
|
|
90
|
+
{ name: "react-renderer-foreign-jsx-override" }
|
|
91
|
+
);
|
|
69
92
|
const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
|
|
70
93
|
const runtimeRewritePlugin = createBrowserRuntimePlugin({
|
|
71
94
|
name: "react-renderer-runtime-import-rewrite",
|
|
@@ -74,13 +97,22 @@ class ReactBundleService {
|
|
|
74
97
|
const runtimePlugins = bundleOptions.includeRuntime ? [] : [runtimeRewritePlugin].filter((plugin) => plugin !== null);
|
|
75
98
|
if (isMdx && this.config.mdxCompilerOptions) {
|
|
76
99
|
const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
|
|
77
|
-
options.plugins = [
|
|
100
|
+
options.plugins = [
|
|
101
|
+
...foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : [],
|
|
102
|
+
graphBoundaryPlugin,
|
|
103
|
+
...runtimePlugins,
|
|
104
|
+
mdxPlugin
|
|
105
|
+
];
|
|
78
106
|
} else {
|
|
79
|
-
options.plugins = [
|
|
107
|
+
options.plugins = [
|
|
108
|
+
...foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : [],
|
|
109
|
+
graphBoundaryPlugin,
|
|
110
|
+
...runtimePlugins
|
|
111
|
+
];
|
|
80
112
|
}
|
|
81
113
|
return options;
|
|
82
114
|
}
|
|
83
115
|
}
|
|
84
116
|
export {
|
|
85
|
-
|
|
117
|
+
BundleService
|
|
86
118
|
};
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Discovers npm packages reachable from persisted `eco.layout()` client graphs.
|
|
3
|
+
*
|
|
4
|
+
* @module
|
|
5
|
+
*/
|
|
6
|
+
export type LayoutRuntimeDiscoveryMode = 'runtime-provider-layouts' | 'provider-scoped-fallback';
|
|
7
|
+
export type LayoutRuntimeDiscoveryResult = {
|
|
8
|
+
specifiers: string[];
|
|
9
|
+
mode: LayoutRuntimeDiscoveryMode;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Returns true when a layout opts into runtime-provider auto-vendoring discovery.
|
|
13
|
+
*/
|
|
14
|
+
export declare function isRuntimeProviderLayoutSource(source: string): boolean;
|
|
15
|
+
/**
|
|
16
|
+
* Returns true when a module looks like it mounts shared client runtime state
|
|
17
|
+
* (React context providers, query clients, etc.).
|
|
18
|
+
*/
|
|
19
|
+
export declare function isProviderRuntimeModulePath(filePath: string, source: string): boolean;
|
|
20
|
+
/**
|
|
21
|
+
* Normalizes import specifiers to the package entry used for browser vendors.
|
|
22
|
+
*/
|
|
23
|
+
export declare function normalizeRuntimePackageSpecifier(specifier: string): string;
|
|
24
|
+
/**
|
|
25
|
+
* Finds npm packages imported from persisted layout client graphs under the given directories.
|
|
26
|
+
*/
|
|
27
|
+
export declare function discoverLayoutRuntimeModuleSpecifiers(options: {
|
|
28
|
+
searchDirs: string[];
|
|
29
|
+
projectRoot?: string;
|
|
30
|
+
extensions?: readonly string[];
|
|
31
|
+
routerImportPath?: string;
|
|
32
|
+
}): LayoutRuntimeDiscoveryResult;
|