@ecopages/react 0.2.0-beta.23 → 0.2.0-beta.25
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 +142 -0
- package/package.json +4 -4
- package/src/react-hmr-strategy.js +1 -0
- package/src/react-renderer.js +1 -0
- package/src/react.plugin.d.ts +1 -0
- package/src/react.plugin.js +45 -2
- package/src/react.types.d.ts +46 -0
- package/src/services/react-bundle.service.d.ts +2 -0
- package/src/services/react-bundle.service.js +7 -2
- package/src/services/react-runtime-bundle.service.d.ts +7 -0
- package/src/services/react-runtime-bundle.service.js +48 -2
- package/src/utils/client-graph-ast-transform.d.ts +1 -1
- package/src/utils/client-graph-ast-transform.js +2 -2
- package/src/utils/client-graph-boundary-plugin.d.ts +2 -0
- package/src/utils/client-graph-boundary-plugin.js +2 -1
- package/src/utils/client-graph-reachability.d.ts +1 -1
- package/src/utils/client-graph-reachability.js +9 -2
- package/src/utils/discover-layout-runtime-modules.d.ts +32 -0
- package/src/utils/discover-layout-runtime-modules.js +180 -0
- package/src/utils/reachability-analyzer.d.ts +2 -2
- package/src/utils/reachability-analyzer.js +4 -1
- package/src/utils/react-plugin-runtime-modules.d.ts +29 -0
- package/src/utils/react-plugin-runtime-modules.js +38 -0
- package/src/utils/react-runtime-alias-map.d.ts +4 -2
- package/src/utils/react-runtime-alias-map.js +13 -2
package/README.md
CHANGED
|
@@ -218,3 +218,145 @@ Layout prop factories receive `LayoutPropsContext` (`params`, `query`, `locals`)
|
|
|
218
218
|
- [src/layout-compose.ts](src/layout-compose.ts): shared client/SSR tree builder.
|
|
219
219
|
- [src/test/react-ssr-hydration-parity.test.tsx](src/test/react-ssr-hydration-parity.test.tsx): nested tier order parity between SSR and `composeLayoutPageTree`.
|
|
220
220
|
- [src/test/react-ssr-unified.test.tsx](src/test/react-ssr-unified.test.tsx): provider context through nested SSR layouts.
|
|
221
|
+
|
|
222
|
+
### Shared runtime vendors (SPA + persisted layouts)
|
|
223
|
+
|
|
224
|
+
#### Mental model
|
|
225
|
+
|
|
226
|
+
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.
|
|
227
|
+
|
|
228
|
+
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.
|
|
229
|
+
|
|
230
|
+
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.
|
|
231
|
+
|
|
232
|
+
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.
|
|
233
|
+
|
|
234
|
+
#### When auto-discovery runs
|
|
235
|
+
|
|
236
|
+
Auto-discovery runs at plugin setup when **both** are true:
|
|
237
|
+
|
|
238
|
+
- `router` is passed to `reactPlugin()`
|
|
239
|
+
- The app config exposes `absolutePaths.projectDir`, `layoutsDir`, and `componentsDir`
|
|
240
|
+
|
|
241
|
+
Without `router`, only explicit `runtimeModules` entries are vendored.
|
|
242
|
+
|
|
243
|
+
#### Discovery modes
|
|
244
|
+
|
|
245
|
+
| Mode | Trigger | Layout roots scanned | npm packages collected |
|
|
246
|
+
| ---------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- |
|
|
247
|
+
| **Runtime-provider** (recommended) | At least one layout sets `runtimeProvider: true` | Only flagged layouts | Every reachable npm package in that layout's `render` graph |
|
|
248
|
+
| **Provider-scoped fallback** | No layout sets `runtimeProvider: true` | All `eco.layout(` files under `layouts/` and `components/` | npm packages imported from provider/context modules only |
|
|
249
|
+
|
|
250
|
+
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.
|
|
251
|
+
|
|
252
|
+
#### What gets discovered
|
|
253
|
+
|
|
254
|
+
1. Select layout entry files using the mode above.
|
|
255
|
+
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.
|
|
256
|
+
3. Collect npm package roots (for example `@tanstack/react-query`, not `@tanstack/react-query/devtools`).
|
|
257
|
+
4. Register each discovered package as a shared vendor.
|
|
258
|
+
|
|
259
|
+
**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.
|
|
260
|
+
|
|
261
|
+
Path aliases resolve from `tsconfig.json` `compilerOptions.paths` (oxc-resolver), same as the Ecopages alias resolver plugin.
|
|
262
|
+
|
|
263
|
+
#### Recommended setup
|
|
264
|
+
|
|
265
|
+
Plugin config — no manual vendor list when provider layouts are flagged:
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
import { ConfigBuilder } from '@ecopages/core/config-builder';
|
|
269
|
+
import { reactPlugin } from '@ecopages/react';
|
|
270
|
+
import { ecoRouter } from '@ecopages/react-router';
|
|
271
|
+
|
|
272
|
+
const config = await new ConfigBuilder().setIntegrations([reactPlugin({ router: ecoRouter() })]).build();
|
|
273
|
+
|
|
274
|
+
export default config;
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Provider root layout — set `runtimeProvider: true` on the tier that mounts shared client state:
|
|
278
|
+
|
|
279
|
+
```tsx
|
|
280
|
+
import type { ReactNode } from 'react';
|
|
281
|
+
import { eco } from '@ecopages/core';
|
|
282
|
+
import { QueryProvider } from '@/shared/query/query-provider';
|
|
283
|
+
|
|
284
|
+
export const QueryRootLayout = eco.layout<ReactNode>({
|
|
285
|
+
runtimeProvider: true,
|
|
286
|
+
render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
|
|
287
|
+
});
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Shell layouts that do not mount shared runtime state omit the flag:
|
|
291
|
+
|
|
292
|
+
```tsx
|
|
293
|
+
export const AppShellLayout = eco.layout({
|
|
294
|
+
render: ({ children }) => <AppShell>{children}</AppShell>,
|
|
295
|
+
});
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Stack provider roots before shell tiers in page `layout` arrays so context wraps the shell on both SSR and persisted client navigation.
|
|
299
|
+
|
|
300
|
+
Requires matching tsconfig paths when using aliases:
|
|
301
|
+
|
|
302
|
+
```json
|
|
303
|
+
{
|
|
304
|
+
"compilerOptions": {
|
|
305
|
+
"paths": {
|
|
306
|
+
"@/*": ["./src/*"]
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
#### Overrides and escape hatches
|
|
313
|
+
|
|
314
|
+
Use explicit `runtimeModules` when discovery misses a package, when `router` is not enabled, or when you need custom vendor output names or externals:
|
|
315
|
+
|
|
316
|
+
```ts
|
|
317
|
+
reactPlugin({
|
|
318
|
+
router: ecoRouter(),
|
|
319
|
+
runtimeModules: ['@tanstack/react-query', { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] }],
|
|
320
|
+
});
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Manual entries **override** auto-discovered entries for the same specifier.
|
|
324
|
+
|
|
325
|
+
#### Troubleshooting
|
|
326
|
+
|
|
327
|
+
| Symptom | Likely cause | Fix |
|
|
328
|
+
| ------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
329
|
+
| `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 |
|
|
330
|
+
| Wrong packages vendored (slow dev startup) | Shell layout scanned as discovery root | Set `runtimeProvider: true` only on provider roots; keep shell layouts unflagged |
|
|
331
|
+
| Package not discovered | Layout outside `layouts/` / `components/`, or import not reachable from `render` | Move layout file or add explicit `runtimeModules` entry |
|
|
332
|
+
| `@/` alias not followed | Missing or invalid tsconfig paths | Add `compilerOptions.paths`; ensure `include` globs are valid JSON (not broken by comment stripping) |
|
|
333
|
+
|
|
334
|
+
#### Tests
|
|
335
|
+
|
|
336
|
+
- [src/utils/discover-layout-runtime-modules.test.ts](src/utils/discover-layout-runtime-modules.test.ts): discovery modes, provider scoping, tsconfig aliases, stacked layouts.
|
|
337
|
+
- [src/services/react-runtime-bundle.service.test.ts](src/services/react-runtime-bundle.service.test.ts): vendor registration and manifest paths.
|
|
338
|
+
- [../../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.
|
|
339
|
+
|
|
340
|
+
### Client-only code in SSR trees
|
|
341
|
+
|
|
342
|
+
Pages and layouts SSR through `renderToString`, which does not support `<Suspense>`. Do not use `React.lazy()` + `<Suspense>` in `eco.page()` or `eco.layout()` trees.
|
|
343
|
+
|
|
344
|
+
Wrap browser-only UI in `ClientOnly`:
|
|
345
|
+
|
|
346
|
+
```tsx
|
|
347
|
+
import { eco } from '@ecopages/core';
|
|
348
|
+
import { ClientOnly } from '@ecopages/react/utils/client-only';
|
|
349
|
+
|
|
350
|
+
export const RootLayout = eco.layout({
|
|
351
|
+
render: ({ children }) => (
|
|
352
|
+
<>
|
|
353
|
+
{children}
|
|
354
|
+
<ClientOnly fallback={null}>
|
|
355
|
+
<DevtoolsPanel />
|
|
356
|
+
</ClientOnly>
|
|
357
|
+
</>
|
|
358
|
+
),
|
|
359
|
+
});
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
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.25",
|
|
4
4
|
"description": "React integration for Ecopages",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ecopages",
|
|
@@ -85,16 +85,16 @@
|
|
|
85
85
|
"directory": "packages/integrations/react"
|
|
86
86
|
},
|
|
87
87
|
"peerDependencies": {
|
|
88
|
-
"@ecopages/core": "0.2.0-beta.
|
|
88
|
+
"@ecopages/core": "0.2.0-beta.25",
|
|
89
89
|
"@types/react": "^19",
|
|
90
90
|
"@types/react-dom": "^19",
|
|
91
91
|
"react": "^19",
|
|
92
92
|
"react-dom": "^19"
|
|
93
93
|
},
|
|
94
94
|
"dependencies": {
|
|
95
|
-
"@ecopages/file-system": "0.2.0-beta.
|
|
95
|
+
"@ecopages/file-system": "0.2.0-beta.25",
|
|
96
96
|
"@ecopages/logger": "^0.2.3",
|
|
97
|
-
"@ecopages/mdx": "0.2.0-beta.
|
|
97
|
+
"@ecopages/mdx": "0.2.0-beta.25",
|
|
98
98
|
"@mdx-js/mdx": "^3.1.1",
|
|
99
99
|
"oxc-parser": "^0.124.0",
|
|
100
100
|
"oxc-transform": "^0.124.0",
|
|
@@ -70,6 +70,7 @@ class ReactHmrStrategy extends HmrStrategy {
|
|
|
70
70
|
});
|
|
71
71
|
return [
|
|
72
72
|
createClientGraphBoundaryPlugin({
|
|
73
|
+
projectRoot: path.dirname(this.context.getSrcDir()),
|
|
73
74
|
absWorkingDir: path.dirname(this.context.getSrcDir()),
|
|
74
75
|
alwaysAllowSpecifiers: allowSpecifiers,
|
|
75
76
|
declaredModules,
|
package/src/react-renderer.js
CHANGED
|
@@ -77,6 +77,7 @@ class ReactRenderer extends IntegrationRenderer {
|
|
|
77
77
|
appConfig: this.appConfig,
|
|
78
78
|
hostIntegrationName: this.name,
|
|
79
79
|
routerAdapter: this.routerAdapter,
|
|
80
|
+
runtimeModules: reactConfig?.runtimeModules,
|
|
80
81
|
mdxCompilerOptions: this.mdxCompilerOptions
|
|
81
82
|
});
|
|
82
83
|
this.pageModuleService = new ReactPageModuleService({
|
package/src/react.plugin.d.ts
CHANGED
|
@@ -41,6 +41,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
|
|
|
41
41
|
rendererModules?: unknown;
|
|
42
42
|
}): ReactRenderer;
|
|
43
43
|
private ensureRuntimeDependencies;
|
|
44
|
+
private resolveEffectiveRuntimeModules;
|
|
44
45
|
get plugins(): EcoBuildPlugin[];
|
|
45
46
|
get browserRuntimeManifest(): BrowserRuntimeManifest;
|
|
46
47
|
/**
|
package/src/react.plugin.js
CHANGED
|
@@ -11,14 +11,28 @@ import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-ca
|
|
|
11
11
|
import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
|
|
12
12
|
import { appendMdxExtensions, resolveMdxCompilerOptions } from "@ecopages/mdx/core";
|
|
13
13
|
import { ClientGraphBoundaryCache } from "./utils/client-graph-boundary-cache.js";
|
|
14
|
+
import { discoverLayoutRuntimeModuleSpecifiers } from "./utils/discover-layout-runtime-modules.js";
|
|
15
|
+
import {
|
|
16
|
+
mergeReactPluginRuntimeModules,
|
|
17
|
+
resolveReactPluginRuntimeModules
|
|
18
|
+
} from "./utils/react-plugin-runtime-modules.js";
|
|
14
19
|
const appLogger = new Logger("[ReactPlugin]");
|
|
15
20
|
const PLUGIN_NAME = REACT_PLUGIN_NAME;
|
|
16
21
|
const resolveReactMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptions(mdxOptions, { jsxImportSource: "react" });
|
|
17
22
|
const resolveReactPluginOptions = (options) => {
|
|
18
|
-
const {
|
|
23
|
+
const {
|
|
24
|
+
extensions: userExtensions,
|
|
25
|
+
router,
|
|
26
|
+
mdx,
|
|
27
|
+
explicitGraph,
|
|
28
|
+
dependencies,
|
|
29
|
+
runtimeModules,
|
|
30
|
+
...baseConfig
|
|
31
|
+
} = options ?? {};
|
|
19
32
|
const extensions = [...userExtensions ?? [".tsx"]];
|
|
20
33
|
const mdxEnabled = mdx?.enabled ?? false;
|
|
21
34
|
const mdxExtensions = mdx?.extensions ?? [".mdx"];
|
|
35
|
+
const resolvedRuntimeModules = resolveReactPluginRuntimeModules(runtimeModules);
|
|
22
36
|
if (mdxEnabled) {
|
|
23
37
|
appendMdxExtensions(extensions, mdxExtensions);
|
|
24
38
|
} else if (mdx?.extensions?.length) {
|
|
@@ -28,6 +42,7 @@ const resolveReactPluginOptions = (options) => {
|
|
|
28
42
|
}
|
|
29
43
|
const rendererConfig = {
|
|
30
44
|
routerAdapter: router,
|
|
45
|
+
runtimeModules: resolvedRuntimeModules,
|
|
31
46
|
mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : void 0,
|
|
32
47
|
mdxExtensions,
|
|
33
48
|
hmrPageMetadataCache: new ReactHmrPageMetadataCache(),
|
|
@@ -83,7 +98,8 @@ class ReactPlugin extends IntegrationPlugin {
|
|
|
83
98
|
appLogger.debug("MDX mode enabled with React jsx runtime");
|
|
84
99
|
}
|
|
85
100
|
this.runtimeBundleService = new ReactRuntimeBundleService({
|
|
86
|
-
routerAdapter: this.routerAdapter
|
|
101
|
+
routerAdapter: this.routerAdapter,
|
|
102
|
+
runtimeModules: this.rendererConfig.runtimeModules
|
|
87
103
|
});
|
|
88
104
|
}
|
|
89
105
|
/**
|
|
@@ -108,9 +124,36 @@ class ReactPlugin extends IntegrationPlugin {
|
|
|
108
124
|
this.runtimeBundleService.setWorkDir(
|
|
109
125
|
this.appConfig?.absolutePaths?.workDir ?? (this.appConfig?.rootDir ? path.join(this.appConfig.rootDir, this.appConfig.workDir ?? ".eco") : void 0)
|
|
110
126
|
);
|
|
127
|
+
this.runtimeBundleService.setRuntimeModules(this.resolveEffectiveRuntimeModules());
|
|
111
128
|
this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
|
|
112
129
|
this.runtimeDependenciesInitialized = true;
|
|
113
130
|
}
|
|
131
|
+
resolveEffectiveRuntimeModules() {
|
|
132
|
+
const manualModules = this.rendererConfig.runtimeModules ?? [];
|
|
133
|
+
if (!this.routerAdapter || !this.appConfig) {
|
|
134
|
+
return manualModules;
|
|
135
|
+
}
|
|
136
|
+
const discovery = discoverLayoutRuntimeModuleSpecifiers({
|
|
137
|
+
searchDirs: [this.appConfig.absolutePaths.layoutsDir, this.appConfig.absolutePaths.componentsDir].filter(
|
|
138
|
+
Boolean
|
|
139
|
+
),
|
|
140
|
+
projectRoot: this.appConfig.absolutePaths.projectDir,
|
|
141
|
+
routerImportPath: this.routerAdapter.bundle.importPath
|
|
142
|
+
});
|
|
143
|
+
const merged = mergeReactPluginRuntimeModules(manualModules, discovery.specifiers);
|
|
144
|
+
this.rendererConfig.runtimeModules = merged;
|
|
145
|
+
if (discovery.mode === "provider-scoped-fallback") {
|
|
146
|
+
appLogger.debug(
|
|
147
|
+
"Layout runtime auto-vendoring is using provider-scoped fallback discovery. Set runtimeProvider: true on provider root layouts to scope discovery explicitly."
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
if (discovery.specifiers.length > 0) {
|
|
151
|
+
appLogger.debug(
|
|
152
|
+
`Auto-vendoring layout runtime modules for persisted SPA layouts: ${discovery.specifiers.join(", ")}`
|
|
153
|
+
);
|
|
154
|
+
}
|
|
155
|
+
return merged;
|
|
156
|
+
}
|
|
114
157
|
get plugins() {
|
|
115
158
|
if (this.mdxLoaderPlugin) {
|
|
116
159
|
return [this.mdxLoaderPlugin];
|
package/src/react.types.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import type { AssetDefinition } from '@ecopages/core/services/asset-processing-s
|
|
|
2
2
|
import type { CompileOptions } from '@mdx-js/mdx';
|
|
3
3
|
import type { ReactRouterAdapter } from './router-adapter.js';
|
|
4
4
|
import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
|
|
5
|
+
import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from './utils/react-plugin-runtime-modules.js';
|
|
5
6
|
/**
|
|
6
7
|
* MDX configuration options for the React plugin.
|
|
7
8
|
*/
|
|
@@ -61,6 +62,50 @@ export type ReactPluginOptions = {
|
|
|
61
62
|
* ```
|
|
62
63
|
*/
|
|
63
64
|
router?: ReactRouterAdapter;
|
|
65
|
+
/**
|
|
66
|
+
* Optional shared browser runtime vendors.
|
|
67
|
+
*
|
|
68
|
+
* With `router`, npm packages reachable from `eco.layout()` **render graphs**
|
|
69
|
+
* under the app's configured `layouts/` and `components/` directories are
|
|
70
|
+
* discovered automatically and registered as shared vendors (alongside React
|
|
71
|
+
* and React DOM). This prevents duplicate module instances when persisted
|
|
72
|
+
* layouts stay mounted across SPA navigation.
|
|
73
|
+
*
|
|
74
|
+
* Without `router`, only explicit entries here are vendored.
|
|
75
|
+
*
|
|
76
|
+
* @remarks
|
|
77
|
+
* Discovery follows client reachability from each layout's `render` path,
|
|
78
|
+
* resolves relative and tsconfig path aliases, and collects npm package roots
|
|
79
|
+
* imported from provider/context modules in that graph (for example files named
|
|
80
|
+
* `query-provider.tsx` or modules using `QueryClientProvider` / `createContext`).
|
|
81
|
+
* It does not vendor every npm dependency reachable from shell or page UI.
|
|
82
|
+
*
|
|
83
|
+
* Layouts that mount shared runtime state should set `runtimeProvider: true` in
|
|
84
|
+
* `eco.layout({ ... })`. Flagged layouts become the only discovery roots and
|
|
85
|
+
* vendor every reachable npm package in that layout graph. When no layout opts
|
|
86
|
+
* in, discovery falls back to scanning all layouts with provider-scoped npm
|
|
87
|
+
* collection.
|
|
88
|
+
*
|
|
89
|
+
* @example
|
|
90
|
+
* ```ts
|
|
91
|
+
* export const QueryRootLayout = eco.layout({
|
|
92
|
+
* runtimeProvider: true,
|
|
93
|
+
* render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
|
|
94
|
+
* });
|
|
95
|
+
*
|
|
96
|
+
* reactPlugin({
|
|
97
|
+
* router: ecoRouter(),
|
|
98
|
+
* });
|
|
99
|
+
* ```
|
|
100
|
+
*
|
|
101
|
+
* @example Advanced vendor config
|
|
102
|
+
* ```ts
|
|
103
|
+
* runtimeModules: [
|
|
104
|
+
* { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] },
|
|
105
|
+
* ]
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
108
|
+
runtimeModules?: ReactPluginRuntimeModule[];
|
|
64
109
|
/**
|
|
65
110
|
* MDX configuration for handling .mdx files within the React plugin.
|
|
66
111
|
* When enabled, MDX files are treated as React pages with full router support.
|
|
@@ -81,6 +126,7 @@ export type ReactPluginOptions = {
|
|
|
81
126
|
};
|
|
82
127
|
export type ReactRendererConfig = {
|
|
83
128
|
routerAdapter?: ReactRouterAdapter;
|
|
129
|
+
runtimeModules?: ResolvedReactPluginRuntimeModule[];
|
|
84
130
|
mdxCompilerOptions?: CompileOptions;
|
|
85
131
|
mdxExtensions?: string[];
|
|
86
132
|
hmrPageMetadataCache?: ReactHmrPageMetadataCache;
|
|
@@ -10,6 +10,7 @@ import type { EcoPagesAppConfig } from '@ecopages/core';
|
|
|
10
10
|
import type { ReactRouterAdapter } from '../router-adapter.js';
|
|
11
11
|
import type { CompileOptions } from '@mdx-js/mdx';
|
|
12
12
|
import { type ReactRuntimeImports } from './react-runtime-bundle.service.js';
|
|
13
|
+
import type { ResolvedReactPluginRuntimeModule } from '../utils/react-plugin-runtime-modules.js';
|
|
13
14
|
/**
|
|
14
15
|
* Configuration for the ReactBundleService.
|
|
15
16
|
*/
|
|
@@ -18,6 +19,7 @@ export interface ReactBundleServiceConfig {
|
|
|
18
19
|
appConfig: EcoPagesAppConfig;
|
|
19
20
|
hostIntegrationName: string;
|
|
20
21
|
routerAdapter?: ReactRouterAdapter;
|
|
22
|
+
runtimeModules?: ResolvedReactPluginRuntimeModule[];
|
|
21
23
|
mdxCompilerOptions?: CompileOptions;
|
|
22
24
|
}
|
|
23
25
|
/**
|
|
@@ -14,7 +14,8 @@ class ReactBundleService {
|
|
|
14
14
|
this.config = config;
|
|
15
15
|
this.runtimeBundleService = new ReactRuntimeBundleService({
|
|
16
16
|
rootDir: config.rootDir,
|
|
17
|
-
routerAdapter: config.routerAdapter
|
|
17
|
+
routerAdapter: config.routerAdapter,
|
|
18
|
+
runtimeModules: config.runtimeModules
|
|
18
19
|
});
|
|
19
20
|
}
|
|
20
21
|
/**
|
|
@@ -57,9 +58,13 @@ class ReactBundleService {
|
|
|
57
58
|
];
|
|
58
59
|
}
|
|
59
60
|
const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
|
|
61
|
+
projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
|
|
60
62
|
absWorkingDir: this.config.rootDir,
|
|
61
63
|
declaredModules,
|
|
62
|
-
alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(
|
|
64
|
+
alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(
|
|
65
|
+
this.runtimeBundleService.getConfiguredRuntimeModuleSpecifiers(),
|
|
66
|
+
this.config.routerAdapter
|
|
67
|
+
)
|
|
63
68
|
});
|
|
64
69
|
const [foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(
|
|
65
70
|
this.config.appConfig,
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
|
|
10
10
|
import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
|
|
11
11
|
import type { ReactRouterAdapter } from '../router-adapter.js';
|
|
12
|
+
import type { ResolvedReactPluginRuntimeModule } from '../utils/react-plugin-runtime-modules.js';
|
|
12
13
|
import { type BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
|
|
13
14
|
export type ReactRuntimeImports = {
|
|
14
15
|
react: string;
|
|
@@ -21,6 +22,7 @@ export type ReactRuntimeImports = {
|
|
|
21
22
|
};
|
|
22
23
|
export interface ReactRuntimeBundleServiceConfig {
|
|
23
24
|
routerAdapter?: ReactRouterAdapter;
|
|
25
|
+
runtimeModules?: ResolvedReactPluginRuntimeModule[];
|
|
24
26
|
rootDir?: string;
|
|
25
27
|
workDir?: string;
|
|
26
28
|
}
|
|
@@ -30,12 +32,17 @@ export declare class ReactRuntimeBundleService {
|
|
|
30
32
|
constructor(config: ReactRuntimeBundleServiceConfig);
|
|
31
33
|
setRootDir(rootDir: string | undefined): void;
|
|
32
34
|
setWorkDir(workDir: string | undefined): void;
|
|
35
|
+
setRuntimeModules(runtimeModules: ResolvedReactPluginRuntimeModule[]): void;
|
|
33
36
|
private get isDevelopment();
|
|
34
37
|
private getCurrentRuntimeMode;
|
|
35
38
|
private createRuntimeDefines;
|
|
36
39
|
private getReactVendorFileName;
|
|
37
40
|
private getReactDomVendorFileName;
|
|
38
41
|
private getRouterVendorFileName;
|
|
42
|
+
private getConfiguredRuntimeModuleFileName;
|
|
43
|
+
private getConfiguredRuntimeModules;
|
|
44
|
+
getConfiguredRuntimeModuleSpecifiers(): string[];
|
|
45
|
+
private getRuntimeModuleBundleExternals;
|
|
39
46
|
private getUseSyncExternalStoreWithSelectorVendorFileName;
|
|
40
47
|
private createReactVendorImportRewritePlugin;
|
|
41
48
|
getRuntimeImports(mode?: RuntimeMode): ReactRuntimeImports;
|
|
@@ -6,7 +6,11 @@ import {
|
|
|
6
6
|
createBrowserRuntimeScriptAsset
|
|
7
7
|
} from "@ecopages/core/services/asset-processing-service";
|
|
8
8
|
import { createReactDomRuntimeInteropPlugin } from "../utils/react-dom-runtime-interop-plugin.js";
|
|
9
|
-
import {
|
|
9
|
+
import {
|
|
10
|
+
buildReactRuntimeAliasMap,
|
|
11
|
+
buildReactRuntimeManifest,
|
|
12
|
+
getReactRuntimeExternalSpecifiers
|
|
13
|
+
} from "../utils/react-runtime-alias-map.js";
|
|
10
14
|
import {
|
|
11
15
|
createBrowserRuntimeManifest
|
|
12
16
|
} from "@ecopages/core/build/browser-runtime-manifest";
|
|
@@ -21,6 +25,9 @@ class ReactRuntimeBundleService {
|
|
|
21
25
|
setWorkDir(workDir) {
|
|
22
26
|
this.config.workDir = workDir;
|
|
23
27
|
}
|
|
28
|
+
setRuntimeModules(runtimeModules) {
|
|
29
|
+
this.config.runtimeModules = runtimeModules;
|
|
30
|
+
}
|
|
24
31
|
get isDevelopment() {
|
|
25
32
|
return process.env.NODE_ENV === "development";
|
|
26
33
|
}
|
|
@@ -46,6 +53,23 @@ class ReactRuntimeBundleService {
|
|
|
46
53
|
}
|
|
47
54
|
return mode === "development" ? `${this.config.routerAdapter.bundle.outputName}.development.js` : `${this.config.routerAdapter.bundle.outputName}.js`;
|
|
48
55
|
}
|
|
56
|
+
getConfiguredRuntimeModuleFileName(outputName, mode) {
|
|
57
|
+
return mode === "development" ? `${outputName}.development.js` : `${outputName}.js`;
|
|
58
|
+
}
|
|
59
|
+
getConfiguredRuntimeModules() {
|
|
60
|
+
return this.config.runtimeModules ?? [];
|
|
61
|
+
}
|
|
62
|
+
getConfiguredRuntimeModuleSpecifiers() {
|
|
63
|
+
return this.getConfiguredRuntimeModules().map((module) => module.specifier);
|
|
64
|
+
}
|
|
65
|
+
getRuntimeModuleBundleExternals(module, mappedSpecifiers) {
|
|
66
|
+
return [
|
|
67
|
+
...getReactRuntimeExternalSpecifiers(),
|
|
68
|
+
...this.config.routerAdapter?.bundle.externals ?? [],
|
|
69
|
+
...this.config.routerAdapter ? [this.config.routerAdapter.bundle.importPath] : [],
|
|
70
|
+
...module.externals
|
|
71
|
+
].filter((external) => !mappedSpecifiers.has(external));
|
|
72
|
+
}
|
|
49
73
|
getUseSyncExternalStoreWithSelectorVendorFileName(mode) {
|
|
50
74
|
return mode === "development" ? "use-sync-external-store-with-selector.development.js" : "use-sync-external-store-with-selector.js";
|
|
51
75
|
}
|
|
@@ -84,7 +108,11 @@ class ReactRuntimeBundleService {
|
|
|
84
108
|
return buildReactRuntimeAliasMap(this.getRuntimeImports(mode));
|
|
85
109
|
}
|
|
86
110
|
getRuntimeManifest(mode = this.getCurrentRuntimeMode()) {
|
|
87
|
-
return buildReactRuntimeManifest(
|
|
111
|
+
return buildReactRuntimeManifest(
|
|
112
|
+
this.getRuntimeImports(mode),
|
|
113
|
+
this.getConfiguredRuntimeModules(),
|
|
114
|
+
(outputName) => buildBrowserRuntimeAssetUrl(this.getConfiguredRuntimeModuleFileName(outputName, mode))
|
|
115
|
+
);
|
|
88
116
|
}
|
|
89
117
|
getDependencies(options) {
|
|
90
118
|
const dependencies = [];
|
|
@@ -168,6 +196,24 @@ class ReactRuntimeBundleService {
|
|
|
168
196
|
})
|
|
169
197
|
);
|
|
170
198
|
}
|
|
199
|
+
for (const runtimeModule of this.getConfiguredRuntimeModules()) {
|
|
200
|
+
dependencies.push(
|
|
201
|
+
createBrowserRuntimeModuleAsset({
|
|
202
|
+
modules: [{ specifier: runtimeModule.specifier, defaultExport: true }],
|
|
203
|
+
name: runtimeModule.outputName,
|
|
204
|
+
fileName: this.getConfiguredRuntimeModuleFileName(runtimeModule.outputName, mode),
|
|
205
|
+
cacheDirName: `ecopages-react-runtime-module-${runtimeModule.outputName}-${mode}`,
|
|
206
|
+
rootDir: this.config.rootDir,
|
|
207
|
+
workDir: this.config.workDir,
|
|
208
|
+
bundleOptions: {
|
|
209
|
+
define: this.createRuntimeDefines(mode),
|
|
210
|
+
external: this.getRuntimeModuleBundleExternals(runtimeModule, mappedSpecifiers),
|
|
211
|
+
excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
|
|
212
|
+
plugins: [runtimeAliasPlugin]
|
|
213
|
+
}
|
|
214
|
+
})
|
|
215
|
+
);
|
|
216
|
+
}
|
|
171
217
|
}
|
|
172
218
|
return dependencies;
|
|
173
219
|
}
|
|
@@ -12,7 +12,7 @@ import type { RequestedExportRules } from './client-graph-boundary-cache.js';
|
|
|
12
12
|
* @param requestedExports - Local requested-export registry used to propagate named reachability across files.
|
|
13
13
|
* @returns An object containing the transformed string and a boolean indicating if changes occurred.
|
|
14
14
|
*/
|
|
15
|
-
export declare function transformModuleImports(source: string, filename: string, globallyAllowed: Map<string, Set<string> | '*'>, requestedExports: Map<string, RequestedExportRules
|
|
15
|
+
export declare function transformModuleImports(source: string, filename: string, globallyAllowed: Map<string, Set<string> | '*'>, requestedExports: Map<string, RequestedExportRules>, projectRoot?: string): {
|
|
16
16
|
transformed: string;
|
|
17
17
|
modified: boolean;
|
|
18
18
|
};
|
|
@@ -83,7 +83,7 @@ function stripServerOnlyEcoPageOptions(source, program) {
|
|
|
83
83
|
}
|
|
84
84
|
return { transformed, modified: true };
|
|
85
85
|
}
|
|
86
|
-
function transformModuleImports(source, filename, globallyAllowed, requestedExports) {
|
|
86
|
+
function transformModuleImports(source, filename, globallyAllowed, requestedExports, projectRoot) {
|
|
87
87
|
let result;
|
|
88
88
|
try {
|
|
89
89
|
result = cachedParseSync(filename, source, {
|
|
@@ -151,7 +151,7 @@ function transformModuleImports(source, filename, globallyAllowed, requestedExpo
|
|
|
151
151
|
}
|
|
152
152
|
return { allowed: false };
|
|
153
153
|
}
|
|
154
|
-
if (isProjectAliasSpecifier(specifier)) return { allowed: true, rules: explicitRules ?? "*" };
|
|
154
|
+
if (isProjectAliasSpecifier(specifier, projectRoot)) return { allowed: true, rules: explicitRules ?? "*" };
|
|
155
155
|
if (!isBareSpecifier(specifier)) return { allowed: true, rules: explicitRules ?? "*" };
|
|
156
156
|
return { allowed: true, rules: explicitRules ?? "*" };
|
|
157
157
|
}
|
|
@@ -13,6 +13,8 @@ import { ClientGraphBoundaryCache } from './client-graph-boundary-cache.js';
|
|
|
13
13
|
* from accidentally leaking into the browser compilation step, which would cause immediate crashes.
|
|
14
14
|
*/
|
|
15
15
|
type ClientGraphBoundaryOptions = {
|
|
16
|
+
/** Absolute path to the app project root, used for tsconfig path alias classification. */
|
|
17
|
+
projectRoot?: string;
|
|
16
18
|
/** Absolute path to the current working directory, used as a root fallback for resolving inline file reads. */
|
|
17
19
|
absWorkingDir?: string;
|
|
18
20
|
/**
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import type { RequestedExportRules } from './client-graph-boundary-cache.js';
|
|
5
5
|
export declare function isBareSpecifier(specifier: string): boolean;
|
|
6
|
-
export declare function isProjectAliasSpecifier(specifier: string): boolean;
|
|
6
|
+
export declare function isProjectAliasSpecifier(specifier: string, projectRoot?: string): boolean;
|
|
7
7
|
/**
|
|
8
8
|
* Determines whether a specifier should be treated as server-only.
|
|
9
9
|
*
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { loadTsconfigPathPrefixes, matchesTsconfigPathPrefix } from "@ecopages/core/plugins/tsconfig-import-resolver";
|
|
1
2
|
import { dirname, resolve } from "node:path";
|
|
2
3
|
function isBareSpecifier(specifier) {
|
|
3
4
|
if (specifier.startsWith(".")) return false;
|
|
@@ -5,8 +6,14 @@ function isBareSpecifier(specifier) {
|
|
|
5
6
|
if (specifier.includes("://")) return false;
|
|
6
7
|
return true;
|
|
7
8
|
}
|
|
8
|
-
function isProjectAliasSpecifier(specifier) {
|
|
9
|
-
|
|
9
|
+
function isProjectAliasSpecifier(specifier, projectRoot) {
|
|
10
|
+
if (specifier.startsWith("ecopages:")) {
|
|
11
|
+
return true;
|
|
12
|
+
}
|
|
13
|
+
if (projectRoot) {
|
|
14
|
+
return matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot));
|
|
15
|
+
}
|
|
16
|
+
return false;
|
|
10
17
|
}
|
|
11
18
|
function isServerOnlySpecifier(specifier) {
|
|
12
19
|
if (specifier.startsWith("node:")) return true;
|
|
@@ -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;
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import { existsSync, readFileSync, readdirSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import {
|
|
4
|
+
isBarePackageImportSpecifier,
|
|
5
|
+
resolveProjectModulePath
|
|
6
|
+
} from "@ecopages/core/plugins/tsconfig-import-resolver";
|
|
7
|
+
import { analyzeReachability } from "./reachability-analyzer.js";
|
|
8
|
+
import { REACT_RUNTIME_SPECIFIERS } from "./react-runtime-alias-map.js";
|
|
9
|
+
const MODULE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mts", ".mjs"];
|
|
10
|
+
const AUTO_RUNTIME_EXCLUDED_SPECIFIERS = /* @__PURE__ */ new Set([
|
|
11
|
+
...REACT_RUNTIME_SPECIFIERS,
|
|
12
|
+
"react-dom/client",
|
|
13
|
+
"use-sync-external-store/shim",
|
|
14
|
+
"use-sync-external-store/shim/index.js",
|
|
15
|
+
"use-sync-external-store/shim/with-selector",
|
|
16
|
+
"use-sync-external-store/shim/with-selector.js"
|
|
17
|
+
]);
|
|
18
|
+
const AUTO_RUNTIME_EXCLUDED_PACKAGE_PREFIXES = ["@ecopages/", "@techn.es/"];
|
|
19
|
+
const PROVIDER_MODULE_PATH_PATTERN = /(?:^|[/\\])(?:[^/\\]*provider[^/\\]*|[^/\\]*context[^/\\]*)\.(?:tsx?|jsx?|mts?|mjs)$/i;
|
|
20
|
+
const PROVIDER_MODULE_SOURCE_PATTERN = /\b(?:QueryClientProvider|(?:\w+Provider)|createContext|Context\.Provider)\b/;
|
|
21
|
+
function isServerModulePath(filePath) {
|
|
22
|
+
return /\.server\.(?:tsx?|jsx?|mts?|mjs|cjs)$/.test(filePath);
|
|
23
|
+
}
|
|
24
|
+
function isEcoLayoutSource(source) {
|
|
25
|
+
return /\beco\.layout(?:<[^>]*>)?\s*\(/.test(source);
|
|
26
|
+
}
|
|
27
|
+
function isRuntimeProviderLayoutSource(source) {
|
|
28
|
+
return isEcoLayoutSource(source) && /\bruntimeProvider\s*:\s*true\b/.test(source);
|
|
29
|
+
}
|
|
30
|
+
function isProviderRuntimeModulePath(filePath, source) {
|
|
31
|
+
if (PROVIDER_MODULE_PATH_PATTERN.test(filePath)) {
|
|
32
|
+
return true;
|
|
33
|
+
}
|
|
34
|
+
return PROVIDER_MODULE_SOURCE_PATTERN.test(source);
|
|
35
|
+
}
|
|
36
|
+
function normalizeRuntimePackageSpecifier(specifier) {
|
|
37
|
+
if (specifier.startsWith("@")) {
|
|
38
|
+
const parts = specifier.split("/");
|
|
39
|
+
if (parts.length >= 2) {
|
|
40
|
+
return `${parts[0]}/${parts[1]}`;
|
|
41
|
+
}
|
|
42
|
+
return specifier;
|
|
43
|
+
}
|
|
44
|
+
return specifier.split("/")[0] ?? specifier;
|
|
45
|
+
}
|
|
46
|
+
function isAutoRuntimeExcludedPackage(packageRoot) {
|
|
47
|
+
if (AUTO_RUNTIME_EXCLUDED_PACKAGE_PREFIXES.some((prefix) => packageRoot.startsWith(prefix))) {
|
|
48
|
+
return true;
|
|
49
|
+
}
|
|
50
|
+
return packageRoot.endsWith("-devtools");
|
|
51
|
+
}
|
|
52
|
+
function shouldExcludeAutoRuntimeSpecifier(specifier, options) {
|
|
53
|
+
if (AUTO_RUNTIME_EXCLUDED_SPECIFIERS.has(specifier)) {
|
|
54
|
+
return true;
|
|
55
|
+
}
|
|
56
|
+
if (options.routerImportPath && specifier === options.routerImportPath) {
|
|
57
|
+
return true;
|
|
58
|
+
}
|
|
59
|
+
return isAutoRuntimeExcludedPackage(normalizeRuntimePackageSpecifier(specifier));
|
|
60
|
+
}
|
|
61
|
+
function collectLayoutEntryFiles(searchDir, extensions, files) {
|
|
62
|
+
if (!existsSync(searchDir)) {
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
for (const entry of readdirSync(searchDir, { withFileTypes: true })) {
|
|
66
|
+
const entryPath = path.join(searchDir, entry.name);
|
|
67
|
+
if (entry.isDirectory()) {
|
|
68
|
+
collectLayoutEntryFiles(entryPath, extensions, files);
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
if (!entry.isFile()) {
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
if (!extensions.some((extension) => entry.name.endsWith(extension))) {
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
try {
|
|
78
|
+
const source = readFileSync(entryPath, "utf8");
|
|
79
|
+
if (!isEcoLayoutSource(source)) {
|
|
80
|
+
continue;
|
|
81
|
+
}
|
|
82
|
+
files.all.push(entryPath);
|
|
83
|
+
if (isRuntimeProviderLayoutSource(source)) {
|
|
84
|
+
files.runtimeProvider.push(entryPath);
|
|
85
|
+
}
|
|
86
|
+
} catch {
|
|
87
|
+
continue;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
function resolveLayoutDiscoveryPlan(layoutEntries) {
|
|
92
|
+
if (layoutEntries.runtimeProvider.length > 0) {
|
|
93
|
+
return {
|
|
94
|
+
entryFiles: layoutEntries.runtimeProvider,
|
|
95
|
+
mode: "runtime-provider-layouts",
|
|
96
|
+
collectAllReachableNpm: true
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
return {
|
|
100
|
+
entryFiles: layoutEntries.all,
|
|
101
|
+
mode: "provider-scoped-fallback",
|
|
102
|
+
collectAllReachableNpm: false
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
function collectReachableNpmSpecifiersFromFile(filePath, options) {
|
|
106
|
+
if (isServerModulePath(filePath)) {
|
|
107
|
+
return;
|
|
108
|
+
}
|
|
109
|
+
if (options.visitedFiles.has(filePath)) {
|
|
110
|
+
return;
|
|
111
|
+
}
|
|
112
|
+
options.visitedFiles.add(filePath);
|
|
113
|
+
let source;
|
|
114
|
+
try {
|
|
115
|
+
source = readFileSync(filePath, "utf8");
|
|
116
|
+
} catch {
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
const reachability = analyzeReachability(source, filePath);
|
|
120
|
+
if (!reachability.analyzed) {
|
|
121
|
+
return;
|
|
122
|
+
}
|
|
123
|
+
const collectNpmFromModule = options.collectAllReachableNpm || isProviderRuntimeModulePath(filePath, source);
|
|
124
|
+
for (const specifier of reachability.reachableImports.keys()) {
|
|
125
|
+
if (options.projectRoot) {
|
|
126
|
+
const resolvedLocalModule = resolveProjectModulePath(options.projectRoot, filePath, specifier);
|
|
127
|
+
if (resolvedLocalModule) {
|
|
128
|
+
options.queue.push(resolvedLocalModule);
|
|
129
|
+
continue;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
if (!collectNpmFromModule) {
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
if (!isBarePackageImportSpecifier(specifier, options.projectRoot)) {
|
|
136
|
+
continue;
|
|
137
|
+
}
|
|
138
|
+
if (shouldExcludeAutoRuntimeSpecifier(specifier, options)) {
|
|
139
|
+
continue;
|
|
140
|
+
}
|
|
141
|
+
options.discovered.add(normalizeRuntimePackageSpecifier(specifier));
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
function discoverLayoutRuntimeModuleSpecifiers(options) {
|
|
145
|
+
const extensions = options.extensions ?? MODULE_EXTENSIONS;
|
|
146
|
+
const layoutEntries = { all: [], runtimeProvider: [] };
|
|
147
|
+
for (const searchDir of options.searchDirs) {
|
|
148
|
+
collectLayoutEntryFiles(searchDir, extensions, layoutEntries);
|
|
149
|
+
}
|
|
150
|
+
const plan = resolveLayoutDiscoveryPlan(layoutEntries);
|
|
151
|
+
const discovered = /* @__PURE__ */ new Set();
|
|
152
|
+
for (const entryFile of plan.entryFiles) {
|
|
153
|
+
const visitedFiles = /* @__PURE__ */ new Set();
|
|
154
|
+
const queue = [entryFile];
|
|
155
|
+
while (queue.length > 0) {
|
|
156
|
+
const filePath = queue.shift();
|
|
157
|
+
if (!filePath) {
|
|
158
|
+
continue;
|
|
159
|
+
}
|
|
160
|
+
collectReachableNpmSpecifiersFromFile(filePath, {
|
|
161
|
+
projectRoot: options.projectRoot,
|
|
162
|
+
routerImportPath: options.routerImportPath,
|
|
163
|
+
collectAllReachableNpm: plan.collectAllReachableNpm,
|
|
164
|
+
visitedFiles,
|
|
165
|
+
queue,
|
|
166
|
+
discovered
|
|
167
|
+
});
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
return {
|
|
171
|
+
specifiers: [...discovered].sort(),
|
|
172
|
+
mode: plan.mode
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
export {
|
|
176
|
+
discoverLayoutRuntimeModuleSpecifiers,
|
|
177
|
+
isProviderRuntimeModulePath,
|
|
178
|
+
isRuntimeProviderLayoutSource,
|
|
179
|
+
normalizeRuntimePackageSpecifier
|
|
180
|
+
};
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* dependencies (imports, variables, functions, and classes) that begin from explicit client roots.
|
|
7
7
|
*
|
|
8
8
|
* In Ecopages, "client roots" are defined as the `render`, `errorBoundary`, or `loadingFallback`
|
|
9
|
-
* properties passed into `eco.page()` or `eco.component()`. By tracing the execution path from
|
|
9
|
+
* properties passed into `eco.page()`, `eco.layout()`, or `eco.component()`. By tracing the execution path from
|
|
10
10
|
* these roots, the analyzer determines exactly which modules and bindings are actually needed
|
|
11
11
|
* by the browser to hydrate the page, and which imports are unused on the client (and thus can be pruned).
|
|
12
12
|
*/
|
|
@@ -53,7 +53,7 @@ export type ReachabilityResult = {
|
|
|
53
53
|
type ExplicitlyRequestedExports = Set<string> | '*';
|
|
54
54
|
/**
|
|
55
55
|
* Analyzes a module using Oxc AST and extracts a strict reachability graph
|
|
56
|
-
* starting from client roots (`render`, `errorBoundary`, `loadingFallback` of `eco.page` or `eco.component`).
|
|
56
|
+
* starting from client roots (`render`, `errorBoundary`, `loadingFallback` of `eco.page`, `eco.layout`, or `eco.component`).
|
|
57
57
|
*
|
|
58
58
|
* @param source - Raw source string of the module.
|
|
59
59
|
* @param filename - Absolute or relative path to the module file.
|
|
@@ -34,6 +34,9 @@ function analyzeReachability(source, filename, program, explicitlyRequestedExpor
|
|
|
34
34
|
const potentialClientRoots = [];
|
|
35
35
|
for (const statement of resolvedProgram.body) {
|
|
36
36
|
if (statement.type === "ImportDeclaration") {
|
|
37
|
+
if (statement.importKind === "type") {
|
|
38
|
+
continue;
|
|
39
|
+
}
|
|
37
40
|
const specifier = statement.source.value;
|
|
38
41
|
const bindings = /* @__PURE__ */ new Map();
|
|
39
42
|
if (!statement.specifiers || statement.specifiers.length === 0) {
|
|
@@ -91,7 +94,7 @@ function analyzeReachability(source, filename, program, explicitlyRequestedExpor
|
|
|
91
94
|
if (node.type === "CallExpression" && node.callee.type === "MemberExpression") {
|
|
92
95
|
const obj = node.callee.object;
|
|
93
96
|
const prop = node.callee.property;
|
|
94
|
-
if (obj.type === "Identifier" && obj.name === "eco" && prop.type === "Identifier" && (prop.name === "page" || prop.name === "component")) {
|
|
97
|
+
if (obj.type === "Identifier" && obj.name === "eco" && prop.type === "Identifier" && (prop.name === "page" || prop.name === "component" || prop.name === "layout")) {
|
|
95
98
|
potentialClientRoots.push(node.callee);
|
|
96
99
|
const arg = node.arguments[0];
|
|
97
100
|
if (arg && arg.type === "ObjectExpression") {
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Normalizes `reactPlugin({ runtimeModules })` entries for vendor bundling.
|
|
3
|
+
*
|
|
4
|
+
* @module
|
|
5
|
+
*/
|
|
6
|
+
export type ReactPluginRuntimeModule = string | {
|
|
7
|
+
specifier: string;
|
|
8
|
+
outputName?: string;
|
|
9
|
+
externals?: string[];
|
|
10
|
+
};
|
|
11
|
+
export type ResolvedReactPluginRuntimeModule = {
|
|
12
|
+
specifier: string;
|
|
13
|
+
outputName: string;
|
|
14
|
+
externals: string[];
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* Builds a stable vendor filename stem from a package specifier.
|
|
18
|
+
*/
|
|
19
|
+
export declare function resolveReactPluginRuntimeModuleSlug(specifier: string): string;
|
|
20
|
+
/**
|
|
21
|
+
* Resolves user-facing runtime module declarations into vendor bundle config.
|
|
22
|
+
*/
|
|
23
|
+
export declare function resolveReactPluginRuntimeModules(modules: ReactPluginRuntimeModule[] | undefined): ResolvedReactPluginRuntimeModule[];
|
|
24
|
+
/**
|
|
25
|
+
* Merges auto-discovered layout npm imports with explicit `runtimeModules` entries.
|
|
26
|
+
*
|
|
27
|
+
* @remarks Manual entries win when both sources declare the same specifier.
|
|
28
|
+
*/
|
|
29
|
+
export declare function mergeReactPluginRuntimeModules(manualModules: ResolvedReactPluginRuntimeModule[], autoSpecifiers: string[]): ResolvedReactPluginRuntimeModule[];
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
function resolveReactPluginRuntimeModuleSlug(specifier) {
|
|
2
|
+
return specifier.replace(/^@/, "").replace(/\//g, "-");
|
|
3
|
+
}
|
|
4
|
+
function resolveReactPluginRuntimeModules(modules) {
|
|
5
|
+
return (modules ?? []).map((entry) => {
|
|
6
|
+
if (typeof entry === "string") {
|
|
7
|
+
return {
|
|
8
|
+
specifier: entry,
|
|
9
|
+
outputName: resolveReactPluginRuntimeModuleSlug(entry),
|
|
10
|
+
externals: []
|
|
11
|
+
};
|
|
12
|
+
}
|
|
13
|
+
return {
|
|
14
|
+
specifier: entry.specifier,
|
|
15
|
+
outputName: entry.outputName ?? resolveReactPluginRuntimeModuleSlug(entry.specifier),
|
|
16
|
+
externals: entry.externals ?? []
|
|
17
|
+
};
|
|
18
|
+
});
|
|
19
|
+
}
|
|
20
|
+
function mergeReactPluginRuntimeModules(manualModules, autoSpecifiers) {
|
|
21
|
+
const merged = /* @__PURE__ */ new Map();
|
|
22
|
+
for (const specifier of autoSpecifiers) {
|
|
23
|
+
merged.set(specifier, {
|
|
24
|
+
specifier,
|
|
25
|
+
outputName: resolveReactPluginRuntimeModuleSlug(specifier),
|
|
26
|
+
externals: []
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
for (const entry of manualModules) {
|
|
30
|
+
merged.set(entry.specifier, entry);
|
|
31
|
+
}
|
|
32
|
+
return [...merged.values()];
|
|
33
|
+
}
|
|
34
|
+
export {
|
|
35
|
+
mergeReactPluginRuntimeModules,
|
|
36
|
+
resolveReactPluginRuntimeModuleSlug,
|
|
37
|
+
resolveReactPluginRuntimeModules
|
|
38
|
+
};
|
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import type { ReactRouterAdapter } from '../router-adapter.js';
|
|
2
2
|
import type { ReactRuntimeImports } from '../services/react-runtime-bundle.service.js';
|
|
3
|
-
import {
|
|
3
|
+
import type { ResolvedReactPluginRuntimeModule } from './react-plugin-runtime-modules.js';
|
|
4
|
+
import { type BrowserRuntimeAssetDeclaration, type BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
|
|
4
5
|
export declare const REACT_RUNTIME_SPECIFIERS: readonly ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"];
|
|
5
6
|
export declare function buildReactRuntimeAliasMap(runtimeImports: ReactRuntimeImports): Record<string, string>;
|
|
6
|
-
export declare function
|
|
7
|
+
export declare function buildConfiguredRuntimeModuleManifestEntries(modules: readonly ResolvedReactPluginRuntimeModule[], getPublicPath: (outputName: string) => string): BrowserRuntimeAssetDeclaration[];
|
|
8
|
+
export declare function buildReactRuntimeManifest(runtimeImports: ReactRuntimeImports, configuredRuntimeModules?: readonly ResolvedReactPluginRuntimeModule[], getConfiguredRuntimeModulePublicPath?: (outputName: string) => string): BrowserRuntimeManifest;
|
|
7
9
|
export declare function getReactRuntimeExternalSpecifiers(): string[];
|
|
8
10
|
export declare function getReactClientGraphAllowSpecifiers(runtimeSpecifiers: Iterable<string>, routerAdapter?: ReactRouterAdapter): string[];
|
|
@@ -12,7 +12,16 @@ const REACT_RUNTIME_SPECIFIERS = [
|
|
|
12
12
|
function buildReactRuntimeAliasMap(runtimeImports) {
|
|
13
13
|
return Object.fromEntries(getBrowserRuntimeSpecifierMap(buildReactRuntimeManifest(runtimeImports)));
|
|
14
14
|
}
|
|
15
|
-
function
|
|
15
|
+
function buildConfiguredRuntimeModuleManifestEntries(modules, getPublicPath) {
|
|
16
|
+
return modules.map((module) => ({
|
|
17
|
+
specifier: module.specifier,
|
|
18
|
+
owner: "@ecopages/react",
|
|
19
|
+
importPath: module.specifier,
|
|
20
|
+
publicPath: getPublicPath(module.outputName),
|
|
21
|
+
externals: [...getReactRuntimeExternalSpecifiers(), ...module.externals]
|
|
22
|
+
}));
|
|
23
|
+
}
|
|
24
|
+
function buildReactRuntimeManifest(runtimeImports, configuredRuntimeModules = [], getConfiguredRuntimeModulePublicPath = () => "") {
|
|
16
25
|
return createBrowserRuntimeManifest([
|
|
17
26
|
{
|
|
18
27
|
specifier: "react",
|
|
@@ -67,7 +76,8 @@ function buildReactRuntimeManifest(runtimeImports) {
|
|
|
67
76
|
owner: "@ecopages/react",
|
|
68
77
|
importPath: "use-sync-external-store/shim/with-selector.js",
|
|
69
78
|
publicPath: runtimeImports.useSyncExternalStoreWithSelector
|
|
70
|
-
}
|
|
79
|
+
},
|
|
80
|
+
...buildConfiguredRuntimeModuleManifestEntries(configuredRuntimeModules, getConfiguredRuntimeModulePublicPath)
|
|
71
81
|
]);
|
|
72
82
|
}
|
|
73
83
|
function getReactRuntimeExternalSpecifiers() {
|
|
@@ -83,6 +93,7 @@ function getReactClientGraphAllowSpecifiers(runtimeSpecifiers, routerAdapter) {
|
|
|
83
93
|
}
|
|
84
94
|
export {
|
|
85
95
|
REACT_RUNTIME_SPECIFIERS,
|
|
96
|
+
buildConfiguredRuntimeModuleManifestEntries,
|
|
86
97
|
buildReactRuntimeAliasMap,
|
|
87
98
|
buildReactRuntimeManifest,
|
|
88
99
|
getReactClientGraphAllowSpecifiers,
|