@ecopages/react 0.2.1 → 0.3.1

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 (167) hide show
  1. package/README.md +179 -35
  2. package/package.json +78 -33
  3. package/src/app/client-only.js +10 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  6. package/src/bundling/bootstrap-package-paths.js +5 -0
  7. package/src/bundling/bundle.d.ts +78 -0
  8. package/src/bundling/bundle.js +130 -0
  9. package/src/bundling/runtime-alias-map.d.ts +12 -0
  10. package/src/bundling/runtime-alias-map.js +110 -0
  11. package/src/bundling/runtime-bundle.d.ts +70 -0
  12. package/src/bundling/runtime-bundle.js +233 -0
  13. package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +1 -1
  14. package/src/bundling/runtime-interop-plugin.js +32 -0
  15. package/src/bundling/runtime-mode.d.ts +1 -0
  16. package/src/bundling/runtime-mode.js +10 -0
  17. package/src/bundling/runtime-modules.d.ts +21 -0
  18. package/src/bundling/runtime-modules.js +28 -0
  19. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  20. package/src/client-graph/ast-transform-eco-page.js +71 -0
  21. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  22. package/src/client-graph/ast-transform-import-edits.js +75 -0
  23. package/src/client-graph/ast-transform-walk-imports.d.ts +20 -0
  24. package/src/client-graph/ast-transform-walk-imports.js +105 -0
  25. package/src/client-graph/ast-transform.d.ts +12 -0
  26. package/src/client-graph/ast-transform.js +91 -0
  27. package/src/client-graph/ast-walk.d.ts +10 -0
  28. package/src/client-graph/ast-walk.js +26 -0
  29. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +7 -0
  30. package/src/client-graph/boundary-plugin-read-file-inline.js +43 -0
  31. package/src/client-graph/boundary-plugin-transform.d.ts +16 -0
  32. package/src/client-graph/boundary-plugin-transform.js +31 -0
  33. package/src/client-graph/boundary-plugin.d.ts +23 -0
  34. package/src/client-graph/boundary-plugin.js +177 -0
  35. package/src/client-graph/component-config-traversal.d.ts +36 -0
  36. package/src/client-graph/component-config-traversal.js +77 -0
  37. package/src/{utils → client-graph}/declared-modules.d.ts +1 -1
  38. package/src/client-graph/declared-modules.js +69 -0
  39. package/src/client-graph/module-classification.d.ts +3 -0
  40. package/src/client-graph/module-classification.js +43 -0
  41. package/src/client-graph/reachability-analyzer.d.ts +26 -0
  42. package/src/client-graph/reachability-analyzer.js +55 -0
  43. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  44. package/src/client-graph/reachability-client-roots.js +59 -0
  45. package/src/client-graph/reachability-export-names.d.ts +5 -0
  46. package/src/client-graph/reachability-export-names.js +34 -0
  47. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  48. package/src/client-graph/reachability-fallback-roots.js +71 -0
  49. package/src/client-graph/reachability-preload.d.ts +10 -0
  50. package/src/client-graph/reachability-preload.js +30 -0
  51. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  52. package/src/client-graph/reachability-top-level-index.js +93 -0
  53. package/src/client-graph/reachability-traverse.d.ts +7 -0
  54. package/src/client-graph/reachability-traverse.js +201 -0
  55. package/src/client-graph/specifier-classification.d.ts +74 -0
  56. package/src/client-graph/specifier-classification.js +191 -0
  57. package/src/content/collection-component-cache.d.ts +25 -0
  58. package/src/content/collection-component-cache.js +62 -0
  59. package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +7 -14
  60. package/src/contracts/router-adapter.js +6 -0
  61. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  62. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  63. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  64. package/src/hmr/hmr-strategy-process.js +83 -0
  65. package/src/hmr/hmr-strategy.d.ts +67 -0
  66. package/src/hmr/hmr-strategy.js +306 -0
  67. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +6 -2
  68. package/src/hmr/page-metadata-cache.js +44 -0
  69. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +22 -0
  70. package/src/hmr/react-hmr-dev-transform-plugins.js +19 -0
  71. package/src/hydration/bootstrap-imports.d.ts +25 -0
  72. package/src/hydration/bootstrap-imports.js +33 -0
  73. package/src/hydration/browser/island-hydration.d.ts +81 -0
  74. package/src/hydration/browser/island-hydration.js +247 -0
  75. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  76. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  77. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  78. package/src/hydration/browser/page-hydration-module.js +17 -0
  79. package/src/hydration/browser/page-hydration.d.ts +54 -0
  80. package/src/hydration/browser/page-hydration.js +177 -0
  81. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  82. package/src/hydration/compiled-page-hydration-options.js +1 -0
  83. package/src/hydration/hydration-asset.d.ts +128 -0
  84. package/src/hydration/hydration-asset.js +388 -0
  85. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  86. package/src/hydration/hydration-page-entry-source.js +87 -0
  87. package/src/hydration/hydration-script-compiler.d.ts +47 -0
  88. package/src/hydration/hydration-script-compiler.js +213 -0
  89. package/src/hydration/page-data-manifest.d.ts +58 -0
  90. package/src/hydration/page-data-manifest.js +97 -0
  91. package/src/hydration/page-data-reader.d.ts +17 -0
  92. package/src/hydration/page-data-reader.js +31 -0
  93. package/src/hydration/page-payload.d.ts +68 -0
  94. package/src/hydration/page-payload.js +106 -0
  95. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  96. package/src/hydration/serialize-page-data-script.js +30 -0
  97. package/src/mdx/mdx-config-dependency.d.ts +37 -0
  98. package/src/mdx/mdx-config-dependency.js +107 -0
  99. package/src/mdx/mdx-loader-plugin.d.ts +8 -0
  100. package/src/mdx/mdx-loader-plugin.js +11 -0
  101. package/src/page/page-module.d.ts +46 -0
  102. package/src/page/page-module.js +74 -0
  103. package/src/plugin/react.constants.d.ts +1 -0
  104. package/src/plugin/react.constants.js +1 -0
  105. package/src/plugin/react.plugin.d.ts +71 -0
  106. package/src/plugin/react.plugin.js +210 -0
  107. package/src/plugin/react.types.d.ts +106 -0
  108. package/src/plugin/react.types.js +1 -0
  109. package/src/render/component-ownership.d.ts +49 -0
  110. package/src/render/component-ownership.js +47 -0
  111. package/src/render/component-ssr.d.ts +59 -0
  112. package/src/render/component-ssr.js +76 -0
  113. package/src/render/eco-embed.d.ts +11 -0
  114. package/src/render/eco-embed.js +9 -0
  115. package/src/render/errors.d.ts +16 -0
  116. package/src/render/errors.js +23 -0
  117. package/src/render/html-boundary.js +59 -0
  118. package/src/render/layout-compose.d.ts +66 -0
  119. package/src/render/layout-compose.js +134 -0
  120. package/src/render/react-renderer.d.ts +114 -0
  121. package/src/render/react-renderer.js +490 -0
  122. package/src/render/react-runtime.d.ts +13 -0
  123. package/src/render/react-runtime.js +26 -0
  124. package/src/render/unified-layout-composition.d.ts +22 -0
  125. package/src/render/unified-layout-composition.js +31 -0
  126. package/src/runtime/use-sync-external-store-with-selector.d.ts +3 -0
  127. package/src/runtime/use-sync-external-store-with-selector.js +54 -0
  128. package/CHANGELOG.md +0 -29
  129. package/src/react-hmr-strategy.d.ts +0 -148
  130. package/src/react-hmr-strategy.js +0 -313
  131. package/src/react-renderer.d.ts +0 -213
  132. package/src/react-renderer.js +0 -654
  133. package/src/react.plugin.d.ts +0 -147
  134. package/src/react.plugin.js +0 -146
  135. package/src/router-adapter.js +0 -0
  136. package/src/services/react-bundle.service.d.ts +0 -47
  137. package/src/services/react-bundle.service.js +0 -93
  138. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  139. package/src/services/react-hydration-asset.service.d.ts +0 -76
  140. package/src/services/react-hydration-asset.service.js +0 -210
  141. package/src/services/react-page-module.service.d.ts +0 -83
  142. package/src/services/react-page-module.service.js +0 -162
  143. package/src/services/react-runtime-bundle.service.d.ts +0 -40
  144. package/src/services/react-runtime-bundle.service.js +0 -130
  145. package/src/utils/client-graph-boundary-plugin.d.ts +0 -43
  146. package/src/utils/client-graph-boundary-plugin.js +0 -494
  147. package/src/utils/client-only.js +0 -19
  148. package/src/utils/declared-modules.js +0 -59
  149. package/src/utils/dynamic.js +0 -12
  150. package/src/utils/hmr-scripts.d.ts +0 -18
  151. package/src/utils/hmr-scripts.js +0 -31
  152. package/src/utils/html-boundary.js +0 -55
  153. package/src/utils/hydration-scripts.d.ts +0 -86
  154. package/src/utils/hydration-scripts.js +0 -285
  155. package/src/utils/reachability-analyzer.d.ts +0 -66
  156. package/src/utils/reachability-analyzer.js +0 -339
  157. package/src/utils/react-dom-runtime-interop-plugin.js +0 -29
  158. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  159. package/src/utils/react-mdx-loader-plugin.js +0 -45
  160. package/src/utils/react-runtime-specifier-map.d.ts +0 -6
  161. package/src/utils/react-runtime-specifier-map.js +0 -37
  162. package/src/utils/use-sync-external-store-shim-plugin.d.ts +0 -5
  163. package/src/utils/use-sync-external-store-shim-plugin.js +0 -41
  164. /package/src/{utils → app}/client-only.d.ts +0 -0
  165. /package/src/{utils → app}/dynamic.d.ts +0 -0
  166. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  167. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Bundle configuration service for React integration.
3
+ *
4
+ * Encapsulates all build plugin creation and bundle options
5
+ * for client-side React component builds.
6
+ *
7
+ * @module
8
+ */
9
+ import { createClientGraphBoundaryPlugin } from '../client-graph/boundary-plugin.js';
10
+ import { getReactClientGraphAllowSpecifiers, getReactRuntimeExternalSpecifiers } from './runtime-alias-map.js';
11
+ import { createBrowserRuntimePlugin } from '@ecopages/core/build';
12
+ import { getHostScopedJsxOwnershipPlugins } from '@ecopages/core/build';
13
+ import { RuntimeBundleService } from './runtime-bundle.js';
14
+ import { isReactProductionRuntime } from './runtime-mode.js';
15
+ /**
16
+ * Manages bundle configuration and plugin creation for React page/component builds.
17
+ */
18
+ export class BundleService {
19
+ runtimeBundleService;
20
+ config;
21
+ foreignJsxOverridePlugin;
22
+ runtimeRewritePlugin;
23
+ pageLayoutNormalizationVendorPromise;
24
+ mdxLoaderPlugin;
25
+ constructor(config) {
26
+ this.config = config;
27
+ this.runtimeBundleService = new RuntimeBundleService({
28
+ rootDir: config.rootDir,
29
+ routerAdapter: config.routerAdapter,
30
+ runtimeModules: config.runtimeModules,
31
+ });
32
+ [this.foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(config.appConfig, config.hostIntegrationName, { name: 'react-renderer-foreign-jsx-override' });
33
+ this.runtimeRewritePlugin = createBrowserRuntimePlugin({
34
+ name: 'react-renderer-runtime-import-rewrite',
35
+ manifest: this.runtimeBundleService.getRuntimeManifest(),
36
+ });
37
+ }
38
+ /**
39
+ * Returns resolved runtime import paths for the React runtime.
40
+ */
41
+ getRuntimeImports() {
42
+ return this.runtimeBundleService.getRuntimeImports();
43
+ }
44
+ /**
45
+ * Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
46
+ *
47
+ * @remarks
48
+ * Concurrent callers share the same in-flight promise. Asset processing itself caches
49
+ * by dependency key, so repeats after success remain cheap.
50
+ */
51
+ async ensurePageLayoutNormalizationVendorProcessed(assetProcessingService) {
52
+ if (!this.pageLayoutNormalizationVendorPromise) {
53
+ this.pageLayoutNormalizationVendorPromise = assetProcessingService
54
+ .processDependencies(this.runtimeBundleService.getPageLayoutNormalizationDependencies(), this.config.assetProcessingIntegration)
55
+ .then(() => undefined)
56
+ .catch((error) => {
57
+ this.pageLayoutNormalizationVendorPromise = undefined;
58
+ throw error;
59
+ });
60
+ }
61
+ await this.pageLayoutNormalizationVendorPromise;
62
+ }
63
+ /**
64
+ * Creates bundle options for a page or component entry.
65
+ *
66
+ * @remarks
67
+ * React derives runtime specifier mappings from the core browser runtime manifest
68
+ * so ESM imports resolve to concrete runtime asset URLs during module loading.
69
+ *
70
+ * @param componentName - Generated unique component name for output naming
71
+ * @param isMdx - Whether the source file is an MDX file
72
+ * @param declaredModules - Explicitly declared browser module specifiers
73
+ * @returns Bundle options object for the build adapter
74
+ */
75
+ async createBundleOptions(componentName, isMdx, declaredModules, bundleOptions = {}, entrypointFile, groupedEntrypointFiles, groupedDeclaredModules) {
76
+ const runtimeImports = this.getRuntimeImports();
77
+ const options = {
78
+ mainFields: ['module', 'browser', 'main'],
79
+ naming: `${componentName}.[ext]`,
80
+ ...(isReactProductionRuntime() && {
81
+ minify: true,
82
+ treeshaking: true,
83
+ }),
84
+ ...(bundleOptions.splitting === undefined ? {} : { splitting: bundleOptions.splitting }),
85
+ };
86
+ if (!bundleOptions.includeRuntime) {
87
+ const reactRuntimeSpecifiers = new Set(getReactRuntimeExternalSpecifiers());
88
+ options.external = [
89
+ ...Object.values(runtimeImports).filter((specifier) => Boolean(specifier) &&
90
+ !reactRuntimeSpecifiers.has(specifier)),
91
+ ];
92
+ }
93
+ options.plugins = this.createClientBuildPlugins({
94
+ declaredModules,
95
+ entrypointFile,
96
+ groupedEntrypointFiles,
97
+ groupedDeclaredModules,
98
+ includeRuntime: bundleOptions.includeRuntime,
99
+ isMdx,
100
+ });
101
+ return options;
102
+ }
103
+ createClientBuildPlugins(options) {
104
+ const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
105
+ projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
106
+ absWorkingDir: this.config.rootDir,
107
+ entrypointFile: options.entrypointFile,
108
+ groupedEntrypointFiles: options.groupedEntrypointFiles,
109
+ groupedDeclaredModules: options.groupedDeclaredModules,
110
+ declaredModules: options.declaredModules,
111
+ alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(this.runtimeBundleService.getConfiguredRuntimeModuleSpecifiers(), this.config.routerAdapter),
112
+ });
113
+ const runtimePlugins = options.includeRuntime
114
+ ? []
115
+ : [this.runtimeRewritePlugin].filter((plugin) => plugin !== null);
116
+ const mdxPlugin = options.isMdx ? this.getMdxLoaderPlugin() : undefined;
117
+ return [
118
+ ...(this.foreignJsxOverridePlugin ? [this.foreignJsxOverridePlugin] : []),
119
+ graphBoundaryPlugin,
120
+ ...runtimePlugins,
121
+ ...(mdxPlugin ? [mdxPlugin] : []),
122
+ ];
123
+ }
124
+ getMdxLoaderPlugin() {
125
+ if (this.mdxLoaderPlugin === undefined) {
126
+ this.mdxLoaderPlugin = this.config.getMdxLoaderPlugin?.() ?? null;
127
+ }
128
+ return this.mdxLoaderPlugin ?? undefined;
129
+ }
130
+ }
@@ -0,0 +1,12 @@
1
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
2
+ import type { ReactRuntimeImports } from './runtime-bundle.js';
3
+ import type { ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
4
+ import { type BrowserRuntimeAssetDeclaration, type BrowserRuntimeManifest } from '@ecopages/core/build';
5
+ export type BuildReactRuntimeManifestOptions = {
6
+ routerImportPath?: string;
7
+ };
8
+ export declare const REACT_RUNTIME_SPECIFIERS: readonly ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"];
9
+ export declare function buildConfiguredRuntimeModuleManifestEntries(modules: readonly ResolvedReactPluginRuntimeModule[], getPublicPath: (outputName: string) => string): BrowserRuntimeAssetDeclaration[];
10
+ export declare function buildReactRuntimeManifest(runtimeImports: ReactRuntimeImports, configuredRuntimeModules?: readonly ResolvedReactPluginRuntimeModule[], getConfiguredRuntimeModulePublicPath?: (outputName: string) => string, options?: BuildReactRuntimeManifestOptions): BrowserRuntimeManifest;
11
+ export declare function getReactRuntimeExternalSpecifiers(): string[];
12
+ export declare function getReactClientGraphAllowSpecifiers(runtimeSpecifiers: Iterable<string>, routerAdapter?: ReactRouterAdapter): string[];
@@ -0,0 +1,110 @@
1
+ import { createBrowserRuntimeManifest, } from '@ecopages/core/build';
2
+ import { LAYOUT_COMPOSE_PACKAGE } from './bootstrap-package-paths.js';
3
+ export const REACT_RUNTIME_SPECIFIERS = [
4
+ 'react',
5
+ 'react-dom',
6
+ 'react/jsx-runtime',
7
+ 'react/jsx-dev-runtime',
8
+ 'react-dom/client',
9
+ ];
10
+ export function buildConfiguredRuntimeModuleManifestEntries(modules, getPublicPath) {
11
+ return modules.map((module) => ({
12
+ specifier: module.specifier,
13
+ owner: '@ecopages/react',
14
+ importPath: module.specifier,
15
+ publicPath: getPublicPath(module.outputName),
16
+ externals: getReactRuntimeExternalSpecifiers(),
17
+ }));
18
+ }
19
+ export function buildReactRuntimeManifest(runtimeImports, configuredRuntimeModules = [], getConfiguredRuntimeModulePublicPath = () => '', options) {
20
+ const frameworkDeclarations = [
21
+ {
22
+ specifier: LAYOUT_COMPOSE_PACKAGE,
23
+ owner: '@ecopages/react',
24
+ importPath: LAYOUT_COMPOSE_PACKAGE,
25
+ publicPath: runtimeImports.layoutCompose,
26
+ },
27
+ ];
28
+ if (options?.routerImportPath && runtimeImports.router) {
29
+ frameworkDeclarations.push({
30
+ specifier: options.routerImportPath,
31
+ owner: '@ecopages/react-router',
32
+ importPath: options.routerImportPath,
33
+ publicPath: runtimeImports.router,
34
+ }, {
35
+ specifier: '@ecopages/react-router',
36
+ owner: '@ecopages/react-router',
37
+ importPath: options.routerImportPath,
38
+ publicPath: runtimeImports.router,
39
+ });
40
+ }
41
+ return createBrowserRuntimeManifest([
42
+ {
43
+ specifier: 'react',
44
+ owner: '@ecopages/react',
45
+ importPath: 'react',
46
+ publicPath: runtimeImports.react,
47
+ },
48
+ {
49
+ specifier: 'react/jsx-runtime',
50
+ owner: '@ecopages/react',
51
+ importPath: 'react/jsx-runtime',
52
+ publicPath: runtimeImports.reactJsxRuntime,
53
+ },
54
+ {
55
+ specifier: 'react/jsx-dev-runtime',
56
+ owner: '@ecopages/react',
57
+ importPath: 'react/jsx-dev-runtime',
58
+ publicPath: runtimeImports.reactJsxDevRuntime,
59
+ },
60
+ {
61
+ specifier: 'react-dom',
62
+ owner: '@ecopages/react',
63
+ importPath: 'react-dom',
64
+ publicPath: runtimeImports.reactDom,
65
+ },
66
+ {
67
+ specifier: 'react-dom/client',
68
+ owner: '@ecopages/react',
69
+ importPath: 'react-dom/client',
70
+ publicPath: runtimeImports.reactDomClient,
71
+ },
72
+ {
73
+ specifier: 'use-sync-external-store/shim',
74
+ owner: '@ecopages/react',
75
+ importPath: 'use-sync-external-store/shim',
76
+ publicPath: runtimeImports.react,
77
+ },
78
+ {
79
+ specifier: 'use-sync-external-store/shim/index.js',
80
+ owner: '@ecopages/react',
81
+ importPath: 'use-sync-external-store/shim/index.js',
82
+ publicPath: runtimeImports.react,
83
+ },
84
+ {
85
+ specifier: 'use-sync-external-store/shim/with-selector',
86
+ owner: '@ecopages/react',
87
+ importPath: 'use-sync-external-store/shim/with-selector',
88
+ publicPath: runtimeImports.useSyncExternalStoreWithSelector,
89
+ },
90
+ {
91
+ specifier: 'use-sync-external-store/shim/with-selector.js',
92
+ owner: '@ecopages/react',
93
+ importPath: 'use-sync-external-store/shim/with-selector.js',
94
+ publicPath: runtimeImports.useSyncExternalStoreWithSelector,
95
+ },
96
+ ...frameworkDeclarations,
97
+ ...buildConfiguredRuntimeModuleManifestEntries(configuredRuntimeModules, getConfiguredRuntimeModulePublicPath),
98
+ ]);
99
+ }
100
+ export function getReactRuntimeExternalSpecifiers() {
101
+ return [...REACT_RUNTIME_SPECIFIERS];
102
+ }
103
+ export function getReactClientGraphAllowSpecifiers(runtimeSpecifiers, routerAdapter) {
104
+ return [
105
+ '@ecopages/core',
106
+ ...REACT_RUNTIME_SPECIFIERS,
107
+ ...(routerAdapter ? [routerAdapter.bundle.importPath] : []),
108
+ ...Array.from(runtimeSpecifiers),
109
+ ];
110
+ }
@@ -0,0 +1,70 @@
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/integration';
10
+ import { type AssetDefinition } from '@ecopages/core/integration';
11
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
12
+ import type { ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
13
+ import { type BrowserRuntimeManifest } from '@ecopages/core/build';
14
+ export type ReactRuntimeImports = {
15
+ react: string;
16
+ reactDomClient: string;
17
+ reactJsxRuntime: string;
18
+ reactJsxDevRuntime: string;
19
+ reactDom: string;
20
+ useSyncExternalStoreWithSelector: string;
21
+ pageLayoutNormalization: string;
22
+ layoutCompose: string;
23
+ router?: string;
24
+ };
25
+ export interface RuntimeBundleServiceConfig {
26
+ routerAdapter?: ReactRouterAdapter;
27
+ runtimeModules?: ResolvedReactPluginRuntimeModule[];
28
+ rootDir?: string;
29
+ workDir?: string;
30
+ }
31
+ type RuntimeMode = 'development' | 'production';
32
+ export declare class RuntimeBundleService {
33
+ private readonly config;
34
+ constructor(config: RuntimeBundleServiceConfig);
35
+ setRootDir(rootDir: string | undefined): void;
36
+ setWorkDir(workDir: string | undefined): void;
37
+ setRuntimeModules(runtimeModules: ResolvedReactPluginRuntimeModule[]): void;
38
+ private get isDevelopment();
39
+ private getCurrentRuntimeMode;
40
+ private createRuntimeDefines;
41
+ private getVendorFileName;
42
+ private getConfiguredRuntimeModules;
43
+ getConfiguredRuntimeModuleSpecifiers(): string[];
44
+ private createReactVendorImportRewritePlugin;
45
+ getRuntimeImports(mode?: RuntimeMode): ReactRuntimeImports;
46
+ getRuntimeAliasMap(mode?: RuntimeMode): Record<string, string>;
47
+ getRuntimeManifest(mode?: RuntimeMode): BrowserRuntimeManifest;
48
+ getDependencies(options?: {
49
+ modes?: RuntimeMode[];
50
+ }): AssetDefinition[];
51
+ /**
52
+ * Declares the MDX-only page-layout-normalization vendor for the current runtime mode.
53
+ *
54
+ * @remarks
55
+ * Kept out of {@link getDependencies} so non-MDX pages do not pay for this vendor during
56
+ * integration setup. Callers process these assets once when an MDX page graph is prepared.
57
+ */
58
+ getPageLayoutNormalizationDependencies(options?: {
59
+ modes?: RuntimeMode[];
60
+ }): AssetDefinition[];
61
+ /**
62
+ * Builds the vendor import-rewrite plugin for one runtime asset.
63
+ *
64
+ * @remarks
65
+ * `omitSpecifiers` drops the module being bundled so a self-import cannot
66
+ * rewrite to the file currently being emitted.
67
+ */
68
+ createRuntimeAliasPlugin(mode?: RuntimeMode, omitSpecifiers?: readonly string[]): EcoBuildPlugin;
69
+ }
70
+ export {};
@@ -0,0 +1,233 @@
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 { createBrowserRuntimePlugin, isDevelopmentRuntime } from '@ecopages/core/build';
10
+ import { DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME } from '@ecopages/core/build';
11
+ import { buildBrowserRuntimeAssetUrl, createBrowserRuntimeModuleAsset, createBrowserRuntimeScriptAsset, } from '@ecopages/core/integration';
12
+ import { createReactDomRuntimeInteropPlugin } from './runtime-interop-plugin.js';
13
+ import { buildReactRuntimeManifest } from './runtime-alias-map.js';
14
+ import { createBrowserRuntimeManifest, getBrowserRuntimeSpecifierMap, } from '@ecopages/core/build';
15
+ import { LAYOUT_COMPOSE_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE } from './bootstrap-package-paths.js';
16
+ export class RuntimeBundleService {
17
+ config;
18
+ constructor(config) {
19
+ this.config = config;
20
+ }
21
+ setRootDir(rootDir) {
22
+ this.config.rootDir = rootDir;
23
+ }
24
+ setWorkDir(workDir) {
25
+ this.config.workDir = workDir;
26
+ }
27
+ setRuntimeModules(runtimeModules) {
28
+ this.config.runtimeModules = runtimeModules;
29
+ }
30
+ get isDevelopment() {
31
+ return isDevelopmentRuntime();
32
+ }
33
+ getCurrentRuntimeMode() {
34
+ return this.isDevelopment ? 'development' : 'production';
35
+ }
36
+ createRuntimeDefines(mode) {
37
+ const nodeEnv = JSON.stringify(mode);
38
+ return {
39
+ 'process.env.NODE_ENV': nodeEnv,
40
+ 'import.meta.env.NODE_ENV': nodeEnv,
41
+ };
42
+ }
43
+ getVendorFileName(name, mode) {
44
+ return `${name}${mode === 'development' ? '.development' : ''}.js`;
45
+ }
46
+ getConfiguredRuntimeModules() {
47
+ return this.config.runtimeModules ?? [];
48
+ }
49
+ getConfiguredRuntimeModuleSpecifiers() {
50
+ return this.getConfiguredRuntimeModules().map((module) => module.specifier);
51
+ }
52
+ createReactVendorImportRewritePlugin(mode) {
53
+ return createBrowserRuntimePlugin({
54
+ name: `react-plugin-vendor-runtime-import-rewrite-${mode}`,
55
+ manifest: createBrowserRuntimeManifest([
56
+ {
57
+ specifier: 'react',
58
+ owner: '@ecopages/react',
59
+ importPath: 'react',
60
+ publicPath: buildBrowserRuntimeAssetUrl(this.getVendorFileName('react', mode)),
61
+ },
62
+ ]),
63
+ });
64
+ }
65
+ getRuntimeImports(mode = this.getCurrentRuntimeMode()) {
66
+ const reactVendorFileName = this.getVendorFileName('react', mode);
67
+ const reactDomVendorFileName = this.getVendorFileName('react-dom', mode);
68
+ const runtimeImports = {
69
+ react: buildBrowserRuntimeAssetUrl(reactVendorFileName),
70
+ reactDomClient: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
71
+ reactJsxRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
72
+ reactJsxDevRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
73
+ reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
74
+ useSyncExternalStoreWithSelector: buildBrowserRuntimeAssetUrl(this.getVendorFileName('use-sync-external-store-with-selector', mode)),
75
+ pageLayoutNormalization: buildBrowserRuntimeAssetUrl(this.getVendorFileName('page-layout-normalization', mode)),
76
+ layoutCompose: buildBrowserRuntimeAssetUrl(this.getVendorFileName('layout-compose', mode)),
77
+ };
78
+ if (this.config.routerAdapter) {
79
+ runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getVendorFileName(this.config.routerAdapter.bundle.outputName, mode));
80
+ }
81
+ return runtimeImports;
82
+ }
83
+ getRuntimeAliasMap(mode = this.getCurrentRuntimeMode()) {
84
+ return Object.fromEntries(getBrowserRuntimeSpecifierMap(this.getRuntimeManifest(mode)));
85
+ }
86
+ getRuntimeManifest(mode = this.getCurrentRuntimeMode()) {
87
+ return buildReactRuntimeManifest(this.getRuntimeImports(mode), this.getConfiguredRuntimeModules(), (outputName) => buildBrowserRuntimeAssetUrl(this.getVendorFileName(outputName, mode)), { routerImportPath: this.config.routerAdapter?.bundle.importPath });
88
+ }
89
+ getDependencies(options) {
90
+ const dependencies = [];
91
+ const modes = options?.modes ?? [this.getCurrentRuntimeMode()];
92
+ for (const mode of modes) {
93
+ const reactVendorImportRewritePlugin = this.createReactVendorImportRewritePlugin(mode);
94
+ const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin({
95
+ reactSpecifier: buildBrowserRuntimeAssetUrl(this.getVendorFileName('react', mode)),
96
+ });
97
+ const reactRuntimeAliasPlugin = createBrowserRuntimePlugin({
98
+ name: `react-plugin-runtime-specifier-alias-${mode}`,
99
+ manifest: createBrowserRuntimeManifest([
100
+ {
101
+ specifier: 'react',
102
+ owner: '',
103
+ importPath: 'react',
104
+ publicPath: buildBrowserRuntimeAssetUrl(this.getVendorFileName('react', mode)),
105
+ },
106
+ ]),
107
+ });
108
+ const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter((plugin) => plugin !== null);
109
+ const mappedSpecifiers = new Set(this.getRuntimeManifest(mode).bySpecifier.keys());
110
+ dependencies.push(createBrowserRuntimeModuleAsset({
111
+ modules: [
112
+ { specifier: 'react', defaultExport: true },
113
+ { specifier: 'react/jsx-runtime' },
114
+ { specifier: 'react/jsx-dev-runtime' },
115
+ ],
116
+ name: 'react',
117
+ fileName: this.getVendorFileName('react', mode),
118
+ cacheDirName: `ecopages-react-runtime-${mode}`,
119
+ rootDir: this.config.rootDir,
120
+ workDir: this.config.workDir,
121
+ bundleOptions: {
122
+ define: this.createRuntimeDefines(mode),
123
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
124
+ },
125
+ }), createBrowserRuntimeModuleAsset({
126
+ modules: [{ specifier: 'react-dom', defaultExport: true }, { specifier: 'react-dom/client' }],
127
+ name: 'react-dom',
128
+ fileName: this.getVendorFileName('react-dom', mode),
129
+ cacheDirName: `ecopages-react-runtime-${mode}`,
130
+ rootDir: this.config.rootDir,
131
+ workDir: this.config.workDir,
132
+ bundleOptions: {
133
+ define: this.createRuntimeDefines(mode),
134
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
135
+ plugins: reactDomBundlePlugins,
136
+ },
137
+ }), createBrowserRuntimeScriptAsset({
138
+ importPath: '@ecopages/react/runtime/use-sync-external-store-with-selector',
139
+ name: 'use-sync-external-store-with-selector',
140
+ fileName: this.getVendorFileName('use-sync-external-store-with-selector', mode),
141
+ bundleOptions: {
142
+ define: this.createRuntimeDefines(mode),
143
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
144
+ plugins: [reactVendorImportRewritePlugin],
145
+ },
146
+ }), createBrowserRuntimeScriptAsset({
147
+ importPath: LAYOUT_COMPOSE_PACKAGE,
148
+ name: 'layout-compose',
149
+ fileName: this.getVendorFileName('layout-compose', mode),
150
+ bundleOptions: {
151
+ define: this.createRuntimeDefines(mode),
152
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
153
+ plugins: [reactVendorImportRewritePlugin],
154
+ },
155
+ }));
156
+ if (this.config.routerAdapter) {
157
+ const unresolvedExternals = this.config.routerAdapter.bundle.externals.filter((external) => !mappedSpecifiers.has(external));
158
+ dependencies.push(createBrowserRuntimeScriptAsset({
159
+ importPath: this.config.routerAdapter.bundle.importPath,
160
+ name: this.config.routerAdapter.bundle.outputName,
161
+ fileName: this.getVendorFileName(this.config.routerAdapter.bundle.outputName, mode),
162
+ bundleOptions: {
163
+ define: this.createRuntimeDefines(mode),
164
+ external: unresolvedExternals,
165
+ plugins: [
166
+ this.createRuntimeAliasPlugin(mode, [
167
+ this.config.routerAdapter.bundle.importPath,
168
+ '@ecopages/react-router',
169
+ ]),
170
+ ],
171
+ },
172
+ }));
173
+ }
174
+ for (const runtimeModule of this.getConfiguredRuntimeModules()) {
175
+ dependencies.push(createBrowserRuntimeModuleAsset({
176
+ modules: [{ specifier: runtimeModule.specifier, defaultExport: true }],
177
+ name: runtimeModule.outputName,
178
+ fileName: this.getVendorFileName(runtimeModule.outputName, mode),
179
+ cacheDirName: `ecopages-react-runtime-module-${runtimeModule.outputName}-${mode}`,
180
+ rootDir: this.config.rootDir,
181
+ workDir: this.config.workDir,
182
+ bundleOptions: {
183
+ define: this.createRuntimeDefines(mode),
184
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
185
+ plugins: [this.createRuntimeAliasPlugin(mode, [runtimeModule.specifier])],
186
+ },
187
+ }));
188
+ }
189
+ }
190
+ return dependencies;
191
+ }
192
+ /**
193
+ * Declares the MDX-only page-layout-normalization vendor for the current runtime mode.
194
+ *
195
+ * @remarks
196
+ * Kept out of {@link getDependencies} so non-MDX pages do not pay for this vendor during
197
+ * integration setup. Callers process these assets once when an MDX page graph is prepared.
198
+ */
199
+ getPageLayoutNormalizationDependencies(options) {
200
+ const dependencies = [];
201
+ const modes = options?.modes ?? [this.getCurrentRuntimeMode()];
202
+ for (const mode of modes) {
203
+ dependencies.push(createBrowserRuntimeScriptAsset({
204
+ importPath: PAGE_LAYOUT_NORMALIZATION_PACKAGE,
205
+ name: 'page-layout-normalization',
206
+ fileName: this.getVendorFileName('page-layout-normalization', mode),
207
+ bundleOptions: {
208
+ define: this.createRuntimeDefines(mode),
209
+ excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
210
+ },
211
+ }));
212
+ }
213
+ return dependencies;
214
+ }
215
+ /**
216
+ * Builds the vendor import-rewrite plugin for one runtime asset.
217
+ *
218
+ * @remarks
219
+ * `omitSpecifiers` drops the module being bundled so a self-import cannot
220
+ * rewrite to the file currently being emitted.
221
+ */
222
+ createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode(), omitSpecifiers = []) {
223
+ const manifest = this.getRuntimeManifest(mode);
224
+ const omitted = new Set(omitSpecifiers);
225
+ const pluginManifest = omitted.size === 0
226
+ ? manifest
227
+ : createBrowserRuntimeManifest(manifest.assets.filter((asset) => !omitted.has(asset.specifier)));
228
+ return createBrowserRuntimePlugin({
229
+ name: `react-plugin-runtime-alias-${mode}`,
230
+ manifest: pluginManifest,
231
+ });
232
+ }
233
+ }
@@ -1,4 +1,4 @@
1
- import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
1
+ import type { EcoBuildPlugin } from '@ecopages/core/integration';
2
2
  export declare function createReactDomRuntimeInteropPlugin(options?: {
3
3
  name?: string;
4
4
  reactSpecifier?: string;
@@ -0,0 +1,32 @@
1
+ import { fileSystem } from '@ecopages/file-system';
2
+ function escapeRegExp(value) {
3
+ return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
4
+ }
5
+ export function createReactDomRuntimeInteropPlugin(options) {
6
+ const reactDomFileFilter = /[\\/]react-dom[\\/].*\.js$/;
7
+ const reactRequirePattern = /\brequire\((['"])react\1\)/g;
8
+ const reactSpecifier = options?.reactSpecifier ?? 'react';
9
+ return {
10
+ name: options?.name ?? 'react-dom-runtime-interop',
11
+ setup(build) {
12
+ if (reactSpecifier.startsWith('/')) {
13
+ build.onResolve({ filter: new RegExp(`^${escapeRegExp(reactSpecifier)}$`) }, (args) => ({
14
+ path: args.path,
15
+ external: true,
16
+ }));
17
+ }
18
+ build.onLoad({ filter: reactDomFileFilter }, (args) => {
19
+ const content = fileSystem.readFileSync(args.path);
20
+ if (!reactRequirePattern.test(content)) {
21
+ return undefined;
22
+ }
23
+ reactRequirePattern.lastIndex = 0;
24
+ const rewritten = content.replace(reactRequirePattern, '__ecopages_react_runtime');
25
+ return {
26
+ contents: `import * as __ecopages_react_runtime from '${reactSpecifier}';\n${rewritten}`,
27
+ loader: 'js',
28
+ };
29
+ });
30
+ },
31
+ };
32
+ }
@@ -0,0 +1 @@
1
+ export declare function isReactProductionRuntime(): boolean;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Production runtime check for React bundle and hydration policy.
3
+ *
4
+ * @remarks
5
+ * Uses the same runtime mode helper as the build and request pipelines.
6
+ */
7
+ import { isProductionRuntime } from '@ecopages/core/build';
8
+ export function isReactProductionRuntime() {
9
+ return isProductionRuntime();
10
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Normalizes `reactPlugin({ runtimeModules })` entries for vendor bundling.
3
+ *
4
+ * @module
5
+ */
6
+ export type ReactPluginRuntimeModule = string | {
7
+ specifier: string;
8
+ outputName?: string;
9
+ };
10
+ export type ResolvedReactPluginRuntimeModule = {
11
+ specifier: string;
12
+ outputName: string;
13
+ };
14
+ /**
15
+ * Builds a stable vendor filename stem from a package specifier.
16
+ */
17
+ export declare function resolveReactPluginRuntimeModuleSlug(specifier: string): string;
18
+ /**
19
+ * Resolves user-facing runtime module declarations into vendor bundle config.
20
+ */
21
+ export declare function resolveReactPluginRuntimeModules(modules: ReactPluginRuntimeModule[] | undefined): ResolvedReactPluginRuntimeModule[];
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Normalizes `reactPlugin({ runtimeModules })` entries for vendor bundling.
3
+ *
4
+ * @module
5
+ */
6
+ /**
7
+ * Builds a stable vendor filename stem from a package specifier.
8
+ */
9
+ export function resolveReactPluginRuntimeModuleSlug(specifier) {
10
+ return specifier.replace(/^@/, '').replace(/\//g, '-');
11
+ }
12
+ /**
13
+ * Resolves user-facing runtime module declarations into vendor bundle config.
14
+ */
15
+ export function resolveReactPluginRuntimeModules(modules) {
16
+ return (modules ?? []).map((entry) => {
17
+ if (typeof entry === 'string') {
18
+ return {
19
+ specifier: entry,
20
+ outputName: resolveReactPluginRuntimeModuleSlug(entry),
21
+ };
22
+ }
23
+ return {
24
+ specifier: entry.specifier,
25
+ outputName: entry.outputName ?? resolveReactPluginRuntimeModuleSlug(entry.specifier),
26
+ };
27
+ });
28
+ }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Strips server-only `eco.page(...)` option keys from browser-bound modules.
3
+ */
4
+ /**
5
+ * Removes server-only `eco.page(...)` options from browser-bound modules.
6
+ */
7
+ export declare function stripServerOnlyEcoPageOptions(source: string, program: any): {
8
+ transformed: string;
9
+ modified: boolean;
10
+ };