@ecopages/react 0.2.0-beta.31 → 0.2.0-beta.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +5 -1
  2. package/package.json +4 -4
  3. package/src/app/client-only.js +13 -17
  4. package/src/app/dynamic.js +7 -10
  5. package/src/app/dynamic.test.browser.js +27 -29
  6. package/src/bundling/bootstrap-package-paths.js +5 -6
  7. package/src/bundling/bundle.js +115 -114
  8. package/src/bundling/discover-layout-runtime-modules.js +166 -155
  9. package/src/bundling/runtime-alias-map.d.ts +4 -1
  10. package/src/bundling/runtime-alias-map.js +107 -95
  11. package/src/bundling/runtime-bundle.js +250 -274
  12. package/src/bundling/runtime-interop-plugin.js +31 -35
  13. package/src/bundling/runtime-mode.js +10 -5
  14. package/src/bundling/runtime-modules.js +46 -35
  15. package/src/client-graph/ast-transform.js +415 -305
  16. package/src/client-graph/boundary-cache.js +146 -104
  17. package/src/client-graph/boundary-plugin.js +122 -104
  18. package/src/client-graph/component-config-traversal.js +70 -49
  19. package/src/client-graph/declared-modules.js +63 -41
  20. package/src/client-graph/reachability-analyzer.js +506 -313
  21. package/src/client-graph/specifier-classification.js +209 -141
  22. package/src/contracts/router-adapter.js +6 -0
  23. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  24. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  25. package/src/hmr/hmr-scripts.js +22 -9
  26. package/src/hmr/hmr-strategy.d.ts +12 -181
  27. package/src/hmr/hmr-strategy.js +321 -650
  28. package/src/hmr/page-metadata-cache.js +43 -40
  29. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  30. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  31. package/src/hydration/assert-no-bare-ecopages-imports.js +6 -6
  32. package/src/hydration/bootstrap-imports.js +30 -20
  33. package/src/hydration/hydration-asset.js +216 -213
  34. package/src/hydration/hydration-scripts.d.ts +4 -0
  35. package/src/hydration/hydration-scripts.js +199 -66
  36. package/src/hydration/hydration-scripts.test.browser.js +163 -168
  37. package/src/hydration/page-data-manifest.js +89 -45
  38. package/src/hydration/page-data-reader.js +45 -32
  39. package/src/hydration/page-payload.js +101 -99
  40. package/src/hydration/serialize-page-data-script.js +27 -28
  41. package/src/mdx/mdx-config-dependency.js +108 -112
  42. package/src/mdx/mdx-loader-plugin.js +7 -10
  43. package/src/page/page-module.js +72 -66
  44. package/src/plugin/react.constants.js +1 -4
  45. package/src/plugin/react.plugin.d.ts +1 -0
  46. package/src/plugin/react.plugin.js +227 -216
  47. package/src/plugin/react.types.js +1 -0
  48. package/src/render/component-ownership.js +42 -18
  49. package/src/render/component-ssr.js +168 -190
  50. package/src/render/eco-embed.js +8 -10
  51. package/src/render/errors.js +21 -16
  52. package/src/render/html-boundary.js +55 -51
  53. package/src/render/layout-compose.js +122 -94
  54. package/src/render/react-renderer.js +433 -468
  55. package/src/render/react-runtime.js +25 -20
  56. package/src/render/unified-layout-composition.js +74 -85
  57. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
@@ -1,41 +1,44 @@
1
- import path from "node:path";
2
- class HmrPageMetadataCache {
3
- declaredModulesByEntrypoint = /* @__PURE__ */ new Map();
4
- ownedEntrypoints = /* @__PURE__ */ new Set();
5
- /**
6
- * Marks an HMR entrypoint as React-owned.
7
- */
8
- markOwnedEntrypoint(entrypointPath) {
9
- this.ownedEntrypoints.add(path.resolve(entrypointPath));
10
- }
11
- /**
12
- * Stores the declared browser modules for a page entrypoint.
13
- */
14
- setDeclaredModules(entrypointPath, declaredModules) {
15
- const resolvedEntrypointPath = path.resolve(entrypointPath);
16
- this.markOwnedEntrypoint(resolvedEntrypointPath);
17
- this.declaredModulesByEntrypoint.set(resolvedEntrypointPath, [...declaredModules]);
18
- }
19
- /**
20
- * Returns the last known declared browser modules for a page entrypoint.
21
- */
22
- getDeclaredModules(entrypointPath) {
23
- const declaredModules = this.declaredModulesByEntrypoint.get(path.resolve(entrypointPath));
24
- return declaredModules ? [...declaredModules] : void 0;
25
- }
26
- /**
27
- * Returns React-owned page entrypoints discovered during development renders.
28
- */
29
- getOwnedEntrypoints() {
30
- return [...this.ownedEntrypoints].sort((left, right) => left.localeCompare(right));
31
- }
32
- /**
33
- * Returns true when the watched entrypoint is owned by the React integration.
34
- */
35
- ownsEntrypoint(entrypointPath) {
36
- return this.ownedEntrypoints.has(path.resolve(entrypointPath));
37
- }
1
+ import path from 'node:path';
2
+ /**
3
+ * React-only cache for page metadata that HMR rebuilds need during development.
4
+ *
5
+ * This keeps React Fast Refresh optimizations local to the React integration so
6
+ * core HMR interfaces do not need React-specific metadata hooks.
7
+ */
8
+ export class HmrPageMetadataCache {
9
+ declaredModulesByEntrypoint = new Map();
10
+ ownedEntrypoints = new Set();
11
+ /**
12
+ * Marks an HMR entrypoint as React-owned.
13
+ */
14
+ markOwnedEntrypoint(entrypointPath) {
15
+ this.ownedEntrypoints.add(path.resolve(entrypointPath));
16
+ }
17
+ /**
18
+ * Stores the declared browser modules for a page entrypoint.
19
+ */
20
+ setDeclaredModules(entrypointPath, declaredModules) {
21
+ const resolvedEntrypointPath = path.resolve(entrypointPath);
22
+ this.markOwnedEntrypoint(resolvedEntrypointPath);
23
+ this.declaredModulesByEntrypoint.set(resolvedEntrypointPath, [...declaredModules]);
24
+ }
25
+ /**
26
+ * Returns the last known declared browser modules for a page entrypoint.
27
+ */
28
+ getDeclaredModules(entrypointPath) {
29
+ const declaredModules = this.declaredModulesByEntrypoint.get(path.resolve(entrypointPath));
30
+ return declaredModules ? [...declaredModules] : undefined;
31
+ }
32
+ /**
33
+ * Returns React-owned page entrypoints discovered during development renders.
34
+ */
35
+ getOwnedEntrypoints() {
36
+ return [...this.ownedEntrypoints].sort((left, right) => left.localeCompare(right));
37
+ }
38
+ /**
39
+ * Returns true when the watched entrypoint is owned by the React integration.
40
+ */
41
+ ownsEntrypoint(entrypointPath) {
42
+ return this.ownedEntrypoints.has(path.resolve(entrypointPath));
43
+ }
38
44
  }
39
- export {
40
- HmrPageMetadataCache
41
- };
@@ -0,0 +1,23 @@
1
+ import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
2
+ import type { EcoComponentConfig } from '@ecopages/core';
3
+ import type { CompileOptions } from '@mdx-js/mdx';
4
+ import type { HmrPageMetadataCache } from './page-metadata-cache.js';
5
+ export type ReactHmrBuildTarget = {
6
+ entrypointPath: string;
7
+ outputUrl: string;
8
+ };
9
+ type ImportedReactPageModule = {
10
+ default?: {
11
+ config?: EcoComponentConfig;
12
+ };
13
+ config?: EcoComponentConfig;
14
+ };
15
+ export type ReactHmrDevTransformPluginOptions = {
16
+ pageMetadataCache: HmrPageMetadataCache;
17
+ mdxCompilerOptions?: CompileOptions;
18
+ getBuildPlugins: (declaredModules?: readonly string[]) => EcoBuildPlugin[];
19
+ importNodePageModule: (entrypointPath: string) => Promise<ImportedReactPageModule>;
20
+ };
21
+ export declare function resolveReactDeclaredModulesForEntrypoint(options: ReactHmrDevTransformPluginOptions, entrypointPath: string): Promise<readonly string[]>;
22
+ export declare function buildReactDevTransformPlugins(options: ReactHmrDevTransformPluginOptions, declaredModules: readonly string[], shouldEnableMdx: boolean): EcoBuildPlugin[];
23
+ export {};
@@ -0,0 +1,20 @@
1
+ import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from '../client-graph/declared-modules.js';
2
+ import { createReactMdxLoaderPlugin } from '../mdx/mdx-loader-plugin.js';
3
+ export async function resolveReactDeclaredModulesForEntrypoint(options, entrypointPath) {
4
+ const cached = options.pageMetadataCache.getDeclaredModules(entrypointPath);
5
+ if (cached) {
6
+ return cached;
7
+ }
8
+ const declaredModules = entrypointPath.endsWith('.mdx')
9
+ ? await collectPageDeclaredModules(entrypointPath)
10
+ : collectPageDeclaredModulesFromModule(await options.importNodePageModule(entrypointPath));
11
+ options.pageMetadataCache.setDeclaredModules(entrypointPath, declaredModules);
12
+ return declaredModules;
13
+ }
14
+ export function buildReactDevTransformPlugins(options, declaredModules, shouldEnableMdx) {
15
+ const plugins = options.getBuildPlugins(declaredModules);
16
+ if (shouldEnableMdx && options.mdxCompilerOptions) {
17
+ plugins.unshift(createReactMdxLoaderPlugin(options.mdxCompilerOptions));
18
+ }
19
+ return plugins;
20
+ }
@@ -1,7 +1,7 @@
1
- import { expect } from "vitest";
2
- function assertNoBareEcopagesImports(source) {
3
- expect(source).not.toMatch(/from\s+["']@ecopages\//);
1
+ import { expect } from 'vitest';
2
+ /**
3
+ * Test helper: assert generated hydration bootstrap source has no bare `@ecopages/*` imports.
4
+ */
5
+ export function assertNoBareEcopagesImports(source) {
6
+ expect(source).not.toMatch(/from\s+["']@ecopages\//);
4
7
  }
5
- export {
6
- assertNoBareEcopagesImports
7
- };
@@ -1,23 +1,33 @@
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) {
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 { LAYOUT_COMPOSE_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE } from '../bundling/bootstrap-package-paths.js';
10
+ /**
11
+ * Returns import paths for React page hydration scripts.
12
+ */
13
+ export function resolveHydrationBootstrapImports(options) {
14
+ const { useBrowserRuntimeImports, runtimeImports, routerAdapterImportPath } = options;
15
+ if (useBrowserRuntimeImports) {
16
+ return {
17
+ reactImportPath: runtimeImports.react,
18
+ reactDomClientImportPath: runtimeImports.reactDomClient,
19
+ ...(runtimeImports.router || routerAdapterImportPath
20
+ ? { routerImportPath: runtimeImports.router ?? routerAdapterImportPath }
21
+ : {}),
22
+ layoutComposeImportPath: runtimeImports.layoutCompose,
23
+ pageLayoutNormalizationImportPath: runtimeImports.pageLayoutNormalization,
24
+ };
25
+ }
5
26
  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
27
+ reactImportPath: 'react',
28
+ reactDomClientImportPath: 'react-dom/client',
29
+ ...(routerAdapterImportPath ? { routerImportPath: routerAdapterImportPath } : {}),
30
+ layoutComposeImportPath: LAYOUT_COMPOSE_PACKAGE,
31
+ pageLayoutNormalizationImportPath: PAGE_LAYOUT_NORMALIZATION_PACKAGE,
11
32
  };
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
33
  }
21
- export {
22
- resolveHydrationBootstrapImports
23
- };
@@ -1,224 +1,227 @@
1
- import path from "node:path";
2
- import { rapidhash } from "@ecopages/core/hash";
3
- import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
4
- import { isReactProductionRuntime } from "../bundling/runtime-mode.js";
5
- import {
6
- AssetFactory
7
- } from "@ecopages/core/services/asset-processing-service";
8
- import { createHydrationScript, createIslandHydrationScript } from "./hydration-scripts.js";
9
- import { resolveHydrationBootstrapImports } from "./bootstrap-imports.js";
10
- import { collectDeclaredModulesInConfig } from "../client-graph/declared-modules.js";
11
- function getIslandComponentKey(componentFile, config) {
12
- return rapidhash(`${componentFile}:${config?.__eco?.id ?? ""}`).toString();
1
+ /**
2
+ * Hydration asset creation service for React integration.
3
+ *
4
+ * Builds the asset definitions required for client-side React rendering — both at
5
+ * the page level and the component island level.
6
+ *
7
+ * @module
8
+ */
9
+ import path from 'node:path';
10
+ import { rapidhash } from '@ecopages/core/hash';
11
+ import { RESOLVED_ASSETS_DIR } from '@ecopages/core/constants';
12
+ import { isReactProductionRuntime } from '../bundling/runtime-mode.js';
13
+ import { AssetFactory, } from '@ecopages/core/services/asset-processing-service';
14
+ import { createHydrationScript, createIslandHydrationScript } from './hydration-scripts.js';
15
+ import { resolveHydrationBootstrapImports } from './bootstrap-imports.js';
16
+ import { collectDeclaredModulesInConfig } from '../client-graph/declared-modules.js';
17
+ export function getIslandComponentKey(componentFile, config) {
18
+ return rapidhash(`${componentFile}:${config?.__eco?.id ?? ''}`).toString();
13
19
  }
14
- class HydrationAssetService {
15
- config;
16
- static ROUTER_PAGE_GROUPED_BUNDLE_ID = "ecopages-react-router-pages";
17
- constructor(config) {
18
- this.config = config;
19
- }
20
- getIslandBundleName(componentFile) {
21
- return `ecopages-react-island-${rapidhash(componentFile)}`;
22
- }
23
- getIslandHydrationName(bundleName, componentKey) {
24
- return `${bundleName}-hydration-${componentKey}`;
25
- }
26
- getRouterPageGroupedEntryName(pagePath) {
27
- const relativePath = path.relative(this.config.srcDir, pagePath);
28
- return relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, "").replace(/[\\/]+/g, "__").replace(/\[([^\]]+)\]/g, "_$1_");
29
- }
30
- /**
31
- * Resolves the browser import path used for a React-owned page or island module.
32
- *
33
- * @remarks
34
- * When HMR is enabled, registers the source file as an HMR entrypoint and returns
35
- * that URL. Otherwise returns the static resolved-assets path for the generated
36
- * asset name.
37
- */
38
- async resolveAssetImportPath(pagePath, assetName) {
39
- const hmrManager = this.config.assetProcessingService?.getHmrManager();
40
- if (hmrManager?.isEnabled()) {
41
- return hmrManager.registerEntrypoint(pagePath);
20
+ /**
21
+ * Manages the creation of client-side hydration assets for React pages and component islands.
22
+ */
23
+ export class HydrationAssetService {
24
+ config;
25
+ static ROUTER_PAGE_GROUPED_BUNDLE_ID = 'ecopages-react-router-pages';
26
+ constructor(config) {
27
+ this.config = config;
42
28
  }
43
- return `/${path.join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath)).replace(path.basename(pagePath), `${assetName}.js`).replace(/\\/g, "/")}`;
44
- }
45
- /**
46
- * Creates the page-owned route entry asset for hydration and client navigation.
47
- */
48
- createPageDependencies(options) {
49
- const {
50
- pagePath,
51
- componentName,
52
- importPath,
53
- pageModuleUrlExpression,
54
- bundleOptions,
55
- hmrEnabled,
56
- useBrowserRuntimeImports,
57
- isMdx
58
- } = options;
59
- const runtimeImports = this.config.bundleService.getRuntimeImports();
60
- const groupedBundle = !hmrEnabled && this.config.routerAdapter ? {
61
- id: HydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
62
- entryName: this.getRouterPageGroupedEntryName(pagePath)
63
- } : void 0;
64
- const bootstrapImports = resolveHydrationBootstrapImports({
65
- useBrowserRuntimeImports,
66
- runtimeImports,
67
- routerAdapterImportPath: this.config.routerAdapter?.bundle.importPath
68
- });
69
- return [
70
- AssetFactory.createContentScript({
71
- position: "head",
72
- content: createHydrationScript({
73
- importPath: hmrEnabled ? importPath : pagePath,
74
- pageModuleUrlExpression,
75
- reactImportPath: bootstrapImports.reactImportPath,
76
- reactDomClientImportPath: bootstrapImports.reactDomClientImportPath,
77
- routerImportPath: bootstrapImports.routerImportPath,
78
- layoutComposeImportPath: bootstrapImports.layoutComposeImportPath,
79
- pageLayoutNormalizationImportPath: bootstrapImports.pageLayoutNormalizationImportPath,
80
- hmrEnabled,
81
- isMdx,
82
- router: this.config.routerAdapter,
83
- scriptId: componentName
84
- }),
85
- name: componentName,
86
- packageRole: "page-script",
29
+ getIslandBundleName(componentFile) {
30
+ return `ecopages-react-island-${rapidhash(componentFile)}`;
31
+ }
32
+ getIslandHydrationName(bundleName, componentKey) {
33
+ return `${bundleName}-hydration-${componentKey}`;
34
+ }
35
+ getRouterPageGroupedEntryName(pagePath) {
36
+ const relativePath = path.relative(this.config.srcDir, pagePath);
37
+ return relativePath
38
+ .replace(/\.(tsx?|jsx?|mdx?)$/, '')
39
+ .replace(/[\\/]+/g, '__')
40
+ .replace(/\[([^\]]+)\]/g, '_$1_');
41
+ }
42
+ /**
43
+ * Resolves the browser import path used for a React-owned page or island module.
44
+ *
45
+ * @remarks
46
+ * When HMR is enabled, registers the source file as an HMR entrypoint and returns
47
+ * that URL. Otherwise returns the static resolved-assets path for the generated
48
+ * asset name.
49
+ */
50
+ async resolveAssetImportPath(pagePath, assetName) {
51
+ const hmrManager = this.config.assetProcessingService?.getHmrManager();
52
+ if (hmrManager?.isEnabled()) {
53
+ return hmrManager.registerEntrypoint(pagePath);
54
+ }
55
+ return `/${path
56
+ .join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath))
57
+ .replace(path.basename(pagePath), `${assetName}.js`)
58
+ .replace(/\\/g, '/')}`;
59
+ }
60
+ /**
61
+ * Creates the page-owned route entry asset for hydration and client navigation.
62
+ */
63
+ createPageDependencies(options) {
64
+ const { pagePath, componentName, importPath, pageModuleUrlExpression, bundleOptions, hmrEnabled, useBrowserRuntimeImports, isMdx, } = options;
65
+ const runtimeImports = this.config.bundleService.getRuntimeImports();
87
66
  /**
88
67
  * @remarks
89
- * HMR bootstraps stay unbundled write-through ESM. Helper imports must
90
- * already be browser-resolvable vendor URLs from
91
- * {@link resolveHydrationBootstrapImports}.
68
+ * Production router pages share a grouped bundle. Development HMR keeps each
69
+ * page bootstrap independent and unbundled; shared helpers resolve via vendor URLs.
92
70
  */
93
- bundle: !hmrEnabled,
94
- groupedBundle,
95
- bundleOptions,
96
- attributes: {
97
- type: "module",
98
- defer: "",
99
- "data-eco-rerun": "true",
100
- "data-eco-script-id": componentName,
101
- ...this.config.routerAdapter ? { "data-eco-page-bootstrap": "react-router" } : {},
102
- "data-eco-persist": "true"
103
- }
104
- })
105
- ];
106
- }
107
- /**
108
- * Builds client-side assets for a React component island.
109
- *
110
- * Includes the bundled component entry and a shared hydration bootstrap script.
111
- *
112
- * @param componentFile - Absolute path to the component source file
113
- * @param config - Optional component config with `__eco` metadata
114
- * @returns Processed assets ready for injection
115
- */
116
- async buildComponentRenderAssets(componentFile, config) {
117
- const componentName = this.getIslandBundleName(componentFile);
118
- const componentKey = getIslandComponentKey(componentFile, config);
119
- const hydrationName = this.getIslandHydrationName(componentName, componentKey);
120
- const hmrManager = this.config.assetProcessingService?.getHmrManager();
121
- const hmrEnabled = hmrManager?.isEnabled() ?? false;
122
- if (hmrEnabled) {
123
- this.config.hmrPageMetadataCache?.markOwnedEntrypoint(componentFile);
71
+ const groupedBundle = !hmrEnabled && this.config.routerAdapter
72
+ ? {
73
+ id: HydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
74
+ entryName: this.getRouterPageGroupedEntryName(pagePath),
75
+ }
76
+ : undefined;
77
+ const bootstrapImports = resolveHydrationBootstrapImports({
78
+ useBrowserRuntimeImports,
79
+ runtimeImports,
80
+ routerAdapterImportPath: this.config.routerAdapter?.bundle.importPath,
81
+ });
82
+ return [
83
+ AssetFactory.createContentScript({
84
+ position: 'head',
85
+ content: createHydrationScript({
86
+ importPath: hmrEnabled ? importPath : pagePath,
87
+ pageModuleUrlExpression,
88
+ reactImportPath: bootstrapImports.reactImportPath,
89
+ reactDomClientImportPath: bootstrapImports.reactDomClientImportPath,
90
+ routerImportPath: bootstrapImports.routerImportPath,
91
+ layoutComposeImportPath: bootstrapImports.layoutComposeImportPath,
92
+ pageLayoutNormalizationImportPath: bootstrapImports.pageLayoutNormalizationImportPath,
93
+ hmrEnabled,
94
+ isMdx,
95
+ router: this.config.routerAdapter,
96
+ scriptId: componentName,
97
+ }),
98
+ name: componentName,
99
+ packageRole: 'page-script',
100
+ /**
101
+ * @remarks
102
+ * HMR bootstraps stay unbundled write-through ESM. Helper imports must
103
+ * already be browser-resolvable vendor URLs from
104
+ * {@link resolveHydrationBootstrapImports}.
105
+ */
106
+ bundle: !hmrEnabled,
107
+ groupedBundle,
108
+ bundleOptions,
109
+ attributes: {
110
+ type: 'module',
111
+ defer: '',
112
+ 'data-eco-rerun': 'true',
113
+ 'data-eco-script-id': componentName,
114
+ ...(this.config.routerAdapter ? { 'data-eco-page-bootstrap': 'react-router' } : {}),
115
+ 'data-eco-persist': 'true',
116
+ },
117
+ }),
118
+ ];
124
119
  }
125
- const importPath = await this.resolveAssetImportPath(componentFile, componentName);
126
- const declaredModules = collectDeclaredModulesInConfig(config);
127
- const bundleOptions = await this.config.bundleService.createBundleOptions(
128
- componentName,
129
- false,
130
- declaredModules
131
- );
132
- const runtimeImports = this.config.bundleService.getRuntimeImports();
133
- const dependencies = [
134
- AssetFactory.createFileScript({
135
- position: "head",
136
- filepath: componentFile,
137
- name: componentName,
138
- packageRole: "dynamic-chunk",
139
- excludeFromHtml: true,
140
- bundle: true,
141
- bundleOptions,
142
- attributes: {
143
- type: "module",
144
- defer: "",
145
- "data-eco-persist": "true"
120
+ /**
121
+ * Builds client-side assets for a React component island.
122
+ *
123
+ * Includes the bundled component entry and a shared hydration bootstrap script.
124
+ *
125
+ * @param componentFile - Absolute path to the component source file
126
+ * @param config - Optional component config with `__eco` metadata
127
+ * @returns Processed assets ready for injection
128
+ */
129
+ async buildComponentRenderAssets(componentFile, config) {
130
+ const componentName = this.getIslandBundleName(componentFile);
131
+ const componentKey = getIslandComponentKey(componentFile, config);
132
+ const hydrationName = this.getIslandHydrationName(componentName, componentKey);
133
+ const hmrManager = this.config.assetProcessingService?.getHmrManager();
134
+ const hmrEnabled = hmrManager?.isEnabled() ?? false;
135
+ if (hmrEnabled) {
136
+ this.config.hmrPageMetadataCache?.markOwnedEntrypoint(componentFile);
146
137
  }
147
- }),
148
- AssetFactory.createContentScript({
149
- position: "head",
150
- content: createIslandHydrationScript({
151
- importPath,
152
- scriptId: hydrationName,
153
- reactImportPath: runtimeImports.react,
154
- reactDomClientImportPath: runtimeImports.reactDomClient,
155
- targetSelector: `[data-eco-component-key="${componentKey}"]`,
156
- componentRef: config?.__eco?.id,
157
- componentFile,
158
- minify: !hmrEnabled
159
- }),
160
- name: hydrationName,
161
- packageRole: "keep-separate",
162
- bundle: false,
163
- attributes: {
164
- type: "module",
165
- defer: "",
166
- "data-eco-rerun": "true",
167
- "data-eco-script-id": hydrationName,
168
- "data-eco-persist": "true"
138
+ const importPath = await this.resolveAssetImportPath(componentFile, componentName);
139
+ const runtimeImports = this.config.bundleService.getRuntimeImports();
140
+ const islandHydrationScript = createIslandHydrationScript({
141
+ importPath,
142
+ scriptId: hydrationName,
143
+ reactImportPath: runtimeImports.react,
144
+ reactDomClientImportPath: runtimeImports.reactDomClient,
145
+ targetSelector: `[data-eco-component-key="${componentKey}"]`,
146
+ componentRef: config?.__eco?.id,
147
+ componentFile,
148
+ minify: !hmrEnabled,
149
+ hmrEnabled,
150
+ });
151
+ const hydrationScript = AssetFactory.createContentScript({
152
+ position: 'head',
153
+ content: islandHydrationScript,
154
+ name: hydrationName,
155
+ packageRole: 'keep-separate',
156
+ bundle: false,
157
+ attributes: {
158
+ type: 'module',
159
+ defer: '',
160
+ 'data-eco-rerun': 'true',
161
+ 'data-eco-script-id': hydrationName,
162
+ 'data-eco-persist': 'true',
163
+ },
164
+ });
165
+ const dependencies = [hydrationScript];
166
+ if (!hmrEnabled) {
167
+ const declaredModules = collectDeclaredModulesInConfig(config);
168
+ const bundleOptions = await this.config.bundleService.createBundleOptions(componentName, false, declaredModules);
169
+ dependencies.unshift(AssetFactory.createFileScript({
170
+ position: 'head',
171
+ filepath: componentFile,
172
+ name: componentName,
173
+ packageRole: 'dynamic-chunk',
174
+ excludeFromHtml: true,
175
+ bundle: true,
176
+ bundleOptions,
177
+ attributes: {
178
+ type: 'module',
179
+ defer: '',
180
+ 'data-eco-persist': 'true',
181
+ },
182
+ }));
169
183
  }
170
- })
171
- ];
172
- if (!this.config.assetProcessingService) {
173
- return [];
184
+ if (!this.config.assetProcessingService) {
185
+ return [];
186
+ }
187
+ return this.config.assetProcessingService.processDependencies(dependencies, componentName);
174
188
  }
175
- return this.config.assetProcessingService.processDependencies(dependencies, componentName);
176
- }
177
- /**
178
- * Creates the page browser graph dependency declarations for a React page.
179
- *
180
- * @remarks
181
- * Chooses shared vendor import URLs when HMR is on, when running a non-production
182
- * hosted runtime with HMR off, or when a router adapter is configured (router
183
- * pages always externalize to shared runtimes). Production non-router pages
184
- * may inline React into the page bundle instead.
185
- *
186
- * @param pagePath - Absolute file path of the page
187
- * @param isMdx - Whether the page is an MDX file
188
- * @param declaredModules - Explicitly declared browser module specifiers
189
- */
190
- async createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules) {
191
- const componentName = `ecopages-react-${rapidhash(pagePath)}`;
192
- const hmrManager = this.config.assetProcessingService?.getHmrManager();
193
- const hmrEnabled = hmrManager?.isEnabled() ?? false;
194
- const productionRuntime = isReactProductionRuntime();
195
- const usesRouterRuntime = Boolean(this.config.routerAdapter);
196
- const useBrowserRuntimeImports = hmrEnabled || !productionRuntime || usesRouterRuntime;
197
- if (hmrEnabled) {
198
- this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
189
+ /**
190
+ * Creates the page browser graph dependency declarations for a React page.
191
+ *
192
+ * @remarks
193
+ * Chooses shared vendor import URLs when HMR is on, when running a non-production
194
+ * hosted runtime with HMR off, or when a router adapter is configured (router
195
+ * pages always externalize to shared runtimes). Production non-router pages
196
+ * may inline React into the page bundle instead.
197
+ *
198
+ * @param pagePath - Absolute file path of the page
199
+ * @param isMdx - Whether the page is an MDX file
200
+ * @param declaredModules - Explicitly declared browser module specifiers
201
+ */
202
+ async createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules) {
203
+ const componentName = `ecopages-react-${rapidhash(pagePath)}`;
204
+ const hmrManager = this.config.assetProcessingService?.getHmrManager();
205
+ const hmrEnabled = hmrManager?.isEnabled() ?? false;
206
+ const productionRuntime = isReactProductionRuntime();
207
+ const usesRouterRuntime = Boolean(this.config.routerAdapter);
208
+ const useBrowserRuntimeImports = hmrEnabled || !productionRuntime || usesRouterRuntime;
209
+ if (hmrEnabled) {
210
+ this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
211
+ }
212
+ const importPath = await this.resolveAssetImportPath(pagePath, componentName);
213
+ const pageModuleUrlExpression = hmrEnabled ? JSON.stringify(importPath) : 'import.meta.url';
214
+ const bundleOptions = await this.config.bundleService.createBundleOptions(componentName, isMdx, declaredModules, { includeRuntime: !useBrowserRuntimeImports, splitting: usesRouterRuntime });
215
+ const dependencies = this.createPageDependencies({
216
+ pagePath,
217
+ componentName,
218
+ importPath,
219
+ pageModuleUrlExpression,
220
+ bundleOptions,
221
+ hmrEnabled,
222
+ useBrowserRuntimeImports,
223
+ isMdx,
224
+ });
225
+ return dependencies;
199
226
  }
200
- const importPath = await this.resolveAssetImportPath(pagePath, componentName);
201
- const pageModuleUrlExpression = hmrEnabled ? JSON.stringify(importPath) : "import.meta.url";
202
- const bundleOptions = await this.config.bundleService.createBundleOptions(
203
- componentName,
204
- isMdx,
205
- declaredModules,
206
- { includeRuntime: !useBrowserRuntimeImports, splitting: usesRouterRuntime }
207
- );
208
- const dependencies = this.createPageDependencies({
209
- pagePath,
210
- componentName,
211
- importPath,
212
- pageModuleUrlExpression,
213
- bundleOptions,
214
- hmrEnabled,
215
- useBrowserRuntimeImports,
216
- isMdx
217
- });
218
- return dependencies;
219
- }
220
227
  }
221
- export {
222
- HydrationAssetService,
223
- getIslandComponentKey
224
- };