@ecopages/react 0.8.0 → 0.10.0
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 +17 -27
- package/package.json +4 -4
- package/src/bundling/bundle.d.ts +6 -0
- package/src/bundling/bundle.js +23 -9
- package/src/client-graph/ast-transform-eco-page.d.ts +14 -1
- package/src/client-graph/ast-transform-eco-page.js +60 -13
- package/src/client-graph/ast-transform-stripped-imports.js +1 -1
- package/src/client-graph/ast-transform-walk-imports.d.ts +0 -1
- package/src/client-graph/ast-transform-walk-imports.js +5 -10
- package/src/client-graph/ast-transform.d.ts +1 -1
- package/src/client-graph/ast-transform.js +1 -2
- package/src/client-graph/boundary-plugin-transform.d.ts +0 -1
- package/src/client-graph/boundary-plugin-transform.js +1 -2
- package/src/client-graph/boundary-plugin.d.ts +19 -0
- package/src/client-graph/boundary-plugin.js +54 -16
- package/src/client-graph/foreign-boundary-rewrite.d.ts +18 -3
- package/src/client-graph/foreign-boundary-rewrite.js +199 -48
- package/src/client-graph/foreign-jsx-reach.d.ts +21 -2
- package/src/client-graph/foreign-jsx-reach.js +56 -14
- package/src/client-graph/foreign-module.d.ts +45 -0
- package/src/client-graph/foreign-module.js +132 -0
- package/src/client-graph/module-classification.d.ts +0 -1
- package/src/client-graph/module-classification.js +0 -4
- package/src/client-graph/reachability-analyzer.d.ts +0 -1
- package/src/client-graph/reachability-analyzer.js +0 -5
- package/src/client-graph/reachability-client-roots.js +28 -0
- package/src/client-graph/requested-exports-plan.d.ts +1 -1
- package/src/client-graph/requested-exports-plan.js +1 -1
- package/src/client-graph/specifier-classification.js +2 -2
- package/src/hmr/hmr-strategy.d.ts +5 -2
- package/src/hmr/hmr-strategy.js +12 -5
- package/src/hydration/browser/foreign-boundary.d.ts +12 -0
- package/src/hydration/browser/foreign-boundary.js +19 -0
- package/src/hydration/browser/page-hydration-hmr.d.ts +1 -0
- package/src/hydration/browser/page-hydration-hmr.js +2 -2
- package/src/hydration/browser/page-hydration.d.ts +2 -1
- package/src/hydration/browser/page-hydration.js +3 -2
- package/src/hydration/hydration-page-entry-source.js +3 -3
- package/src/hydration/page-data-manifest.d.ts +22 -1
- package/src/hydration/page-data-manifest.js +38 -3
- package/src/hydration/page-data-reader.d.ts +2 -1
- package/src/hydration/page-data-reader.js +4 -2
- package/src/hydration/page-payload.d.ts +6 -15
- package/src/hydration/page-payload.js +5 -42
- package/src/hydration/serialize-page-data-script.d.ts +4 -4
- package/src/hydration/serialize-page-data-script.js +6 -6
- package/src/page/page-module.d.ts +4 -2
- package/src/page/page-module.js +8 -23
- package/src/plugin/react.plugin.js +2 -0
- package/src/render/component-ownership.d.ts +1 -6
- package/src/render/component-ownership.js +0 -3
- package/src/render/component-ssr.d.ts +0 -1
- package/src/render/component-ssr.js +0 -7
- package/src/render/layout-compose.d.ts +16 -8
- package/src/render/layout-compose.js +13 -36
- package/src/render/react-renderer.js +37 -55
package/README.md
CHANGED
|
@@ -120,7 +120,7 @@ The client-graph boundary analyzes project modules during each browser build and
|
|
|
120
120
|
|
|
121
121
|
`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.
|
|
122
122
|
|
|
123
|
-
It does **not** disable the client-graph AST boundary. Server-only `eco.page(...)` options such as `middleware` and `
|
|
123
|
+
It does **not** disable the client-graph AST boundary. Server-only `eco.page(...)` options such as `middleware` and `props` are still stripped from browser bundles. With a router adapter, page hydration is already always on, so the option is redundant for SPA apps.
|
|
124
124
|
|
|
125
125
|
The option name is historical — it forces hydration asset emission, it does not mean “skip graph transforms.”
|
|
126
126
|
|
|
@@ -136,13 +136,12 @@ The client bundle keeps:
|
|
|
136
136
|
The client bundle removes or excludes:
|
|
137
137
|
|
|
138
138
|
- Server-only imports that are not reachable from the hydrated render path.
|
|
139
|
-
- Server-only `eco.page(...)` options such as `cache`, `middleware`, `metadata`, `
|
|
139
|
+
- Server-only `eco.page(...)` options such as `cache`, `middleware`, `metadata`, `props`, and `paths`.
|
|
140
140
|
- Request-time configuration that has no meaning in the browser.
|
|
141
141
|
|
|
142
142
|
Important:
|
|
143
143
|
|
|
144
|
-
- `render` must stay in the client bundle, because hydration needs it to reconstruct the page tree.
|
|
145
|
-
- `requires` does **not** stay in the browser page config. It is used on the server to decide which `locals` keys may be serialized into the hydration payload.
|
|
144
|
+
- `render` must stay in the client bundle, because hydration needs it to reconstruct the page tree. It receives no `locals`, only what `props` returned, so it needs no request code in the browser.
|
|
146
145
|
|
|
147
146
|
### AST Pipeline Order
|
|
148
147
|
|
|
@@ -172,18 +171,17 @@ Consider a page like this:
|
|
|
172
171
|
import { authMiddleware } from './auth.server';
|
|
173
172
|
import { getPost } from './posts.server';
|
|
174
173
|
|
|
175
|
-
const
|
|
174
|
+
const getProps = async () => ({ post: await getPost() });
|
|
176
175
|
|
|
177
176
|
export default eco.page({
|
|
178
177
|
cache: 'dynamic',
|
|
179
178
|
middleware: [authMiddleware],
|
|
180
|
-
|
|
181
|
-
staticProps,
|
|
179
|
+
props: getProps,
|
|
182
180
|
render: () => <div>Dashboard</div>,
|
|
183
181
|
});
|
|
184
182
|
```
|
|
185
183
|
|
|
186
|
-
If the client transform removed the `auth.server` import but left `middleware: [authMiddleware]` in place, the browser bundle would contain a dangling identifier and throw a `ReferenceError` when it loads. The boundary therefore strips the server-only options, then the `
|
|
184
|
+
If the client transform removed the `auth.server` import but left `middleware: [authMiddleware]` in place, the browser bundle would contain a dangling identifier and throw a `ReferenceError` when it loads. The boundary therefore strips the server-only options, then the `getProps` helper they alone used, while keeping `render` intact.
|
|
187
185
|
|
|
188
186
|
A stripped import still used by code the browser module needs fails the build with its `file:line:column`:
|
|
189
187
|
|
|
@@ -191,30 +189,22 @@ A stripped import still used by code the browser module needs fails the build wi
|
|
|
191
189
|
[Ecopages Client Graph] 'authMiddleware' (imported from './auth.server') is used at src/widget.tsx:2:22, but that import is server-only and the browser build removes it. ...
|
|
192
190
|
```
|
|
193
191
|
|
|
194
|
-
Move that code into a server-only Page option, into a helper only those options use, or out of the code the browser module reaches.
|
|
192
|
+
Move that code into a server-only Page option, into a helper only those options use, or out of the code the browser module reaches. A server-only import that the render function itself uses fails the build the same way, naming the import, its bindings and the `.server` fix.
|
|
195
193
|
|
|
196
194
|
### Hydration Contract for `locals`
|
|
197
195
|
|
|
198
|
-
The browser
|
|
199
|
-
|
|
200
|
-
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.
|
|
201
|
-
|
|
202
|
-
Example:
|
|
196
|
+
The browser never receives request locals. `render` does not get them: a dynamic Page reads them in `props` and returns what `render` needs, and the hydration payload carries exactly that return value, with the Params, Query and each layout tier's props.
|
|
203
197
|
|
|
204
198
|
```tsx
|
|
205
199
|
export default eco.page({
|
|
206
|
-
|
|
207
|
-
|
|
200
|
+
cache: 'dynamic',
|
|
201
|
+
middleware: [authMiddleware],
|
|
202
|
+
props: ({ locals }) => ({ user: locals.session.user }),
|
|
203
|
+
render: ({ user }) => <Dashboard user={user} />,
|
|
208
204
|
});
|
|
209
205
|
```
|
|
210
206
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
Important:
|
|
214
|
-
|
|
215
|
-
- This filtering is currently top-level only.
|
|
216
|
-
- If `locals.session` itself contains sensitive nested fields, those fields will still be serialized.
|
|
217
|
-
- Middleware should therefore expose a client-safe shape for any key declared in `requires`.
|
|
207
|
+
Whatever `props` returns is serialized, nested fields included, so return a client-safe shape: the user, not the session that holds its token.
|
|
218
208
|
|
|
219
209
|
### Layout Hydration Invariant
|
|
220
210
|
|
|
@@ -225,17 +215,17 @@ That applies to both:
|
|
|
225
215
|
- page hydration lifecycle in [src/hydration/browser/page-hydration.ts](src/hydration/browser/page-hydration.ts)
|
|
226
216
|
- router-backed hydration in [../../react-router/src/router.ts](../../react-router/src/router.ts)
|
|
227
217
|
|
|
228
|
-
|
|
218
|
+
The server resolves each layout tier's props once from its entry's `props` factory and ships them as `tiers`; the browser renders each tier from those props without running a factory, so a layout cannot differ between server and browser.
|
|
229
219
|
|
|
230
220
|
### Tests That Guard This Contract
|
|
231
221
|
|
|
232
222
|
The main regression coverage lives in:
|
|
233
223
|
|
|
234
224
|
- [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.
|
|
235
|
-
- [src/render/react-renderer.locals.test.ts](src/render/react-renderer.locals.test.ts):
|
|
225
|
+
- [src/render/react-renderer.locals.test.ts](src/render/react-renderer.locals.test.ts) and [src/test/react-renderer.test.tsx](src/test/react-renderer.test.tsx): the hydration payload holds the page props, Params, Query and tiers, never `locals`, even when middleware provided a secret.
|
|
236
226
|
- [src/hydration/hydration-entry-source.test.ts](src/hydration/hydration-entry-source.test.ts): a generated island entry registers, and a generated Page entry hydrates, through the bootstrap module it imports.
|
|
237
227
|
- [../../../e2e/fixtures/react-production-start/react-production-start.test.e2e.ts](../../../e2e/fixtures/react-production-start/react-production-start.test.e2e.ts): a built app serves a static and a dynamic Page under `ecopages start`, and their React island hydrates.
|
|
238
|
-
- [../../react-router/test/layout-persistence.test.browser.ts](../../react-router/test/layout-persistence.test.browser.ts): verifies router-backed
|
|
228
|
+
- [../../react-router/test/layout-persistence.test.browser.ts](../../react-router/test/layout-persistence.test.browser.ts): verifies router-backed layouts render from the server-resolved tier props with `persistLayouts` both enabled and disabled.
|
|
239
229
|
- [src/hydration/hydration-lifecycle.test.browser.ts](src/hydration/hydration-lifecycle.test.browser.ts): an uncaught `React.lazy` rejection during first hydration restores the server HTML, keeps body nodes added after mount, drops the page root and makes the next HMR update reload; a Page-level error boundary around the entry still shows its fallback.
|
|
240
230
|
- [../../../playground/kitchen-sink/e2e/content-lazy.test.e2e.ts](../../../playground/kitchen-sink/e2e/content-lazy.test.e2e.ts): a collection chunk that fails during first hydration restores the server HTML (including the playground shell) and is not retried. A Page-level error boundary around the entry keeps the rest of the Page and shows the boundary fallback.
|
|
241
231
|
- [../../../e2e/fixtures/react-lazy-first-load/lazy-first-load.test.e2e.ts](../../../e2e/fixtures/react-lazy-first-load/lazy-first-load.test.e2e.ts): the same first-hydration outcomes for a React Page without the router.
|
|
@@ -252,7 +242,7 @@ A server render tracks which tiers and the page it reached (`LayoutRenderTracker
|
|
|
252
242
|
|
|
253
243
|
During SSR, `ReactRenderer` passes the app-resolved React runtime into `composeLayoutPageTree` via `options.react` so layout trees are built with the same module instance the server renders them with. 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).
|
|
254
244
|
|
|
255
|
-
Layout prop factories receive `
|
|
245
|
+
Layout prop factories run on the server only and receive `params`, `query` and, on a dynamic Page, `locals` typed from the Page's `middleware` list. The browser renders each tier from the props the server shipped as `tiers`, and the browser build removes the factory of an entry written inline in `eco.page({ layout })`. Serialized page props never carry `locals`.
|
|
256
246
|
|
|
257
247
|
- [src/render/layout-compose.ts](src/render/layout-compose.ts): shared client/SSR tree builder.
|
|
258
248
|
- [src/test/react-ssr-hydration-parity.test.tsx](src/test/react-ssr-hydration-parity.test.tsx): nested tier order parity between SSR and `composeLayoutPageTree`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ecopages/react",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "React integration for Ecopages",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ecopages",
|
|
@@ -123,16 +123,16 @@
|
|
|
123
123
|
"directory": "packages/integrations/react"
|
|
124
124
|
},
|
|
125
125
|
"peerDependencies": {
|
|
126
|
-
"@ecopages/core": "0.
|
|
126
|
+
"@ecopages/core": "0.10.0",
|
|
127
127
|
"@types/react": "^19",
|
|
128
128
|
"@types/react-dom": "^19",
|
|
129
129
|
"react": "^19",
|
|
130
130
|
"react-dom": "^19"
|
|
131
131
|
},
|
|
132
132
|
"dependencies": {
|
|
133
|
-
"@ecopages/file-system": "0.
|
|
133
|
+
"@ecopages/file-system": "0.10.0",
|
|
134
134
|
"@ecopages/logger": "^0.2.3",
|
|
135
|
-
"@ecopages/mdx": "0.
|
|
135
|
+
"@ecopages/mdx": "0.10.0",
|
|
136
136
|
"@mdx-js/mdx": "^3.1.1",
|
|
137
137
|
"oxc-parser": "^0.141.0"
|
|
138
138
|
}
|
package/src/bundling/bundle.d.ts
CHANGED
|
@@ -31,6 +31,12 @@ export declare function getReactClientGraphAllowSpecifiers(routerAdapter?: React
|
|
|
31
31
|
export declare class BundleService {
|
|
32
32
|
private readonly config;
|
|
33
33
|
private readonly foreignJsxOverridePlugin;
|
|
34
|
+
/**
|
|
35
|
+
* @remarks
|
|
36
|
+
* One instance for every entry: its options do not depend on the entry, and core merges the entries of a
|
|
37
|
+
* build by plugin identity, so a fresh instance per entry would run its transform once per React page.
|
|
38
|
+
*/
|
|
39
|
+
private readonly foreignBoundaryPlugin;
|
|
34
40
|
private mdxLoaderPlugin;
|
|
35
41
|
constructor(config: BundleServiceConfig);
|
|
36
42
|
/**
|
package/src/bundling/bundle.js
CHANGED
|
@@ -6,7 +6,8 @@
|
|
|
6
6
|
*
|
|
7
7
|
* @module
|
|
8
8
|
*/
|
|
9
|
-
import { createClientGraphBoundaryPlugin, createForeignBoundaryPlugin, createForeignJsxScope, } from '../client-graph/boundary-plugin.js';
|
|
9
|
+
import { createClientGraphBoundaryPlugin, createForeignBoundaryPlugin, createForeignJsxScope, createReactModuleSource, } from '../client-graph/boundary-plugin.js';
|
|
10
|
+
import { createForeignModuleReader } from '../client-graph/foreign-module.js';
|
|
10
11
|
import { findIntegrationForFile, findJsxExtensionOwner, getHostScopedJsxOwnershipPlugins, isProductionRuntime, } from '@ecopages/core/build';
|
|
11
12
|
import { getReactBrowserPackages } from './bootstrap-package-paths.js';
|
|
12
13
|
/**
|
|
@@ -24,20 +25,39 @@ export function getReactClientGraphAllowSpecifiers(routerAdapter) {
|
|
|
24
25
|
export class BundleService {
|
|
25
26
|
config;
|
|
26
27
|
foreignJsxOverridePlugin;
|
|
28
|
+
/**
|
|
29
|
+
* @remarks
|
|
30
|
+
* One instance for every entry: its options do not depend on the entry, and core merges the entries of a
|
|
31
|
+
* build by plugin identity, so a fresh instance per entry would run its transform once per React page.
|
|
32
|
+
*/
|
|
33
|
+
foreignBoundaryPlugin;
|
|
27
34
|
mdxLoaderPlugin;
|
|
28
35
|
constructor(config) {
|
|
29
36
|
this.config = config;
|
|
37
|
+
const projectRoot = config.appConfig?.absolutePaths?.projectDir ?? config.rootDir;
|
|
38
|
+
const integrations = config.appConfig?.integrations ?? [];
|
|
39
|
+
const isForeignFile = (filePath) => {
|
|
40
|
+
const owner = findIntegrationForFile(integrations, filePath);
|
|
41
|
+
return owner !== undefined && owner.name !== config.hostIntegrationName;
|
|
42
|
+
};
|
|
43
|
+
const foreignModuleOf = createForeignModuleReader({
|
|
44
|
+
rootDir: config.appConfig?.rootDir ?? config.rootDir,
|
|
45
|
+
integrationOf: (filePath) => findIntegrationForFile(integrations, filePath)?.name,
|
|
46
|
+
});
|
|
47
|
+
const reactModuleSource = createReactModuleSource({ projectRoot, isForeignFile, foreignModuleOf });
|
|
30
48
|
[this.foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(config.appConfig, config.hostIntegrationName, {
|
|
31
49
|
name: 'react-renderer-foreign-jsx-override',
|
|
32
50
|
scope: createForeignJsxScope({
|
|
33
|
-
projectRoot
|
|
51
|
+
projectRoot,
|
|
34
52
|
hostIntegrationName: config.hostIntegrationName,
|
|
53
|
+
reactModuleSource,
|
|
35
54
|
findForeignOwner: (filePath) => {
|
|
36
55
|
const owner = findJsxExtensionOwner(config.appConfig, filePath);
|
|
37
56
|
return owner === config.hostIntegrationName ? undefined : owner;
|
|
38
57
|
},
|
|
39
58
|
}),
|
|
40
59
|
});
|
|
60
|
+
this.foreignBoundaryPlugin = createForeignBoundaryPlugin({ projectRoot, isForeignFile, foreignModuleOf });
|
|
41
61
|
}
|
|
42
62
|
/**
|
|
43
63
|
* Creates bundle options for a page or component entry.
|
|
@@ -80,13 +100,7 @@ export class BundleService {
|
|
|
80
100
|
return [
|
|
81
101
|
...(this.foreignJsxOverridePlugin ? [this.foreignJsxOverridePlugin] : []),
|
|
82
102
|
graphBoundaryPlugin,
|
|
83
|
-
|
|
84
|
-
projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
|
|
85
|
-
isForeignFile: (filePath) => {
|
|
86
|
-
const owner = findIntegrationForFile(this.config.appConfig?.integrations ?? [], filePath);
|
|
87
|
-
return owner !== undefined && owner.name !== this.config.hostIntegrationName;
|
|
88
|
-
},
|
|
89
|
-
}),
|
|
103
|
+
this.foreignBoundaryPlugin,
|
|
90
104
|
...(mdxPlugin ? [mdxPlugin] : []),
|
|
91
105
|
];
|
|
92
106
|
}
|
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Finds the server-only `eco.page(...)` options of browser-bound modules
|
|
2
|
+
* Finds the server-only `eco.page(...)` options of browser-bound modules, and the `props` factories of the layout
|
|
3
|
+
* entries written inline in its `layout` option.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Nodes are typed `any`, as in `walkAstNodes`: they come from the parser as untyped ESTree objects, and each helper
|
|
7
|
+
* checks `type` before reading a field.
|
|
3
8
|
*/
|
|
4
9
|
import type { SourceEdit } from './ast-transform-import-edits.js';
|
|
5
10
|
export type ServerOnlyPageCode = {
|
|
@@ -8,6 +13,14 @@ export type ServerOnlyPageCode = {
|
|
|
8
13
|
/** Nodes whose subtrees the edits remove; references inside them do not reach the browser. */
|
|
9
14
|
strippedNodes: Set<unknown>;
|
|
10
15
|
};
|
|
16
|
+
export declare function isPropertyNamed(property: any, name: string): boolean;
|
|
17
|
+
/**
|
|
18
|
+
* Returns the tiers of a `layout` option, each unwrapped from type-only wrappers: the value itself, or the elements
|
|
19
|
+
* of an array. A hole stays `null`.
|
|
20
|
+
*/
|
|
21
|
+
export declare function getLayoutTiers(layout: any): any[];
|
|
22
|
+
/** Returns the layout entries written as object literals in a `layout` option. */
|
|
23
|
+
export declare function getInlineLayoutEntries(layout: any): any[];
|
|
11
24
|
/**
|
|
12
25
|
* Collects the server-only `eco.page(...)` options of a browser-bound module and the edits that remove them.
|
|
13
26
|
*/
|
|
@@ -1,16 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Finds the server-only `eco.page(...)` options of browser-bound modules
|
|
2
|
+
* Finds the server-only `eco.page(...)` options of browser-bound modules, and the `props` factories of the layout
|
|
3
|
+
* entries written inline in its `layout` option.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Nodes are typed `any`, as in `walkAstNodes`: they come from the parser as untyped ESTree objects, and each helper
|
|
7
|
+
* checks `type` before reading a field.
|
|
3
8
|
*/
|
|
4
9
|
import { walkAstNodes } from './ast-walk.js';
|
|
5
|
-
const SERVER_ONLY_ECO_PAGE_OPTION_KEYS = new Set([
|
|
6
|
-
'cache',
|
|
7
|
-
'middleware',
|
|
8
|
-
'dependencies',
|
|
9
|
-
'requires',
|
|
10
|
-
'metadata',
|
|
11
|
-
'staticProps',
|
|
12
|
-
'staticPaths',
|
|
13
|
-
]);
|
|
10
|
+
const SERVER_ONLY_ECO_PAGE_OPTION_KEYS = new Set(['cache', 'middleware', 'dependencies', 'metadata', 'props', 'paths']);
|
|
14
11
|
function isEcoPageOptionsCall(node) {
|
|
15
12
|
return (node.type === 'CallExpression' &&
|
|
16
13
|
node.callee?.type === 'MemberExpression' &&
|
|
@@ -36,6 +33,36 @@ function isServerOnlyOption(property) {
|
|
|
36
33
|
const keyName = getObjectPropertyKeyName(property.key);
|
|
37
34
|
return keyName !== undefined && SERVER_ONLY_ECO_PAGE_OPTION_KEYS.has(keyName);
|
|
38
35
|
}
|
|
36
|
+
export function isPropertyNamed(property, name) {
|
|
37
|
+
return property?.type === 'Property' && !property.computed && getObjectPropertyKeyName(property.key) === name;
|
|
38
|
+
}
|
|
39
|
+
const TRANSPARENT_EXPRESSION_TYPES = new Set([
|
|
40
|
+
'ParenthesizedExpression',
|
|
41
|
+
'TSAsExpression',
|
|
42
|
+
'TSSatisfiesExpression',
|
|
43
|
+
'TSNonNullExpression',
|
|
44
|
+
'TSTypeAssertion',
|
|
45
|
+
]);
|
|
46
|
+
/** Returns the expression inside parentheses and type-only wrappers such as `as const` and `satisfies`. */
|
|
47
|
+
function unwrapExpression(node) {
|
|
48
|
+
let current = node;
|
|
49
|
+
while (current && TRANSPARENT_EXPRESSION_TYPES.has(current.type))
|
|
50
|
+
current = current.expression;
|
|
51
|
+
return current;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Returns the tiers of a `layout` option, each unwrapped from type-only wrappers: the value itself, or the elements
|
|
55
|
+
* of an array. A hole stays `null`.
|
|
56
|
+
*/
|
|
57
|
+
export function getLayoutTiers(layout) {
|
|
58
|
+
const value = unwrapExpression(layout);
|
|
59
|
+
const tiers = value?.type === 'ArrayExpression' ? value.elements : [value];
|
|
60
|
+
return tiers.map(unwrapExpression);
|
|
61
|
+
}
|
|
62
|
+
/** Returns the layout entries written as object literals in a `layout` option. */
|
|
63
|
+
export function getInlineLayoutEntries(layout) {
|
|
64
|
+
return getLayoutTiers(layout).filter((tier) => tier?.type === 'ObjectExpression');
|
|
65
|
+
}
|
|
39
66
|
/**
|
|
40
67
|
* Returns the range that removes one property and its separating comma.
|
|
41
68
|
*
|
|
@@ -66,11 +93,10 @@ function mergeRanges(ranges) {
|
|
|
66
93
|
}
|
|
67
94
|
return merged;
|
|
68
95
|
}
|
|
69
|
-
function
|
|
70
|
-
const objectExpression = node.arguments[0];
|
|
96
|
+
function collectPropertyEdits(objectExpression, isStripped, code) {
|
|
71
97
|
const ranges = [];
|
|
72
98
|
objectExpression.properties.forEach((property, index) => {
|
|
73
|
-
if (!
|
|
99
|
+
if (!isStripped(property))
|
|
74
100
|
return;
|
|
75
101
|
code.strippedNodes.add(property);
|
|
76
102
|
ranges.push(getPropertyRemovalRange(objectExpression, index));
|
|
@@ -78,6 +104,27 @@ function collectPageOptionEdits(node, code) {
|
|
|
78
104
|
for (const range of mergeRanges(ranges))
|
|
79
105
|
code.edits.push({ ...range, replacement: '' });
|
|
80
106
|
}
|
|
107
|
+
/**
|
|
108
|
+
* Removes the `props` factory of each layout entry written inline in the `layout` option.
|
|
109
|
+
*
|
|
110
|
+
* @remarks
|
|
111
|
+
* The factory runs only on the server: the browser renders each tier from the props the server resolved and
|
|
112
|
+
* shipped as `tiers`. An entry imported from another module cannot be edited here; its module reaches the
|
|
113
|
+
* browser whole, so a server import its factory uses fails the browser build.
|
|
114
|
+
*/
|
|
115
|
+
function collectLayoutEntryEdits(objectExpression, code) {
|
|
116
|
+
const layout = objectExpression.properties.find((property) => isPropertyNamed(property, 'layout'));
|
|
117
|
+
if (!layout)
|
|
118
|
+
return;
|
|
119
|
+
for (const entry of getInlineLayoutEntries(layout.value)) {
|
|
120
|
+
collectPropertyEdits(entry, (property) => isPropertyNamed(property, 'props'), code);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
function collectPageOptionEdits(node, code) {
|
|
124
|
+
const objectExpression = node.arguments[0];
|
|
125
|
+
collectPropertyEdits(objectExpression, isServerOnlyOption, code);
|
|
126
|
+
collectLayoutEntryEdits(objectExpression, code);
|
|
127
|
+
}
|
|
81
128
|
/**
|
|
82
129
|
* Collects the server-only `eco.page(...)` options of a browser-bound module and the edits that remove them.
|
|
83
130
|
*/
|
|
@@ -140,7 +140,7 @@ function assertNoStrippedBindingReferences(browserUnits, input) {
|
|
|
140
140
|
if (!first)
|
|
141
141
|
return;
|
|
142
142
|
const specifier = input.strippedBindings.get(first.name);
|
|
143
|
-
throw new Error(`[Ecopages Client Graph] '${first.name}' (imported from '${specifier}') is used at ${input.filename}:${toLineColumn(input.source, first.node.start)}, but that import is server-only and the browser build removes it. Use it only in server-only Page options such as middleware or
|
|
143
|
+
throw new Error(`[Ecopages Client Graph] '${first.name}' (imported from '${specifier}') is used at ${input.filename}:${toLineColumn(input.source, first.node.start)}, but that import is server-only and the browser build removes it. Use it only in server-only Page options such as middleware or props, or in code the browser module does not reach. A layout entry's props factory is server-only only when the entry is written inline in eco.page({ layout }), not when it is declared in a variable. To use server code in the browser's render path, move it into a '.server' module and call it only from those options.`);
|
|
144
144
|
}
|
|
145
145
|
/**
|
|
146
146
|
* Plans the removal of the top-level code the browser module does not need once server-only code is gone.
|
|
@@ -12,7 +12,6 @@ export type WalkImportsContext = {
|
|
|
12
12
|
reachability: ReachabilityResult;
|
|
13
13
|
edits: SourceEdit[];
|
|
14
14
|
allowedMap: Map<string, Set<string> | '*'>;
|
|
15
|
-
preserveUnreachableSideEffectImports: boolean;
|
|
16
15
|
/** Receives the local name of each removed value binding, mapped to its import specifier. */
|
|
17
16
|
strippedBindings: Map<string, string>;
|
|
18
17
|
/** Receives each import declaration that gets an edit. */
|
|
@@ -11,10 +11,11 @@ function processSpecifier(specifier, allowedMap) {
|
|
|
11
11
|
}
|
|
12
12
|
return { allowed: true, rules: explicitRules ?? '*' };
|
|
13
13
|
}
|
|
14
|
-
function pruneForbiddenSpecifier(node, ctx, specifier, message, replacement) {
|
|
14
|
+
function pruneForbiddenSpecifier(node, ctx, specifier, message, replacement, bindings = []) {
|
|
15
15
|
const reachableRules = ctx.reachability.reachableImports.get(specifier);
|
|
16
16
|
if (reachableRules && !ctx.reachability.isFallbackRoots) {
|
|
17
|
-
|
|
17
|
+
const used = bindings.length > 0 ? ` (${bindings.map((name) => `'${name}'`).join(', ')})` : '';
|
|
18
|
+
throw new Error(`[Ecopages Client Reachability] ${message} at ${ctx.filename}:${node.start}. This server-only import${used} is reachable from the React render function, which runs in the browser. Move the code that uses it into a '.server' module and call it only from server-only Page options such as props. A layout entry's props factory is server-only only when the entry is written inline in eco.page({ layout }), not when it is declared in a variable.`);
|
|
18
19
|
}
|
|
19
20
|
ctx.edits.push({ start: node.start, end: node.end, replacement });
|
|
20
21
|
}
|
|
@@ -29,10 +30,10 @@ function recordStrippedBindings(node, specifier, ctx, isKept = () => false) {
|
|
|
29
30
|
}
|
|
30
31
|
function handleImportDeclaration(node, ctx) {
|
|
31
32
|
const specifier = node.source.value;
|
|
32
|
-
const reachableRules = ctx.reachability.reachableImports.get(specifier);
|
|
33
33
|
const { allowed, rules } = processSpecifier(specifier, ctx.allowedMap);
|
|
34
34
|
if (!allowed) {
|
|
35
|
-
|
|
35
|
+
const bindings = (node.specifiers ?? []).map((specifierNode) => specifierNode.local.name);
|
|
36
|
+
pruneForbiddenSpecifier(node, ctx, specifier, `Forbidden client import '${specifier}'`, '', bindings);
|
|
36
37
|
recordStrippedBindings(node, specifier, ctx);
|
|
37
38
|
ctx.editedImports.add(node);
|
|
38
39
|
return true;
|
|
@@ -46,12 +47,6 @@ function handleImportDeclaration(node, ctx) {
|
|
|
46
47
|
}
|
|
47
48
|
return true;
|
|
48
49
|
}
|
|
49
|
-
if (!ctx.preserveUnreachableSideEffectImports &&
|
|
50
|
-
!reachableRules &&
|
|
51
|
-
(!node.specifiers || node.specifiers.length === 0)) {
|
|
52
|
-
ctx.edits.push({ start: node.start, end: node.end, replacement: '' });
|
|
53
|
-
ctx.editedImports.add(node);
|
|
54
|
-
}
|
|
55
50
|
return true;
|
|
56
51
|
}
|
|
57
52
|
function handleExportNamedDeclaration(node, ctx) {
|
|
@@ -15,7 +15,7 @@ import { type RequestedExportRules } from './specifier-classification.js';
|
|
|
15
15
|
* @param requestedExports - The exports this module's importers use; `undefined` keeps every export.
|
|
16
16
|
* @param parsed - The parse of `source`, when the caller already has it.
|
|
17
17
|
*/
|
|
18
|
-
export declare function transformModuleImports(source: string, filename: string, globallyAllowed: Map<string, Set<string> | '*'>, requestedExports: RequestedExportRules | undefined,
|
|
18
|
+
export declare function transformModuleImports(source: string, filename: string, globallyAllowed: Map<string, Set<string> | '*'>, requestedExports: RequestedExportRules | undefined, parsed?: ParseResult['program']): {
|
|
19
19
|
transformed: string;
|
|
20
20
|
modified: boolean;
|
|
21
21
|
};
|
|
@@ -34,7 +34,7 @@ function collectLocalDeclaredModules(program) {
|
|
|
34
34
|
* @param requestedExports - The exports this module's importers use; `undefined` keeps every export.
|
|
35
35
|
* @param parsed - The parse of `source`, when the caller already has it.
|
|
36
36
|
*/
|
|
37
|
-
export function transformModuleImports(source, filename, globallyAllowed, requestedExports,
|
|
37
|
+
export function transformModuleImports(source, filename, globallyAllowed, requestedExports, parsed) {
|
|
38
38
|
let program = parsed;
|
|
39
39
|
if (!program) {
|
|
40
40
|
try {
|
|
@@ -54,7 +54,6 @@ export function transformModuleImports(source, filename, globallyAllowed, reques
|
|
|
54
54
|
filename,
|
|
55
55
|
reachability,
|
|
56
56
|
allowedMap,
|
|
57
|
-
preserveUnreachableSideEffectImports,
|
|
58
57
|
strippedBindings,
|
|
59
58
|
editedImports,
|
|
60
59
|
});
|
|
@@ -9,7 +9,6 @@ export type TransformClientGraphModuleOptions = {
|
|
|
9
9
|
category: ClientGraphModuleKind;
|
|
10
10
|
globallyDeclaredSources: Map<string, Set<string> | '*'>;
|
|
11
11
|
requestedExports: RequestedExportRules | undefined;
|
|
12
|
-
preserveUnreachableSideEffectImports?: boolean;
|
|
13
12
|
};
|
|
14
13
|
/**
|
|
15
14
|
* Applies import transforms to one client-graph module whose read-file calls are already inlined.
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { path } from '@ecopages/file-system/path';
|
|
2
2
|
import { recordModuleTransformProfile } from '@ecopages/core/build';
|
|
3
3
|
import { transformModuleImports } from './ast-transform.js';
|
|
4
|
-
import { isPageOrLayoutEntry } from './module-classification.js';
|
|
5
4
|
function toLoaderResult(filePath, contents) {
|
|
6
5
|
const ext = path.extname(filePath).slice(1);
|
|
7
6
|
return { contents, loader: ext };
|
|
@@ -12,7 +11,7 @@ function toLoaderResult(filePath, contents) {
|
|
|
12
11
|
export function transformClientGraphModule(options) {
|
|
13
12
|
const { module } = options;
|
|
14
13
|
const analysisStartedAt = performance.now();
|
|
15
|
-
const { transformed, modified } = transformModuleImports(module.source, options.filePath, options.globallyDeclaredSources, options.requestedExports,
|
|
14
|
+
const { transformed, modified } = transformModuleImports(module.source, options.filePath, options.globallyDeclaredSources, options.requestedExports, module.program);
|
|
16
15
|
recordModuleTransformProfile({
|
|
17
16
|
category: options.category,
|
|
18
17
|
phase: 'analysis',
|
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* Build plugin securing the Ecopages isomorphic compilation pipeline.
|
|
5
5
|
*/
|
|
6
6
|
import type { EcoBuildPlugin, EcoBuildPluginBuilder } from '@ecopages/core/integration';
|
|
7
|
+
import { type ForeignBoundaryRewriteOptions } from './foreign-boundary-rewrite.js';
|
|
7
8
|
/**
|
|
8
9
|
* Configuration options for the Client Graph Boundary build plugin.
|
|
9
10
|
*/
|
|
@@ -16,6 +17,20 @@ type ClientGraphBoundaryOptions = {
|
|
|
16
17
|
declaredModules?: readonly string[];
|
|
17
18
|
alwaysAllowSpecifiers?: string[];
|
|
18
19
|
};
|
|
20
|
+
/** The source of a module as React's graph compiles it, or `undefined` when React keeps it as it is. */
|
|
21
|
+
export type ReactModuleSource = (filePath: string, source: string) => string | undefined;
|
|
22
|
+
/**
|
|
23
|
+
* The foreign boundary rewrite as the reach scans apply it: to React's own modules, with the identity stubs.
|
|
24
|
+
*
|
|
25
|
+
* @remarks
|
|
26
|
+
* Without `foreignModuleOf` the rewrite only wraps bindings and keeps every import, so the scans read the
|
|
27
|
+
* original source.
|
|
28
|
+
*/
|
|
29
|
+
export declare function createReactModuleSource(options: {
|
|
30
|
+
projectRoot: string;
|
|
31
|
+
isForeignFile: (filePath: string) => boolean;
|
|
32
|
+
foreignModuleOf?: ForeignBoundaryRewriteOptions['foreignModuleOf'];
|
|
33
|
+
}): ReactModuleSource | undefined;
|
|
19
34
|
/**
|
|
20
35
|
* Scope for React's foreign-JSX override: a file another JSX Integration owns gets React's JSX runtime only when
|
|
21
36
|
* a React entry file reaches it.
|
|
@@ -31,6 +46,8 @@ export declare function createForeignJsxScope(options: {
|
|
|
31
46
|
hostIntegrationName: string;
|
|
32
47
|
/** Name of the other JSX Integration that owns `filePath`; `undefined` when the file is not foreign. */
|
|
33
48
|
findForeignOwner: (filePath: string) => string | undefined;
|
|
49
|
+
/** How React's graph compiles a module, so the reach scan sees the imports React keeps. */
|
|
50
|
+
reactModuleSource?: ReactModuleSource;
|
|
34
51
|
}): (build: EcoBuildPluginBuilder) => (sourcePath: string) => boolean;
|
|
35
52
|
/**
|
|
36
53
|
* Instantiates the client graph boundary build plugin.
|
|
@@ -65,5 +82,7 @@ export declare function createForeignBoundaryPlugin(options: {
|
|
|
65
82
|
isForeignFile: (filePath: string) => boolean;
|
|
66
83
|
/** Whether another module graph uses `filePath`, in a build whose entries cannot say. */
|
|
67
84
|
isSharedFile?: (filePath: string) => boolean;
|
|
85
|
+
/** See {@link ForeignBoundaryRewriteOptions.foreignModuleOf}. */
|
|
86
|
+
foreignModuleOf?: ForeignBoundaryRewriteOptions['foreignModuleOf'];
|
|
68
87
|
}): EcoBuildPlugin;
|
|
69
88
|
export {};
|