@ecopages/react 0.2.0-beta.28 → 0.2.0-beta.29

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecopages/react",
3
- "version": "0.2.0-beta.28",
3
+ "version": "0.2.0-beta.29",
4
4
  "description": "React integration for Ecopages",
5
5
  "keywords": [
6
6
  "ecopages",
@@ -93,16 +93,16 @@
93
93
  "directory": "packages/integrations/react"
94
94
  },
95
95
  "peerDependencies": {
96
- "@ecopages/core": "0.2.0-beta.28",
96
+ "@ecopages/core": "0.2.0-beta.29",
97
97
  "@types/react": "^19",
98
98
  "@types/react-dom": "^19",
99
99
  "react": "^19",
100
100
  "react-dom": "^19"
101
101
  },
102
102
  "dependencies": {
103
- "@ecopages/file-system": "0.2.0-beta.28",
103
+ "@ecopages/file-system": "0.2.0-beta.29",
104
104
  "@ecopages/logger": "^0.2.3",
105
- "@ecopages/mdx": "0.2.0-beta.28",
105
+ "@ecopages/mdx": "0.2.0-beta.29",
106
106
  "@mdx-js/mdx": "^3.1.1",
107
107
  "oxc-parser": "^0.124.0",
108
108
  "oxc-transform": "^0.124.0",
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Bare package specifiers for React page hydration bootstrap helpers.
3
+ */
4
+ export declare const PAGE_LAYOUT_NORMALIZATION_PACKAGE = "@ecopages/core/eco/page-layout-normalization";
5
+ export declare const LAYOUT_COMPOSE_PACKAGE = "@ecopages/react/layout-compose";
@@ -0,0 +1,6 @@
1
+ const PAGE_LAYOUT_NORMALIZATION_PACKAGE = "@ecopages/core/eco/page-layout-normalization";
2
+ const LAYOUT_COMPOSE_PACKAGE = "@ecopages/react/layout-compose";
3
+ export {
4
+ LAYOUT_COMPOSE_PACKAGE,
5
+ PAGE_LAYOUT_NORMALIZATION_PACKAGE
6
+ };
@@ -18,6 +18,8 @@ export type ReactRuntimeImports = {
18
18
  reactJsxDevRuntime: string;
19
19
  reactDom: string;
20
20
  useSyncExternalStoreWithSelector: string;
21
+ pageLayoutNormalization: string;
22
+ layoutCompose: string;
21
23
  router?: string;
22
24
  };
23
25
  export interface RuntimeBundleServiceConfig {
@@ -44,6 +46,8 @@ export declare class RuntimeBundleService {
44
46
  getConfiguredRuntimeModuleSpecifiers(): string[];
45
47
  private getRuntimeModuleBundleExternals;
46
48
  private getUseSyncExternalStoreWithSelectorVendorFileName;
49
+ private getPageLayoutNormalizationVendorFileName;
50
+ private getLayoutComposeVendorFileName;
47
51
  private createReactVendorImportRewritePlugin;
48
52
  getRuntimeImports(mode?: RuntimeMode): ReactRuntimeImports;
49
53
  getRuntimeAliasMap(mode?: RuntimeMode): Record<string, string>;
@@ -14,6 +14,7 @@ import {
14
14
  import {
15
15
  createBrowserRuntimeManifest
16
16
  } from "@ecopages/core/build/browser-runtime-manifest";
17
+ import { LAYOUT_COMPOSE_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE } from "./bootstrap-package-paths.js";
17
18
  class RuntimeBundleService {
18
19
  config;
19
20
  constructor(config) {
@@ -73,6 +74,12 @@ class RuntimeBundleService {
73
74
  getUseSyncExternalStoreWithSelectorVendorFileName(mode) {
74
75
  return mode === "development" ? "use-sync-external-store-with-selector.development.js" : "use-sync-external-store-with-selector.js";
75
76
  }
77
+ getPageLayoutNormalizationVendorFileName(mode) {
78
+ return mode === "development" ? "page-layout-normalization.development.js" : "page-layout-normalization.js";
79
+ }
80
+ getLayoutComposeVendorFileName(mode) {
81
+ return mode === "development" ? "layout-compose.development.js" : "layout-compose.js";
82
+ }
76
83
  createReactVendorImportRewritePlugin(mode) {
77
84
  return createBrowserRuntimePlugin({
78
85
  name: `react-plugin-vendor-runtime-import-rewrite-${mode}`,
@@ -97,7 +104,9 @@ class RuntimeBundleService {
97
104
  reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
98
105
  useSyncExternalStoreWithSelector: buildBrowserRuntimeAssetUrl(
99
106
  this.getUseSyncExternalStoreWithSelectorVendorFileName(mode)
100
- )
107
+ ),
108
+ pageLayoutNormalization: buildBrowserRuntimeAssetUrl(this.getPageLayoutNormalizationVendorFileName(mode)),
109
+ layoutCompose: buildBrowserRuntimeAssetUrl(this.getLayoutComposeVendorFileName(mode))
101
110
  };
102
111
  if (this.config.routerAdapter) {
103
112
  runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getRouterVendorFileName(mode));
@@ -177,6 +186,25 @@ class RuntimeBundleService {
177
186
  excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
178
187
  plugins: [reactVendorImportRewritePlugin]
179
188
  }
189
+ }),
190
+ createBrowserRuntimeScriptAsset({
191
+ importPath: PAGE_LAYOUT_NORMALIZATION_PACKAGE,
192
+ name: "page-layout-normalization",
193
+ fileName: this.getPageLayoutNormalizationVendorFileName(mode),
194
+ bundleOptions: {
195
+ define: this.createRuntimeDefines(mode),
196
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME]
197
+ }
198
+ }),
199
+ createBrowserRuntimeScriptAsset({
200
+ importPath: LAYOUT_COMPOSE_PACKAGE,
201
+ name: "layout-compose",
202
+ fileName: this.getLayoutComposeVendorFileName(mode),
203
+ bundleOptions: {
204
+ define: this.createRuntimeDefines(mode),
205
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
206
+ plugins: [reactVendorImportRewritePlugin]
207
+ }
180
208
  })
181
209
  );
182
210
  if (this.config.routerAdapter) {
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Test helper: assert generated hydration bootstrap source has no bare `@ecopages/*` imports.
3
+ */
4
+ export declare function assertNoBareEcopagesImports(source: string): void;
@@ -0,0 +1,7 @@
1
+ import { expect } from "vitest";
2
+ function assertNoBareEcopagesImports(source) {
3
+ expect(source).not.toMatch(/from\s+["']@ecopages\//);
4
+ }
5
+ export {
6
+ assertNoBareEcopagesImports
7
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Resolves browser import paths for React page hydration bootstraps.
3
+ *
4
+ * @remarks
5
+ * When `useBrowserRuntimeImports` is true, helpers and runtimes resolve to shared
6
+ * `/assets/vendors/*.js` URLs so unbundled HMR bootstraps evaluate as native ESM.
7
+ * When false, bare package names are emitted for the production page bundler.
8
+ */
9
+ import type { ReactRuntimeImports } from '../bundling/runtime-bundle.js';
10
+ export type HydrationBootstrapImportPaths = {
11
+ reactImportPath: string;
12
+ reactDomClientImportPath: string;
13
+ routerImportPath?: string;
14
+ layoutComposeImportPath: string;
15
+ pageLayoutNormalizationImportPath: string;
16
+ };
17
+ export type ResolveHydrationBootstrapImportsOptions = {
18
+ useBrowserRuntimeImports: boolean;
19
+ runtimeImports: ReactRuntimeImports;
20
+ routerAdapterImportPath?: string;
21
+ };
22
+ /**
23
+ * Returns import paths for React page hydration scripts.
24
+ */
25
+ export declare function resolveHydrationBootstrapImports(options: ResolveHydrationBootstrapImportsOptions): HydrationBootstrapImportPaths;
@@ -0,0 +1,23 @@
1
+ import { LAYOUT_COMPOSE_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE } from "../bundling/bootstrap-package-paths.js";
2
+ function resolveHydrationBootstrapImports(options) {
3
+ const { useBrowserRuntimeImports, runtimeImports, routerAdapterImportPath } = options;
4
+ if (useBrowserRuntimeImports) {
5
+ return {
6
+ reactImportPath: runtimeImports.react,
7
+ reactDomClientImportPath: runtimeImports.reactDomClient,
8
+ ...runtimeImports.router || routerAdapterImportPath ? { routerImportPath: runtimeImports.router ?? routerAdapterImportPath } : {},
9
+ layoutComposeImportPath: runtimeImports.layoutCompose,
10
+ pageLayoutNormalizationImportPath: runtimeImports.pageLayoutNormalization
11
+ };
12
+ }
13
+ return {
14
+ reactImportPath: "react",
15
+ reactDomClientImportPath: "react-dom/client",
16
+ ...routerAdapterImportPath ? { routerImportPath: routerAdapterImportPath } : {},
17
+ layoutComposeImportPath: LAYOUT_COMPOSE_PACKAGE,
18
+ pageLayoutNormalizationImportPath: PAGE_LAYOUT_NORMALIZATION_PACKAGE
19
+ };
20
+ }
21
+ export {
22
+ resolveHydrationBootstrapImports
23
+ };
@@ -6,6 +6,7 @@ import {
6
6
  AssetFactory
7
7
  } from "@ecopages/core/services/asset-processing-service";
8
8
  import { createHydrationScript, createIslandHydrationScript } from "./hydration-scripts.js";
9
+ import { resolveHydrationBootstrapImports } from "./bootstrap-imports.js";
9
10
  import { collectDeclaredModulesInConfig } from "../client-graph/declared-modules.js";
10
11
  function getIslandComponentKey(componentFile, config) {
11
12
  return rapidhash(`${componentFile}:${config?.__eco?.id ?? ""}`).toString();
@@ -60,20 +61,22 @@ class HydrationAssetService {
60
61
  id: HydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
61
62
  entryName: this.getRouterPageGroupedEntryName(pagePath)
62
63
  } : void 0;
63
- const existingExternal = Array.isArray(bundleOptions.external) ? bundleOptions.external.filter((value) => typeof value === "string") : [];
64
- const pageBootstrapBundleOptions = hmrEnabled ? {
65
- ...bundleOptions,
66
- external: [.../* @__PURE__ */ new Set([...existingExternal, importPath])]
67
- } : bundleOptions;
64
+ const bootstrapImports = resolveHydrationBootstrapImports({
65
+ useBrowserRuntimeImports,
66
+ runtimeImports,
67
+ routerAdapterImportPath: this.config.routerAdapter?.bundle.importPath
68
+ });
68
69
  return [
69
70
  AssetFactory.createContentScript({
70
71
  position: "head",
71
72
  content: createHydrationScript({
72
73
  importPath: hmrEnabled ? importPath : pagePath,
73
74
  pageModuleUrlExpression,
74
- reactImportPath: useBrowserRuntimeImports ? runtimeImports.react : "react",
75
- reactDomClientImportPath: useBrowserRuntimeImports ? runtimeImports.reactDomClient : "react-dom/client",
76
- routerImportPath: useBrowserRuntimeImports ? runtimeImports.router : this.config.routerAdapter?.bundle.importPath,
75
+ reactImportPath: bootstrapImports.reactImportPath,
76
+ reactDomClientImportPath: bootstrapImports.reactDomClientImportPath,
77
+ routerImportPath: bootstrapImports.routerImportPath,
78
+ layoutComposeImportPath: bootstrapImports.layoutComposeImportPath,
79
+ pageLayoutNormalizationImportPath: bootstrapImports.pageLayoutNormalizationImportPath,
77
80
  hmrEnabled,
78
81
  isMdx,
79
82
  router: this.config.routerAdapter,
@@ -83,14 +86,13 @@ class HydrationAssetService {
83
86
  packageRole: "page-script",
84
87
  /**
85
88
  * @remarks
86
- * Always bundle page bootstraps. Unbundled HMR entries are evaluated as
87
- * native browser ESM and cannot resolve bare package imports such as
88
- * `@ecopages/core/eco/page-layout-normalization` or
89
- * `@ecopages/react/layout-compose`.
89
+ * HMR bootstraps stay unbundled write-through ESM. Helper imports must
90
+ * already be browser-resolvable vendor URLs from
91
+ * {@link resolveHydrationBootstrapImports}.
90
92
  */
91
- bundle: true,
93
+ bundle: !hmrEnabled,
92
94
  groupedBundle,
93
- bundleOptions: pageBootstrapBundleOptions,
95
+ bundleOptions,
94
96
  attributes: {
95
97
  type: "module",
96
98
  defer: "",
@@ -24,17 +24,30 @@ export type HydrationScriptOptions = {
24
24
  * When true, emit HMR registration and hot-reload handlers.
25
25
  *
26
26
  * @remarks
27
- * Page bootstraps are always bundled so bare package imports resolve through
28
- * the browser build pipeline. When false, this generator emits the same
29
- * readable bootstrap without HMR hooks.
27
+ * HMR page bootstraps stay unbundled and evaluate as native browser ESM.
28
+ * Callers must supply browser-resolvable import paths (shared vendor URLs)
29
+ * so generated source does not emit bare `@ecopages/*` imports. When false,
30
+ * this generator emits the same readable bootstrap without HMR hooks.
30
31
  */
31
32
  hmrEnabled: boolean;
32
33
  /** Whether the source file is an MDX file */
33
34
  isMdx: boolean;
34
35
  /** Optional router adapter for SPA navigation */
35
36
  router?: ReactRouterAdapter;
36
- /** Import path for shared layout composition helper */
37
- layoutComposeImportPath?: string;
37
+ /**
38
+ * Import path for shared layout composition helper.
39
+ *
40
+ * @remarks
41
+ * Required so callers (not this generator) decide vendor URL vs bare package.
42
+ */
43
+ layoutComposeImportPath: string;
44
+ /**
45
+ * Import path for MDX page layout normalization helper.
46
+ *
47
+ * @remarks
48
+ * Required so callers (not this generator) decide vendor URL vs bare package.
49
+ */
50
+ pageLayoutNormalizationImportPath: string;
38
51
  /**
39
52
  * Optional import path for the page-data reader.
40
53
  *
@@ -1,18 +1,13 @@
1
1
  import { getDevPageDataReaderBootstrapSource } from "./page-data-reader.js";
2
- const DEFAULT_LAYOUT_COMPOSE_IMPORT_PATH = "@ecopages/react/layout-compose";
3
- const PAGE_LAYOUT_NORMALIZATION_IMPORT = "@ecopages/core/eco/page-layout-normalization";
4
2
  function getPageDataReaderSource(options) {
5
3
  if (options.pageDataReaderImportPath) {
6
4
  return `import { readPageDataDocument, getPageDataFromDocument as getPageData } from "${options.pageDataReaderImportPath}";`;
7
5
  }
8
6
  return getDevPageDataReaderBootstrapSource();
9
7
  }
10
- function resolveLayoutComposeImportPath(options) {
11
- return options.layoutComposeImportPath ?? DEFAULT_LAYOUT_COMPOSE_IMPORT_PATH;
12
- }
13
- function getImportStatement(importPath, isMdx) {
8
+ function getImportStatement(importPath, isMdx, pageLayoutNormalizationImportPath) {
14
9
  return isMdx ? `import * as MDXModule from "${importPath}";
15
- import { ensurePageConfigLayouts } from "${PAGE_LAYOUT_NORMALIZATION_IMPORT}";
10
+ import { ensurePageConfigLayouts } from "${pageLayoutNormalizationImportPath}";
16
11
  const Page = MDXModule.default;
17
12
  if (MDXModule.config) {
18
13
  Page.config = MDXModule.config;
@@ -137,6 +132,7 @@ function createScriptWithRouter(options) {
137
132
  if (!routerImportPath) {
138
133
  throw new Error("routerImportPath is required when router adapter is configured");
139
134
  }
135
+ const pageLayoutNormalizationImportPath = options.pageLayoutNormalizationImportPath;
140
136
  const hmrInit = hmrEnabled ? `window.__ECO_PAGES__.hmrHandlers = window.__ECO_PAGES__.hmrHandlers || {};
141
137
  ` : "";
142
138
  const hmrHandler = hmrEnabled ? getRouterHmrHandlerScript({ importPath, isMdx }) : "";
@@ -145,7 +141,7 @@ import { hydrateRoot } from "${reactDomClientImportPath}";
145
141
  import { createElement } from "${reactImportPath}";
146
142
  import { ${components.router}, ${components.pageContent} } from "${routerImportPath}";
147
143
  ${getPageDataReaderSource(options)}
148
- ${getImportStatement(importPath, isMdx)}
144
+ ${getImportStatement(importPath, isMdx, pageLayoutNormalizationImportPath)}
149
145
  const pageModuleUrl = ${pageModuleUrlExpression};
150
146
  export default Page;
151
147
  export const config = Page.config;
@@ -212,7 +208,8 @@ if (document.readyState === "loading") {
212
208
  function createScriptWithoutRouter(options) {
213
209
  const { importPath, isMdx, reactImportPath, reactDomClientImportPath, scriptId, hmrEnabled } = options;
214
210
  const pageModuleUrlExpression = options.pageModuleUrlExpression ?? "import.meta.url";
215
- const layoutComposeImportPath = resolveLayoutComposeImportPath(options);
211
+ const layoutComposeImportPath = options.layoutComposeImportPath;
212
+ const pageLayoutNormalizationImportPath = options.pageLayoutNormalizationImportPath;
216
213
  const hmrInit = hmrEnabled ? `window.__ECO_PAGES__.hmrHandlers = window.__ECO_PAGES__.hmrHandlers || {};
217
214
  ` : "";
218
215
  const hmrHandler = hmrEnabled ? getNonRouterHmrHandlerScript({ importPath, isMdx }) : "";
@@ -221,7 +218,7 @@ import { hydrateRoot } from "${reactDomClientImportPath}";
221
218
  import { createElement } from "${reactImportPath}";
222
219
  import { composeLayoutPageTree } from "${layoutComposeImportPath}";
223
220
  ${getPageDataReaderSource(options)}
224
- ${getImportStatement(importPath, isMdx)}
221
+ ${getImportStatement(importPath, isMdx, pageLayoutNormalizationImportPath)}
225
222
  const pageModuleUrl = ${pageModuleUrlExpression};
226
223
  export default Page;
227
224
  export const config = Page.config;
@@ -62,7 +62,11 @@ export function PageContent() {
62
62
  importPath,
63
63
  reactImportPath,
64
64
  reactDomClientImportPath,
65
- routerImportPath
65
+ routerImportPath,
66
+ layoutComposeImportPath: createModuleUrl("export function composeLayoutPageTree() { return null; }"),
67
+ pageLayoutNormalizationImportPath: createModuleUrl(
68
+ "export function ensurePageConfigLayouts(config) { return config; }"
69
+ )
66
70
  };
67
71
  }
68
72
  describe("createHydrationScript browser execution", () => {