@ecopages/react 0.2.1 → 0.3.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.
Files changed (173) hide show
  1. package/README.md +178 -35
  2. package/package.json +80 -32
  3. package/src/app/client-only.js +10 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/app/dynamic.test.browser.d.ts +1 -0
  6. package/src/app/dynamic.test.browser.js +38 -0
  7. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  8. package/src/bundling/bootstrap-package-paths.js +5 -0
  9. package/src/bundling/bundle.d.ts +78 -0
  10. package/src/bundling/bundle.js +130 -0
  11. package/src/bundling/runtime-alias-map.d.ts +12 -0
  12. package/src/bundling/runtime-alias-map.js +110 -0
  13. package/src/bundling/runtime-bundle.d.ts +70 -0
  14. package/src/bundling/runtime-bundle.js +233 -0
  15. package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +1 -1
  16. package/src/bundling/runtime-interop-plugin.js +32 -0
  17. package/src/bundling/runtime-mode.d.ts +1 -0
  18. package/src/bundling/runtime-mode.js +10 -0
  19. package/src/bundling/runtime-modules.d.ts +21 -0
  20. package/src/bundling/runtime-modules.js +28 -0
  21. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  22. package/src/client-graph/ast-transform-eco-page.js +71 -0
  23. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  24. package/src/client-graph/ast-transform-import-edits.js +75 -0
  25. package/src/client-graph/ast-transform-walk-imports.d.ts +20 -0
  26. package/src/client-graph/ast-transform-walk-imports.js +105 -0
  27. package/src/client-graph/ast-transform.d.ts +12 -0
  28. package/src/client-graph/ast-transform.js +91 -0
  29. package/src/client-graph/ast-walk.d.ts +10 -0
  30. package/src/client-graph/ast-walk.js +26 -0
  31. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +7 -0
  32. package/src/client-graph/boundary-plugin-read-file-inline.js +43 -0
  33. package/src/client-graph/boundary-plugin-transform.d.ts +16 -0
  34. package/src/client-graph/boundary-plugin-transform.js +31 -0
  35. package/src/client-graph/boundary-plugin.d.ts +23 -0
  36. package/src/client-graph/boundary-plugin.js +177 -0
  37. package/src/client-graph/component-config-traversal.d.ts +36 -0
  38. package/src/client-graph/component-config-traversal.js +77 -0
  39. package/src/{utils → client-graph}/declared-modules.d.ts +1 -1
  40. package/src/client-graph/declared-modules.js +69 -0
  41. package/src/client-graph/module-classification.d.ts +3 -0
  42. package/src/client-graph/module-classification.js +43 -0
  43. package/src/client-graph/reachability-analyzer.d.ts +26 -0
  44. package/src/client-graph/reachability-analyzer.js +55 -0
  45. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  46. package/src/client-graph/reachability-client-roots.js +59 -0
  47. package/src/client-graph/reachability-export-names.d.ts +5 -0
  48. package/src/client-graph/reachability-export-names.js +34 -0
  49. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  50. package/src/client-graph/reachability-fallback-roots.js +71 -0
  51. package/src/client-graph/reachability-preload.d.ts +10 -0
  52. package/src/client-graph/reachability-preload.js +30 -0
  53. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  54. package/src/client-graph/reachability-top-level-index.js +93 -0
  55. package/src/client-graph/reachability-traverse.d.ts +7 -0
  56. package/src/client-graph/reachability-traverse.js +201 -0
  57. package/src/client-graph/specifier-classification.d.ts +74 -0
  58. package/src/client-graph/specifier-classification.js +191 -0
  59. package/src/content/collection-component-cache.d.ts +25 -0
  60. package/src/content/collection-component-cache.js +62 -0
  61. package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +7 -14
  62. package/src/contracts/router-adapter.js +6 -0
  63. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  64. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  65. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  66. package/src/hmr/hmr-strategy-process.js +83 -0
  67. package/src/hmr/hmr-strategy.d.ts +67 -0
  68. package/src/hmr/hmr-strategy.js +306 -0
  69. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +6 -2
  70. package/src/hmr/page-metadata-cache.js +44 -0
  71. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +22 -0
  72. package/src/hmr/react-hmr-dev-transform-plugins.js +19 -0
  73. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  74. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  75. package/src/hydration/bootstrap-imports.d.ts +25 -0
  76. package/src/hydration/bootstrap-imports.js +33 -0
  77. package/src/hydration/browser/island-hydration.d.ts +82 -0
  78. package/src/hydration/browser/island-hydration.js +251 -0
  79. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  80. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  81. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  82. package/src/hydration/browser/page-hydration-module.js +17 -0
  83. package/src/hydration/browser/page-hydration.d.ts +54 -0
  84. package/src/hydration/browser/page-hydration.js +177 -0
  85. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  86. package/src/hydration/compiled-page-hydration-options.js +1 -0
  87. package/src/hydration/hydration-asset.d.ts +127 -0
  88. package/src/hydration/hydration-asset.js +379 -0
  89. package/src/hydration/hydration-lifecycle.test.browser.d.ts +1 -0
  90. package/src/hydration/hydration-lifecycle.test.browser.js +461 -0
  91. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  92. package/src/hydration/hydration-page-entry-source.js +87 -0
  93. package/src/hydration/hydration-script-compiler.d.ts +48 -0
  94. package/src/hydration/hydration-script-compiler.js +213 -0
  95. package/src/hydration/page-data-manifest.d.ts +58 -0
  96. package/src/hydration/page-data-manifest.js +97 -0
  97. package/src/hydration/page-data-reader.d.ts +17 -0
  98. package/src/hydration/page-data-reader.js +31 -0
  99. package/src/hydration/page-payload.d.ts +68 -0
  100. package/src/hydration/page-payload.js +106 -0
  101. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  102. package/src/hydration/serialize-page-data-script.js +30 -0
  103. package/src/mdx/mdx-config-dependency.d.ts +37 -0
  104. package/src/mdx/mdx-config-dependency.js +107 -0
  105. package/src/mdx/mdx-loader-plugin.d.ts +8 -0
  106. package/src/mdx/mdx-loader-plugin.js +11 -0
  107. package/src/page/page-module.d.ts +46 -0
  108. package/src/page/page-module.js +74 -0
  109. package/src/plugin/react.constants.d.ts +1 -0
  110. package/src/plugin/react.constants.js +1 -0
  111. package/src/plugin/react.plugin.d.ts +71 -0
  112. package/src/plugin/react.plugin.js +210 -0
  113. package/src/plugin/react.types.d.ts +106 -0
  114. package/src/plugin/react.types.js +1 -0
  115. package/src/render/component-ownership.d.ts +49 -0
  116. package/src/render/component-ownership.js +47 -0
  117. package/src/render/component-ssr.d.ts +59 -0
  118. package/src/render/component-ssr.js +76 -0
  119. package/src/render/eco-embed.d.ts +11 -0
  120. package/src/render/eco-embed.js +9 -0
  121. package/src/render/errors.d.ts +16 -0
  122. package/src/render/errors.js +23 -0
  123. package/src/render/html-boundary.js +59 -0
  124. package/src/render/layout-compose.d.ts +66 -0
  125. package/src/render/layout-compose.js +134 -0
  126. package/src/render/react-renderer.d.ts +114 -0
  127. package/src/render/react-renderer.js +490 -0
  128. package/src/render/react-runtime.d.ts +13 -0
  129. package/src/render/react-runtime.js +26 -0
  130. package/src/render/unified-layout-composition.d.ts +22 -0
  131. package/src/render/unified-layout-composition.js +31 -0
  132. package/src/runtime/use-sync-external-store-with-selector.d.ts +3 -0
  133. package/src/runtime/use-sync-external-store-with-selector.js +54 -0
  134. package/CHANGELOG.md +0 -29
  135. package/src/react-hmr-strategy.d.ts +0 -148
  136. package/src/react-hmr-strategy.js +0 -313
  137. package/src/react-renderer.d.ts +0 -213
  138. package/src/react-renderer.js +0 -654
  139. package/src/react.plugin.d.ts +0 -147
  140. package/src/react.plugin.js +0 -146
  141. package/src/router-adapter.js +0 -0
  142. package/src/services/react-bundle.service.d.ts +0 -47
  143. package/src/services/react-bundle.service.js +0 -93
  144. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  145. package/src/services/react-hydration-asset.service.d.ts +0 -76
  146. package/src/services/react-hydration-asset.service.js +0 -210
  147. package/src/services/react-page-module.service.d.ts +0 -83
  148. package/src/services/react-page-module.service.js +0 -162
  149. package/src/services/react-runtime-bundle.service.d.ts +0 -40
  150. package/src/services/react-runtime-bundle.service.js +0 -130
  151. package/src/utils/client-graph-boundary-plugin.d.ts +0 -43
  152. package/src/utils/client-graph-boundary-plugin.js +0 -494
  153. package/src/utils/client-only.js +0 -19
  154. package/src/utils/declared-modules.js +0 -59
  155. package/src/utils/dynamic.js +0 -12
  156. package/src/utils/hmr-scripts.d.ts +0 -18
  157. package/src/utils/hmr-scripts.js +0 -31
  158. package/src/utils/html-boundary.js +0 -55
  159. package/src/utils/hydration-scripts.d.ts +0 -86
  160. package/src/utils/hydration-scripts.js +0 -285
  161. package/src/utils/reachability-analyzer.d.ts +0 -66
  162. package/src/utils/reachability-analyzer.js +0 -339
  163. package/src/utils/react-dom-runtime-interop-plugin.js +0 -29
  164. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  165. package/src/utils/react-mdx-loader-plugin.js +0 -45
  166. package/src/utils/react-runtime-specifier-map.d.ts +0 -6
  167. package/src/utils/react-runtime-specifier-map.js +0 -37
  168. package/src/utils/use-sync-external-store-shim-plugin.d.ts +0 -5
  169. package/src/utils/use-sync-external-store-shim-plugin.js +0 -41
  170. /package/src/{utils → app}/client-only.d.ts +0 -0
  171. /package/src/{utils → app}/dynamic.d.ts +0 -0
  172. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  173. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -1,210 +0,0 @@
1
- import path from "node:path";
2
- import { rapidhash } from "@ecopages/core/hash";
3
- import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
4
- import {
5
- AssetFactory
6
- } from "@ecopages/core/services/asset-processing-service";
7
- import { createHydrationScript, createIslandHydrationScript } from "../utils/hydration-scripts.js";
8
- import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
9
- function getReactIslandComponentKey(componentFile, config) {
10
- return rapidhash(`${componentFile}:${config?.__eco?.id ?? ""}`).toString();
11
- }
12
- class ReactHydrationAssetService {
13
- config;
14
- constructor(config) {
15
- this.config = config;
16
- }
17
- getIslandBundleName(componentFile) {
18
- return `ecopages-react-island-${rapidhash(componentFile)}`;
19
- }
20
- getIslandHydrationName(bundleName, componentKey) {
21
- return `${bundleName}-hydration-${componentKey}`;
22
- }
23
- /**
24
- * Resolves the import path for the bundled page component.
25
- * Uses HMR manager for development or constructs static path for production.
26
- *
27
- * @param pagePath - Absolute path to the page source file
28
- * @param assetName - Generated asset name
29
- * @returns The resolved import path for the bundled component
30
- */
31
- async resolveAssetImportPath(pagePath, assetName) {
32
- const hmrManager = this.config.assetProcessingService?.getHmrManager();
33
- if (hmrManager?.isEnabled()) {
34
- return hmrManager.registerEntrypoint(pagePath);
35
- }
36
- return `/${path.join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath)).replace(path.basename(pagePath), `${assetName}.js`).replace(/\\/g, "/")}`;
37
- }
38
- /**
39
- * Creates the asset dependencies for a page: the bundled component and hydration script.
40
- *
41
- * @param pagePath - Absolute path to the page source file
42
- * @param componentName - Generated unique component name
43
- * @param importPath - Resolved import path for the bundled component
44
- * @param bundleOptions - Bundle configuration options
45
- * @param isDevelopment - Whether running in development mode with HMR
46
- * @param isMdx - Whether the source file is an MDX file
47
- * @param props - Optional page props for client serialization
48
- * @returns Array of asset definitions for processing
49
- */
50
- createPageDependencies(pagePath, componentName, importPath, bundleOptions, isDevelopment, isMdx, props) {
51
- const runtimeImports = this.config.bundleService.getRuntimeImports();
52
- const dependencies = [
53
- AssetFactory.createFileScript({
54
- position: "head",
55
- filepath: pagePath,
56
- name: componentName,
57
- excludeFromHtml: true,
58
- bundle: true,
59
- bundleOptions,
60
- attributes: {
61
- type: "module",
62
- defer: "",
63
- "data-eco-persist": "true"
64
- }
65
- })
66
- ];
67
- if (props && Object.keys(props).length > 0) {
68
- dependencies.push(
69
- AssetFactory.createContentScript({
70
- position: "head",
71
- content: `window.__ECO_PAGES__=window.__ECO_PAGES__||{};window.__ECO_PAGES__.page={module:"${importPath}",props:${JSON.stringify(props)}};`,
72
- name: `${componentName}-props`,
73
- bundle: false,
74
- attributes: {
75
- type: "module"
76
- }
77
- })
78
- );
79
- }
80
- dependencies.push(
81
- AssetFactory.createContentScript({
82
- position: "head",
83
- content: createHydrationScript({
84
- importPath,
85
- reactImportPath: runtimeImports.react,
86
- reactDomClientImportPath: runtimeImports.reactDomClient,
87
- routerImportPath: runtimeImports.router,
88
- isDevelopment,
89
- isMdx,
90
- router: this.config.routerAdapter
91
- }),
92
- name: `${componentName}-hydration`,
93
- bundle: false,
94
- attributes: {
95
- type: "module",
96
- defer: "",
97
- "data-eco-rerun": "true",
98
- "data-eco-script-id": `${componentName}-hydration`,
99
- "data-eco-persist": "true"
100
- }
101
- })
102
- );
103
- return dependencies;
104
- }
105
- /**
106
- * Builds client-side assets for a React component island.
107
- *
108
- * Includes the bundled component entry and a shared hydration bootstrap script.
109
- *
110
- * @param componentFile - Absolute path to the component source file
111
- * @param config - Optional component config with `__eco` metadata
112
- * @returns Processed assets ready for injection
113
- */
114
- async buildComponentRenderAssets(componentFile, config) {
115
- const componentName = this.getIslandBundleName(componentFile);
116
- const componentKey = getReactIslandComponentKey(componentFile, config);
117
- const hydrationName = this.getIslandHydrationName(componentName, componentKey);
118
- const hmrManager = this.config.assetProcessingService?.getHmrManager();
119
- const isDevelopment = hmrManager?.isEnabled() ?? false;
120
- if (isDevelopment) {
121
- this.config.hmrPageMetadataCache?.markOwnedEntrypoint(componentFile);
122
- }
123
- const importPath = await this.resolveAssetImportPath(componentFile, componentName);
124
- const declaredModules = collectDeclaredModulesInConfig(config);
125
- const bundleOptions = await this.config.bundleService.createBundleOptions(
126
- componentName,
127
- false,
128
- declaredModules
129
- );
130
- const runtimeImports = this.config.bundleService.getRuntimeImports();
131
- const dependencies = [
132
- AssetFactory.createFileScript({
133
- position: "head",
134
- filepath: componentFile,
135
- name: componentName,
136
- excludeFromHtml: true,
137
- bundle: true,
138
- bundleOptions,
139
- attributes: {
140
- type: "module",
141
- defer: "",
142
- "data-eco-persist": "true"
143
- }
144
- }),
145
- AssetFactory.createContentScript({
146
- position: "head",
147
- content: createIslandHydrationScript({
148
- importPath,
149
- reactImportPath: runtimeImports.react,
150
- reactDomClientImportPath: runtimeImports.reactDomClient,
151
- targetSelector: `[data-eco-component-key="${componentKey}"]`,
152
- componentRef: config?.__eco?.id,
153
- componentFile,
154
- isDevelopment
155
- }),
156
- name: hydrationName,
157
- bundle: false,
158
- attributes: {
159
- type: "module",
160
- defer: "",
161
- "data-eco-rerun": "true",
162
- "data-eco-script-id": hydrationName,
163
- "data-eco-persist": "true"
164
- }
165
- })
166
- ];
167
- if (!this.config.assetProcessingService) {
168
- return [];
169
- }
170
- return this.config.assetProcessingService.processDependencies(dependencies, componentName);
171
- }
172
- /**
173
- * Builds all client-side route assets for a page.
174
- *
175
- * @param pagePath - Absolute file path of the page
176
- * @param isMdx - Whether the page is an MDX file
177
- * @param declaredModules - Explicitly declared browser module specifiers
178
- * @returns Processed assets for the route
179
- */
180
- async buildRouteRenderAssets(pagePath, isMdx, declaredModules) {
181
- const componentName = `ecopages-react-${rapidhash(pagePath)}`;
182
- const hmrManager = this.config.assetProcessingService?.getHmrManager();
183
- const isDevelopment = hmrManager?.isEnabled() ?? false;
184
- if (isDevelopment) {
185
- this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
186
- }
187
- const importPath = await this.resolveAssetImportPath(pagePath, componentName);
188
- const bundleOptions = await this.config.bundleService.createBundleOptions(
189
- componentName,
190
- isMdx,
191
- declaredModules
192
- );
193
- const dependencies = this.createPageDependencies(
194
- pagePath,
195
- componentName,
196
- importPath,
197
- bundleOptions,
198
- isDevelopment,
199
- isMdx
200
- );
201
- if (!this.config.assetProcessingService) {
202
- throw new Error("AssetProcessingService is not set");
203
- }
204
- return this.config.assetProcessingService.processDependencies(dependencies, componentName);
205
- }
206
- }
207
- export {
208
- ReactHydrationAssetService,
209
- getReactIslandComponentKey
210
- };
@@ -1,83 +0,0 @@
1
- /**
2
- * Page module loading and configuration resolution service for React integration.
3
- *
4
- * Handles MDX compilation, component config metadata resolution,
5
- * and module hydration analysis.
6
- *
7
- * @module
8
- */
9
- import type { EcoComponentConfig, EcoPageFile } from '@ecopages/core';
10
- import type { BuildExecutor } from '@ecopages/core/build/build-adapter';
11
- import type { CompileOptions } from '@mdx-js/mdx';
12
- /**
13
- * Configuration for the ReactPageModuleService.
14
- */
15
- export interface ReactPageModuleServiceConfig {
16
- rootDir: string;
17
- distDir: string;
18
- workDir: string;
19
- buildExecutor: BuildExecutor;
20
- layoutsDir?: string;
21
- componentsDir?: string;
22
- mdxCompilerOptions?: CompileOptions;
23
- mdxExtensions: string[];
24
- integrationName: string;
25
- hasRouterAdapter: boolean;
26
- }
27
- /**
28
- * Manages page module loading (including MDX compilation), config metadata
29
- * resolution, and hydration analysis for React pages.
30
- */
31
- export declare class ReactPageModuleService {
32
- private readonly config;
33
- constructor(config: ReactPageModuleServiceConfig);
34
- /**
35
- * Checks if the given file path corresponds to an MDX file based on configured extensions.
36
- * @param filePath - The file path to check
37
- * @returns True if the file is an MDX file
38
- */
39
- isMdxFile(filePath: string): boolean;
40
- /**
41
- * Compiles and imports an MDX file as a page module.
42
- *
43
- * @param filePath - Absolute path to the MDX file
44
- * @returns The imported module
45
- */
46
- importMdxPageFile(filePath: string): Promise<unknown>;
47
- /**
48
- * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
49
- * Resolves the file path from dependency declarations when not already set.
50
- *
51
- * @param config - The component config to augment
52
- * @param pagePath - Fallback file path if dependency resolution fails
53
- * @returns Config with `__eco` metadata populated
54
- */
55
- ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig;
56
- /**
57
- * Recursively checks whether a component config tree declares any browser modules.
58
- * Used to determine if a page needs hydration.
59
- */
60
- hasModulesInConfig(config: EcoComponentConfig | undefined, visited?: Set<EcoComponentConfig>): boolean;
61
- /**
62
- * Determines whether a page needs client-side hydration.
63
- *
64
- * @param pageModule - The imported page module
65
- * @returns True if the page should be hydrated
66
- */
67
- shouldHydratePage(pageModule: EcoPageFile<{
68
- config?: EcoComponentConfig;
69
- }> & {
70
- config?: EcoComponentConfig;
71
- }): boolean;
72
- /**
73
- * Collects all explicitly declared browser module specifiers from a page module.
74
- *
75
- * @param pageModule - The imported page module
76
- * @returns Deduplicated list of declared module specifiers
77
- */
78
- collectPageDeclaredModules(pageModule: EcoPageFile<{
79
- config?: EcoComponentConfig;
80
- }> & {
81
- config?: EcoComponentConfig;
82
- }): string[];
83
- }
@@ -1,162 +0,0 @@
1
- import path from "node:path";
2
- import { pathToFileURL } from "node:url";
3
- import { rapidhash } from "@ecopages/core/hash";
4
- import { build } from "@ecopages/core/build/build-adapter";
5
- import { fileSystem } from "@ecopages/file-system";
6
- import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
7
- class ReactPageModuleService {
8
- config;
9
- constructor(config) {
10
- this.config = config;
11
- }
12
- /**
13
- * Checks if the given file path corresponds to an MDX file based on configured extensions.
14
- * @param filePath - The file path to check
15
- * @returns True if the file is an MDX file
16
- */
17
- isMdxFile(filePath) {
18
- return this.config.mdxExtensions.some((ext) => filePath.endsWith(ext));
19
- }
20
- /**
21
- * Compiles and imports an MDX file as a page module.
22
- *
23
- * @param filePath - Absolute path to the MDX file
24
- * @returns The imported module
25
- */
26
- async importMdxPageFile(filePath) {
27
- const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
28
- const mdxPlugin = createReactMdxLoaderPlugin(
29
- this.config.mdxCompilerOptions ?? {
30
- jsxImportSource: "react",
31
- jsxRuntime: "automatic",
32
- development: process?.env?.NODE_ENV === "development"
33
- }
34
- );
35
- const outdir = path.join(this.config.workDir, ".server-modules-react-mdx");
36
- const fileBaseName = path.basename(filePath, path.extname(filePath));
37
- const fileHash = fileSystem.hash(filePath);
38
- const cacheBuster = process?.env?.NODE_ENV === "development" ? `-${Date.now()}` : "";
39
- const outputFileName = `${fileBaseName}-${fileHash}${cacheBuster}.js`;
40
- const buildResult = await build(
41
- {
42
- entrypoints: [filePath],
43
- root: this.config.rootDir,
44
- outdir,
45
- target: "es2022",
46
- format: "esm",
47
- sourcemap: "none",
48
- splitting: false,
49
- minify: false,
50
- treeshaking: false,
51
- naming: outputFileName,
52
- plugins: [mdxPlugin]
53
- },
54
- this.config.buildExecutor
55
- );
56
- if (!buildResult.success) {
57
- const details = buildResult.logs.map((log) => log.message).join(" | ");
58
- throw new Error(`Failed to compile MDX page module: ${details}`);
59
- }
60
- const preferredOutputPath = path.join(outdir, outputFileName);
61
- const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => output.path.endsWith(".js"))?.path;
62
- if (!compiledOutput) {
63
- throw new Error(`No compiled MDX output generated for page: ${filePath}`);
64
- }
65
- return await import(
66
- /* @vite-ignore */
67
- pathToFileURL(compiledOutput).href
68
- );
69
- }
70
- /**
71
- * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
72
- * Resolves the file path from dependency declarations when not already set.
73
- *
74
- * @param config - The component config to augment
75
- * @param pagePath - Fallback file path if dependency resolution fails
76
- * @returns Config with `__eco` metadata populated
77
- */
78
- ensureConfigFileMetadata(config, pagePath) {
79
- if (config.__eco?.file) {
80
- return config;
81
- }
82
- const buildEcoMeta = (file) => ({
83
- id: config.__eco?.id ?? rapidhash(file).toString(36),
84
- integration: config.__eco?.integration ?? this.config.integrationName,
85
- file
86
- });
87
- const resolveDependencyValue = (value) => typeof value === "string" ? value : value.src;
88
- const dependencyPaths = [
89
- ...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
90
- ...(config.dependencies?.scripts ?? []).map(resolveDependencyValue)
91
- ].filter((value) => Boolean(value)).filter((value) => value.startsWith("./") || value.startsWith("../"));
92
- const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter(
93
- (value) => typeof value === "string" && value.length > 0
94
- );
95
- for (const dependencyPath of dependencyPaths) {
96
- for (const candidateDir of candidateDirs) {
97
- const resolvedDependency = path.resolve(candidateDir, dependencyPath);
98
- if (fileSystem.exists(resolvedDependency)) {
99
- return {
100
- ...config,
101
- __eco: buildEcoMeta(path.join(candidateDir, path.basename(pagePath)))
102
- };
103
- }
104
- }
105
- }
106
- return {
107
- ...config,
108
- __eco: buildEcoMeta(pagePath)
109
- };
110
- }
111
- /**
112
- * Recursively checks whether a component config tree declares any browser modules.
113
- * Used to determine if a page needs hydration.
114
- */
115
- hasModulesInConfig(config, visited = /* @__PURE__ */ new Set()) {
116
- if (!config || visited.has(config)) {
117
- return false;
118
- }
119
- visited.add(config);
120
- if (config.dependencies?.modules?.some((entry) => entry.trim().length > 0)) {
121
- return true;
122
- }
123
- if (config.layout?.config && this.hasModulesInConfig(config.layout.config, visited)) {
124
- return true;
125
- }
126
- for (const component of config.dependencies?.components ?? []) {
127
- if (this.hasModulesInConfig(component.config, visited)) {
128
- return true;
129
- }
130
- }
131
- return false;
132
- }
133
- /**
134
- * Determines whether a page needs client-side hydration.
135
- *
136
- * @param pageModule - The imported page module
137
- * @returns True if the page should be hydrated
138
- */
139
- shouldHydratePage(pageModule) {
140
- if (this.config.hasRouterAdapter) {
141
- return true;
142
- }
143
- const pageConfig = pageModule.default?.config;
144
- return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
145
- }
146
- /**
147
- * Collects all explicitly declared browser module specifiers from a page module.
148
- *
149
- * @param pageModule - The imported page module
150
- * @returns Deduplicated list of declared module specifiers
151
- */
152
- collectPageDeclaredModules(pageModule) {
153
- const declarations = [
154
- ...collectDeclaredModulesInConfig(pageModule.default?.config),
155
- ...collectDeclaredModulesInConfig(pageModule.config)
156
- ];
157
- return Array.from(new Set(declarations));
158
- }
159
- }
160
- export {
161
- ReactPageModuleService
162
- };
@@ -1,40 +0,0 @@
1
- /**
2
- * Runtime bundle service for React integration.
3
- *
4
- * Owns creation of the browser runtime assets for React and React DOM,
5
- * including shared runtime entry generation and specifier mapping.
6
- *
7
- * @module
8
- */
9
- import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
10
- import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
11
- import type { ReactRouterAdapter } from '../router-adapter.js';
12
- export type ReactRuntimeImports = {
13
- react: string;
14
- reactDomClient: string;
15
- reactJsxRuntime: string;
16
- reactJsxDevRuntime: string;
17
- reactDom: string;
18
- router?: string;
19
- };
20
- export interface ReactRuntimeBundleServiceConfig {
21
- routerAdapter?: ReactRouterAdapter;
22
- rootDir?: string;
23
- }
24
- type RuntimeMode = 'development' | 'production';
25
- export declare class ReactRuntimeBundleService {
26
- private readonly config;
27
- constructor(config: ReactRuntimeBundleServiceConfig);
28
- setRootDir(rootDir: string | undefined): void;
29
- private get isDevelopment();
30
- private getCurrentRuntimeMode;
31
- private createRuntimeDefines;
32
- private getReactVendorFileName;
33
- private getReactDomVendorFileName;
34
- private getRouterVendorFileName;
35
- getRuntimeImports(mode?: RuntimeMode): ReactRuntimeImports;
36
- getSpecifierMap(mode?: RuntimeMode): Record<string, string>;
37
- getDependencies(): AssetDefinition[];
38
- createRuntimeAliasPlugin(mode?: RuntimeMode): EcoBuildPlugin;
39
- }
40
- export {};
@@ -1,130 +0,0 @@
1
- import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
2
- import {
3
- buildBrowserRuntimeAssetUrl,
4
- createBrowserRuntimeModuleAsset,
5
- createBrowserRuntimeScriptAsset
6
- } from "@ecopages/core/services/asset-processing-service";
7
- import { createReactDomRuntimeInteropPlugin } from "../utils/react-dom-runtime-interop-plugin.js";
8
- import { buildReactRuntimeSpecifierMap } from "../utils/react-runtime-specifier-map.js";
9
- class ReactRuntimeBundleService {
10
- config;
11
- constructor(config) {
12
- this.config = config;
13
- }
14
- setRootDir(rootDir) {
15
- this.config.rootDir = rootDir;
16
- }
17
- get isDevelopment() {
18
- return process.env.NODE_ENV === "development";
19
- }
20
- getCurrentRuntimeMode() {
21
- return this.isDevelopment ? "development" : "production";
22
- }
23
- createRuntimeDefines(mode) {
24
- const nodeEnv = JSON.stringify(mode);
25
- return {
26
- "process.env.NODE_ENV": nodeEnv,
27
- "import.meta.env.NODE_ENV": nodeEnv
28
- };
29
- }
30
- getReactVendorFileName(mode) {
31
- return mode === "development" ? "react.development.js" : "react.js";
32
- }
33
- getReactDomVendorFileName(mode) {
34
- return mode === "development" ? "react-dom.development.js" : "react-dom.js";
35
- }
36
- getRouterVendorFileName(mode) {
37
- if (!this.config.routerAdapter) {
38
- return "";
39
- }
40
- return mode === "development" ? `${this.config.routerAdapter.bundle.outputName}.development.js` : `${this.config.routerAdapter.bundle.outputName}.js`;
41
- }
42
- getRuntimeImports(mode = this.getCurrentRuntimeMode()) {
43
- const reactVendorFileName = this.getReactVendorFileName(mode);
44
- const reactDomVendorFileName = this.getReactDomVendorFileName(mode);
45
- const runtimeImports = {
46
- react: buildBrowserRuntimeAssetUrl(reactVendorFileName),
47
- reactDomClient: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
48
- reactJsxRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
49
- reactJsxDevRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
50
- reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName)
51
- };
52
- if (this.config.routerAdapter) {
53
- runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getRouterVendorFileName(mode));
54
- }
55
- return runtimeImports;
56
- }
57
- getSpecifierMap(mode = this.getCurrentRuntimeMode()) {
58
- return buildReactRuntimeSpecifierMap(this.getRuntimeImports(mode), this.config.routerAdapter);
59
- }
60
- getDependencies() {
61
- const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin();
62
- const dependencies = [];
63
- for (const mode of ["production", "development"]) {
64
- const reactRuntimeAliasPlugin = createRuntimeSpecifierAliasPlugin(
65
- {
66
- react: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
67
- },
68
- { name: `react-plugin-runtime-specifier-alias-${mode}` }
69
- );
70
- const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter(
71
- (plugin) => plugin !== null
72
- );
73
- const runtimeAliasPlugin = this.createRuntimeAliasPlugin(mode);
74
- const mappedSpecifiers = new Set(Object.keys(this.getSpecifierMap(mode)));
75
- dependencies.push(
76
- createBrowserRuntimeModuleAsset({
77
- modules: [
78
- { specifier: "react", defaultExport: true },
79
- { specifier: "react/jsx-runtime" },
80
- { specifier: "react/jsx-dev-runtime" }
81
- ],
82
- name: "react",
83
- fileName: this.getReactVendorFileName(mode),
84
- cacheDirName: `ecopages-react-runtime-${mode}`,
85
- rootDir: this.config.rootDir,
86
- bundleOptions: {
87
- define: this.createRuntimeDefines(mode)
88
- }
89
- }),
90
- createBrowserRuntimeModuleAsset({
91
- modules: [{ specifier: "react-dom", defaultExport: true }, { specifier: "react-dom/client" }],
92
- name: "react-dom",
93
- fileName: this.getReactDomVendorFileName(mode),
94
- cacheDirName: `ecopages-react-runtime-${mode}`,
95
- rootDir: this.config.rootDir,
96
- bundleOptions: {
97
- define: this.createRuntimeDefines(mode),
98
- plugins: reactDomBundlePlugins
99
- }
100
- })
101
- );
102
- if (this.config.routerAdapter) {
103
- const unresolvedExternals = this.config.routerAdapter.bundle.externals.filter(
104
- (external) => !mappedSpecifiers.has(external)
105
- );
106
- dependencies.push(
107
- createBrowserRuntimeScriptAsset({
108
- importPath: this.config.routerAdapter.bundle.importPath,
109
- name: this.config.routerAdapter.bundle.outputName,
110
- fileName: this.getRouterVendorFileName(mode),
111
- bundleOptions: {
112
- define: this.createRuntimeDefines(mode),
113
- external: unresolvedExternals,
114
- plugins: [runtimeAliasPlugin]
115
- }
116
- })
117
- );
118
- }
119
- }
120
- return dependencies;
121
- }
122
- createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode()) {
123
- return createRuntimeSpecifierAliasPlugin(this.getSpecifierMap(mode), {
124
- name: `react-plugin-runtime-alias-${mode}`
125
- });
126
- }
127
- }
128
- export {
129
- ReactRuntimeBundleService
130
- };
@@ -1,43 +0,0 @@
1
- /**
2
- * @module ClientGraphBoundaryPlugin
3
- *
4
- * This module defines the primary esbuild plugin responsible for securing the Ecopages
5
- * isomorphic compilation pipeline. It ensures that backend-only code, sensitive Node.js APIs,
6
- * and massive server utilities do not accidentally leak into the browser bundle.
7
- *
8
- * It achieves this by intercepting all client module compilation passes and applying the
9
- * `analyzeReachability` AST pass. If a forbidden import (e.g. `node:fs` or `*.server.ts`)
10
- * is completely unreachable from the client component's `render` function, it is surgically
11
- * pruned. If a forbidden import IS reachable, the build is intentionally failed to prevent
12
- * runtime hydration crashes.
13
- *
14
- * Additionally, this plugin provides a build-time transform that statically resolves and
15
- * inlines `fs.readFileSync(path.resolve(...))` calls to prevent server/client data mismatches.
16
- */
17
- import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
18
- /**
19
- * Configuration options for the Client Graph Boundary esbuild plugin.
20
- *
21
- * This plugin serves as the primary security layer between server-only logic and the client-side JavaScript bundle.
22
- * It prevents Node.js built-ins (`node:fs`, `node:path`) and backend-exclusive dependencies (e.g. `pg`, `redis`)
23
- * from accidentally leaking into the browser compilation step, which would cause immediate crashes.
24
- */
25
- type ClientGraphBoundaryOptions = {
26
- /** Absolute path to the current working directory, used as a root fallback for resolving inline file reads. */
27
- absWorkingDir?: string;
28
- /**
29
- * Array of module specifiers that are explicitly whitelisted to be bundled in the client code.
30
- * This is typically populated by parsing `modules: ["..."]` declarations in React/Lit components.
31
- */
32
- declaredModules?: string[];
33
- /** Array of emergency escape-hatch specifiers that always bypass the boundary checks regardless of component declarations. */
34
- alwaysAllowSpecifiers?: string[];
35
- };
36
- /**
37
- * Instantiates the client graph boundary esbuild plugin.
38
- *
39
- * @param options - Configuration options for the graph boundary.
40
- * @returns The resulting `EcoBuildPlugin`.
41
- */
42
- export declare function createClientGraphBoundaryPlugin(options?: ClientGraphBoundaryOptions): EcoBuildPlugin;
43
- export {};