@ecopages/react 0.2.0-beta.8 → 0.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +179 -7
- package/package.json +54 -29
- package/src/app/client-only.js +15 -0
- package/src/app/dynamic.js +9 -0
- package/src/app/dynamic.test.browser.js +31 -0
- package/src/bundling/bootstrap-package-paths.d.ts +5 -0
- package/src/bundling/bootstrap-package-paths.js +5 -0
- package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +23 -8
- package/src/bundling/bundle.js +120 -0
- package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
- package/src/bundling/discover-layout-runtime-modules.js +185 -0
- package/src/bundling/runtime-alias-map.d.ts +13 -0
- package/src/bundling/runtime-alias-map.js +113 -0
- package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +25 -4
- package/src/bundling/runtime-bundle.js +258 -0
- package/src/bundling/runtime-interop-plugin.js +34 -0
- package/src/bundling/runtime-mode.d.ts +9 -0
- package/src/bundling/runtime-mode.js +11 -0
- package/src/bundling/runtime-modules.d.ts +29 -0
- package/src/bundling/runtime-modules.js +49 -0
- package/src/client-graph/ast-transform.d.ts +18 -0
- package/src/client-graph/ast-transform.js +426 -0
- package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +23 -13
- package/src/client-graph/boundary-cache.js +182 -0
- package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
- package/src/client-graph/boundary-plugin.js +149 -0
- package/src/client-graph/component-config-traversal.js +77 -0
- package/src/client-graph/declared-modules.js +69 -0
- package/src/client-graph/module-classification.d.ts +3 -0
- package/src/client-graph/module-classification.js +43 -0
- package/src/{utils → client-graph}/reachability-analyzer.d.ts +4 -12
- package/src/client-graph/reachability-analyzer.js +515 -0
- package/src/client-graph/specifier-classification.d.ts +75 -0
- package/src/client-graph/specifier-classification.js +214 -0
- package/src/contracts/router-adapter.js +6 -0
- package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
- package/src/dev-transform/react-dev-transform-contributor.js +22 -0
- package/src/hmr/hmr-scripts.js +44 -0
- package/src/hmr/hmr-strategy.d.ts +74 -0
- package/src/hmr/hmr-strategy.js +351 -0
- package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
- package/src/hmr/page-metadata-cache.js +44 -0
- package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
- package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
- package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
- package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
- package/src/hydration/bootstrap-imports.d.ts +25 -0
- package/src/hydration/bootstrap-imports.js +33 -0
- package/src/hydration/hydration-asset.d.ts +84 -0
- package/src/hydration/hydration-asset.js +227 -0
- package/src/hydration/hydration-scripts.d.ts +104 -0
- package/src/hydration/hydration-scripts.js +483 -0
- package/src/hydration/hydration-scripts.test.browser.js +199 -0
- package/src/hydration/page-data-manifest.d.ts +58 -0
- package/src/hydration/page-data-manifest.js +97 -0
- package/src/hydration/page-data-reader.d.ts +31 -0
- package/src/hydration/page-data-reader.js +77 -0
- package/src/hydration/page-payload.d.ts +67 -0
- package/src/hydration/page-payload.js +106 -0
- package/src/hydration/serialize-page-data-script.d.ts +27 -0
- package/src/hydration/serialize-page-data-script.js +30 -0
- package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +6 -6
- package/src/mdx/mdx-config-dependency.js +110 -0
- package/src/mdx/mdx-loader-plugin.d.ts +2 -0
- package/src/mdx/mdx-loader-plugin.js +8 -0
- package/src/page/page-module.d.ts +46 -0
- package/src/page/page-module.js +74 -0
- package/src/plugin/react.constants.js +1 -0
- package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +9 -3
- package/src/plugin/react.plugin.js +241 -0
- package/src/plugin/react.types.d.ts +156 -0
- package/src/plugin/react.types.js +1 -0
- package/src/render/component-ownership.d.ts +49 -0
- package/src/render/component-ownership.js +46 -0
- package/src/render/component-ssr.d.ts +113 -0
- package/src/render/component-ssr.js +180 -0
- package/src/render/eco-embed.js +9 -0
- package/src/render/errors.d.ts +16 -0
- package/src/render/errors.js +23 -0
- package/src/render/html-boundary.js +59 -0
- package/src/render/layout-compose.d.ts +66 -0
- package/src/render/layout-compose.js +134 -0
- package/src/render/react-renderer.d.ts +138 -0
- package/src/render/react-renderer.js +448 -0
- package/src/render/react-runtime.d.ts +13 -0
- package/src/render/react-runtime.js +26 -0
- package/src/render/unified-layout-composition.d.ts +53 -0
- package/src/render/unified-layout-composition.js +78 -0
- package/src/runtime/use-sync-external-store-with-selector.js +52 -54
- package/src/eco-embed.js +0 -11
- package/src/react-hmr-strategy.d.ts +0 -230
- package/src/react-hmr-strategy.js +0 -657
- package/src/react-renderer.d.ts +0 -233
- package/src/react-renderer.js +0 -622
- package/src/react.constants.js +0 -4
- package/src/react.plugin.js +0 -209
- package/src/react.types.d.ts +0 -88
- package/src/react.types.js +0 -0
- package/src/router-adapter.js +0 -0
- package/src/services/pages-index.d.ts +0 -64
- package/src/services/pages-index.js +0 -73
- package/src/services/react-bundle.service.js +0 -86
- package/src/services/react-hmr-page-metadata-cache.js +0 -35
- package/src/services/react-hydration-asset.service.d.ts +0 -84
- package/src/services/react-hydration-asset.service.js +0 -217
- package/src/services/react-mdx-config-dependency.service.js +0 -122
- package/src/services/react-page-module.service.d.ts +0 -88
- package/src/services/react-page-module.service.js +0 -166
- package/src/services/react-page-payload.service.d.ts +0 -46
- package/src/services/react-page-payload.service.js +0 -67
- package/src/services/react-runtime-bundle.service.js +0 -192
- package/src/utils/client-graph-boundary-cache.js +0 -116
- package/src/utils/client-graph-boundary-plugin.js +0 -552
- package/src/utils/client-only.js +0 -19
- package/src/utils/component-config-traversal.js +0 -54
- package/src/utils/declared-modules.js +0 -47
- package/src/utils/dynamic.js +0 -12
- package/src/utils/dynamic.test.browser.js +0 -33
- package/src/utils/hmr-scripts.js +0 -31
- package/src/utils/html-boundary.js +0 -55
- package/src/utils/hydration-scripts.d.ts +0 -92
- package/src/utils/hydration-scripts.js +0 -358
- package/src/utils/hydration-scripts.test.browser.js +0 -198
- package/src/utils/reachability-analyzer.js +0 -339
- package/src/utils/react-dom-runtime-interop-plugin.js +0 -38
- package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
- package/src/utils/react-mdx-loader-plugin.js +0 -45
- package/src/utils/react-runtime-alias-map.d.ts +0 -8
- package/src/utils/react-runtime-alias-map.js +0 -90
- /package/src/{utils → app}/client-only.d.ts +0 -0
- /package/src/{utils → app}/dynamic.d.ts +0 -0
- /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
- /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
- /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
- /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
- /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
- /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
- /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
- /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
- /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
- /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
- /package/src/{utils → render}/html-boundary.d.ts +0 -0
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Page module loading and configuration resolution service for React integration.
|
|
3
|
+
*
|
|
4
|
+
* Handles component identity resolution and module hydration analysis.
|
|
5
|
+
* MDX page modules load through the core {@link PageModuleImportService} path
|
|
6
|
+
* using the React plugin's server build contributions.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import { type EcoComponentConfig, type EcoPageFile } from '@ecopages/core';
|
|
11
|
+
/**
|
|
12
|
+
* Configuration for the PageModuleService.
|
|
13
|
+
*/
|
|
14
|
+
export interface PageModuleServiceConfig {
|
|
15
|
+
layoutsDir?: string;
|
|
16
|
+
componentsDir?: string;
|
|
17
|
+
mdxExtensions: string[];
|
|
18
|
+
integrationName: string;
|
|
19
|
+
hasRouterAdapter: boolean;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Manages page module metadata resolution and hydration analysis for React pages.
|
|
23
|
+
*/
|
|
24
|
+
export declare class PageModuleService {
|
|
25
|
+
private readonly config;
|
|
26
|
+
constructor(config: PageModuleServiceConfig);
|
|
27
|
+
/**
|
|
28
|
+
* Checks if the given file path corresponds to an MDX file based on configured extensions.
|
|
29
|
+
*/
|
|
30
|
+
isMdxFile(filePath: string): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Ensures that an EcoComponentConfig has canonical identity attached.
|
|
33
|
+
*/
|
|
34
|
+
ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig;
|
|
35
|
+
hasModulesInConfig(config: EcoComponentConfig | undefined): boolean;
|
|
36
|
+
shouldHydratePage(pageModule: EcoPageFile<{
|
|
37
|
+
config?: EcoComponentConfig;
|
|
38
|
+
}> & {
|
|
39
|
+
config?: EcoComponentConfig;
|
|
40
|
+
}): boolean;
|
|
41
|
+
collectPageDeclaredModules(pageModule: EcoPageFile<{
|
|
42
|
+
config?: EcoComponentConfig;
|
|
43
|
+
}> & {
|
|
44
|
+
config?: EcoComponentConfig;
|
|
45
|
+
}): string[];
|
|
46
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Page module loading and configuration resolution service for React integration.
|
|
3
|
+
*
|
|
4
|
+
* Handles component identity resolution and module hydration analysis.
|
|
5
|
+
* MDX page modules load through the core {@link PageModuleImportService} path
|
|
6
|
+
* using the React plugin's server build contributions.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import path from 'node:path';
|
|
11
|
+
import { bindComponentIdentity, getComponentIdentity } from '@ecopages/core';
|
|
12
|
+
import { rapidhash } from '@ecopages/core/hash';
|
|
13
|
+
import { fileSystem } from '@ecopages/file-system';
|
|
14
|
+
import { someInConfigTree } from '../client-graph/component-config-traversal.js';
|
|
15
|
+
import { collectPageDeclaredModulesFromModule } from '../client-graph/declared-modules.js';
|
|
16
|
+
/**
|
|
17
|
+
* Manages page module metadata resolution and hydration analysis for React pages.
|
|
18
|
+
*/
|
|
19
|
+
export class PageModuleService {
|
|
20
|
+
config;
|
|
21
|
+
constructor(config) {
|
|
22
|
+
this.config = config;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Checks if the given file path corresponds to an MDX file based on configured extensions.
|
|
26
|
+
*/
|
|
27
|
+
isMdxFile(filePath) {
|
|
28
|
+
return this.config.mdxExtensions.some((ext) => filePath.endsWith(ext));
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Ensures that an EcoComponentConfig has canonical identity attached.
|
|
32
|
+
*/
|
|
33
|
+
ensureConfigFileMetadata(config, pagePath) {
|
|
34
|
+
const identity = getComponentIdentity(config);
|
|
35
|
+
if (identity?.file) {
|
|
36
|
+
return config;
|
|
37
|
+
}
|
|
38
|
+
const buildIdentity = (file) => ({
|
|
39
|
+
id: identity?.id ?? rapidhash(file).toString(36),
|
|
40
|
+
integration: identity?.integration ?? this.config.integrationName,
|
|
41
|
+
file,
|
|
42
|
+
});
|
|
43
|
+
const resolveDependencyValue = (value) => typeof value === 'string' ? value : value.src;
|
|
44
|
+
const dependencyPaths = [
|
|
45
|
+
...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
|
|
46
|
+
...(config.dependencies?.scripts ?? []).map(resolveDependencyValue),
|
|
47
|
+
]
|
|
48
|
+
.filter((value) => Boolean(value))
|
|
49
|
+
.filter((value) => value.startsWith('./') || value.startsWith('../'));
|
|
50
|
+
const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter((value) => typeof value === 'string' && value.length > 0);
|
|
51
|
+
for (const dependencyPath of dependencyPaths) {
|
|
52
|
+
for (const candidateDir of candidateDirs) {
|
|
53
|
+
const resolvedDependency = path.resolve(candidateDir, dependencyPath);
|
|
54
|
+
if (fileSystem.exists(resolvedDependency)) {
|
|
55
|
+
return bindComponentIdentity(buildIdentity(path.join(candidateDir, path.basename(pagePath))), config);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return bindComponentIdentity(buildIdentity(pagePath), config);
|
|
60
|
+
}
|
|
61
|
+
hasModulesInConfig(config) {
|
|
62
|
+
return someInConfigTree(config, (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false);
|
|
63
|
+
}
|
|
64
|
+
shouldHydratePage(pageModule) {
|
|
65
|
+
if (this.config.hasRouterAdapter) {
|
|
66
|
+
return true;
|
|
67
|
+
}
|
|
68
|
+
const pageConfig = pageModule.default?.config;
|
|
69
|
+
return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
|
|
70
|
+
}
|
|
71
|
+
collectPageDeclaredModules(pageModule) {
|
|
72
|
+
return collectPageDeclaredModulesFromModule(pageModule);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const REACT_PLUGIN_NAME = 'react';
|
|
@@ -2,7 +2,7 @@ import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/i
|
|
|
2
2
|
import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
|
|
3
3
|
import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
|
|
4
4
|
import type React from 'react';
|
|
5
|
-
import { ReactRenderer } from '
|
|
5
|
+
import { ReactRenderer } from '../render/react-renderer.js';
|
|
6
6
|
import type { ReactPluginOptions } from './react.types.js';
|
|
7
7
|
export type { ReactMdxOptions, ReactPluginOptions, ReactRendererConfig } from './react.types.js';
|
|
8
8
|
/**
|
|
@@ -23,11 +23,15 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
|
|
|
23
23
|
private readonly runtimeBundleService;
|
|
24
24
|
private readonly hmrPageMetadataCache;
|
|
25
25
|
private readonly clientGraphBoundaryCache;
|
|
26
|
+
private hmrStrategy?;
|
|
26
27
|
private runtimeDependenciesInitialized;
|
|
27
28
|
/**
|
|
28
|
-
*
|
|
29
|
+
* When true, always emit page browser graph / hydration assets.
|
|
30
|
+
*
|
|
31
|
+
* @remarks
|
|
32
|
+
* Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
|
|
29
33
|
*/
|
|
30
|
-
private readonly
|
|
34
|
+
private readonly forceBrowserGraph;
|
|
31
35
|
private readonly rendererConfig;
|
|
32
36
|
constructor(options?: ReactPluginOptions);
|
|
33
37
|
/**
|
|
@@ -41,6 +45,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
|
|
|
41
45
|
rendererModules?: unknown;
|
|
42
46
|
}): ReactRenderer;
|
|
43
47
|
private ensureRuntimeDependencies;
|
|
48
|
+
private resolveEffectiveRuntimeModules;
|
|
44
49
|
get plugins(): EcoBuildPlugin[];
|
|
45
50
|
get browserRuntimeManifest(): BrowserRuntimeManifest;
|
|
46
51
|
/**
|
|
@@ -67,6 +72,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
|
|
|
67
72
|
*
|
|
68
73
|
* @returns ReactHmrStrategy instance for handling React component updates
|
|
69
74
|
*/
|
|
75
|
+
setHmrManager(hmrManager: NonNullable<IntegrationPlugin['hmrManager']>): void;
|
|
70
76
|
getHmrStrategy(): HmrStrategy | undefined;
|
|
71
77
|
}
|
|
72
78
|
/**
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import { IntegrationPlugin, } from '@ecopages/core/plugins/integration-plugin';
|
|
2
|
+
import { Logger } from '@ecopages/logger';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { REACT_PLUGIN_NAME } from './react.constants.js';
|
|
5
|
+
import { ReactRenderer } from '../render/react-renderer.js';
|
|
6
|
+
import { ReactHmrStrategy } from '../hmr/hmr-strategy.js';
|
|
7
|
+
import { ReactDevTransformContributor } from '../dev-transform/react-dev-transform-contributor.js';
|
|
8
|
+
import { RuntimeBundleService } from '../bundling/runtime-bundle.js';
|
|
9
|
+
import { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
|
|
10
|
+
import { createReactMdxLoaderPlugin } from '../mdx/mdx-loader-plugin.js';
|
|
11
|
+
import { appendMdxExtensions, resolveMdxCompilerOptions } from '@ecopages/mdx/core';
|
|
12
|
+
import { ClientGraphBoundaryCache } from '../client-graph/boundary-cache.js';
|
|
13
|
+
import { discoverLayoutRuntimeModuleSpecifiers } from '../bundling/discover-layout-runtime-modules.js';
|
|
14
|
+
import { mergeReactPluginRuntimeModules, resolveReactPluginRuntimeModules } from '../bundling/runtime-modules.js';
|
|
15
|
+
const appLogger = new Logger('[ReactPlugin]');
|
|
16
|
+
/**
|
|
17
|
+
* The name of the React plugin
|
|
18
|
+
*/
|
|
19
|
+
export const PLUGIN_NAME = REACT_PLUGIN_NAME;
|
|
20
|
+
const resolveReactMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptions(mdxOptions, { jsxImportSource: 'react' });
|
|
21
|
+
/**
|
|
22
|
+
* Resolves user-facing React plugin options into the internal plugin config.
|
|
23
|
+
*
|
|
24
|
+
* Defaults:
|
|
25
|
+
* - `extensions`: `['.tsx']`
|
|
26
|
+
* - `explicitGraph`: `false`
|
|
27
|
+
* - `mdx.enabled`: `false`
|
|
28
|
+
* - `mdx.extensions`: `['.mdx']`
|
|
29
|
+
*/
|
|
30
|
+
const resolveReactPluginOptions = (options) => {
|
|
31
|
+
const { extensions: userExtensions, router, mdx, explicitGraph, dependencies, runtimeModules, ...baseConfig } = options ?? {};
|
|
32
|
+
const extensions = [...(userExtensions ?? ['.tsx'])];
|
|
33
|
+
const mdxEnabled = mdx?.enabled ?? false;
|
|
34
|
+
const mdxExtensions = mdx?.extensions ?? ['.mdx'];
|
|
35
|
+
const resolvedRuntimeModules = resolveReactPluginRuntimeModules(runtimeModules);
|
|
36
|
+
if (mdxEnabled) {
|
|
37
|
+
appendMdxExtensions(extensions, mdxExtensions);
|
|
38
|
+
}
|
|
39
|
+
else if (mdx?.extensions?.length) {
|
|
40
|
+
appLogger.warn('MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support.');
|
|
41
|
+
}
|
|
42
|
+
const rendererConfig = {
|
|
43
|
+
routerAdapter: router,
|
|
44
|
+
runtimeModules: resolvedRuntimeModules,
|
|
45
|
+
mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : undefined,
|
|
46
|
+
mdxExtensions,
|
|
47
|
+
hmrPageMetadataCache: new HmrPageMetadataCache(),
|
|
48
|
+
forceBrowserGraph: explicitGraph ?? false,
|
|
49
|
+
};
|
|
50
|
+
return {
|
|
51
|
+
...baseConfig,
|
|
52
|
+
extensions,
|
|
53
|
+
integrationDependencies: dependencies,
|
|
54
|
+
rendererConfig,
|
|
55
|
+
};
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* The React plugin class
|
|
59
|
+
* This plugin provides support for React components in Ecopages
|
|
60
|
+
*/
|
|
61
|
+
export class ReactPlugin extends IntegrationPlugin {
|
|
62
|
+
renderer = ReactRenderer;
|
|
63
|
+
routerAdapter;
|
|
64
|
+
mdxEnabled;
|
|
65
|
+
mdxCompilerOptions;
|
|
66
|
+
mdxExtensions;
|
|
67
|
+
mdxLoaderPlugin;
|
|
68
|
+
runtimeBundleService;
|
|
69
|
+
hmrPageMetadataCache;
|
|
70
|
+
clientGraphBoundaryCache;
|
|
71
|
+
hmrStrategy;
|
|
72
|
+
runtimeDependenciesInitialized = false;
|
|
73
|
+
/**
|
|
74
|
+
* When true, always emit page browser graph / hydration assets.
|
|
75
|
+
*
|
|
76
|
+
* @remarks
|
|
77
|
+
* Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
|
|
78
|
+
*/
|
|
79
|
+
forceBrowserGraph;
|
|
80
|
+
rendererConfig;
|
|
81
|
+
constructor(options) {
|
|
82
|
+
const config = resolveReactPluginOptions(options);
|
|
83
|
+
const { extensions, rendererConfig, integrationDependencies, ...baseConfig } = config;
|
|
84
|
+
super({
|
|
85
|
+
name: PLUGIN_NAME,
|
|
86
|
+
extensions,
|
|
87
|
+
jsxImportSource: 'react',
|
|
88
|
+
integrationDependencies,
|
|
89
|
+
...baseConfig,
|
|
90
|
+
});
|
|
91
|
+
this.routerAdapter = rendererConfig.routerAdapter;
|
|
92
|
+
this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
|
|
93
|
+
this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
|
|
94
|
+
this.mdxExtensions = rendererConfig.mdxExtensions ?? ['.mdx'];
|
|
95
|
+
this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new HmrPageMetadataCache();
|
|
96
|
+
this.clientGraphBoundaryCache = new ClientGraphBoundaryCache();
|
|
97
|
+
this.forceBrowserGraph = rendererConfig.forceBrowserGraph ?? false;
|
|
98
|
+
this.rendererConfig = {
|
|
99
|
+
...rendererConfig,
|
|
100
|
+
mdxExtensions: this.mdxExtensions,
|
|
101
|
+
hmrPageMetadataCache: this.hmrPageMetadataCache,
|
|
102
|
+
forceBrowserGraph: this.forceBrowserGraph,
|
|
103
|
+
clientGraphBoundaryCache: this.clientGraphBoundaryCache,
|
|
104
|
+
};
|
|
105
|
+
if (this.mdxEnabled) {
|
|
106
|
+
appLogger.debug('MDX mode enabled with React jsx runtime');
|
|
107
|
+
}
|
|
108
|
+
this.runtimeBundleService = new RuntimeBundleService({
|
|
109
|
+
routerAdapter: this.routerAdapter,
|
|
110
|
+
runtimeModules: this.rendererConfig.runtimeModules,
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Creates a React renderer with instance-owned runtime configuration.
|
|
115
|
+
*
|
|
116
|
+
* React renderers depend on plugin-owned router, MDX, and HMR metadata state.
|
|
117
|
+
* Keeping that state on the instance avoids cross-plugin static mutation while
|
|
118
|
+
* preserving the same runtime services the base initializer wires up.
|
|
119
|
+
*/
|
|
120
|
+
initializeRenderer(options) {
|
|
121
|
+
const renderer = new this.renderer({
|
|
122
|
+
...this.createRendererOptions(options),
|
|
123
|
+
reactConfig: this.rendererConfig,
|
|
124
|
+
});
|
|
125
|
+
return this.attachRendererRuntimeServices(renderer);
|
|
126
|
+
}
|
|
127
|
+
ensureRuntimeDependencies() {
|
|
128
|
+
if (this.runtimeDependenciesInitialized) {
|
|
129
|
+
return;
|
|
130
|
+
}
|
|
131
|
+
this.runtimeBundleService.setRootDir(this.appConfig?.rootDir);
|
|
132
|
+
this.runtimeBundleService.setWorkDir(this.appConfig?.absolutePaths?.workDir ??
|
|
133
|
+
(this.appConfig?.rootDir
|
|
134
|
+
? path.join(this.appConfig.rootDir, this.appConfig.workDir ?? '.eco')
|
|
135
|
+
: undefined));
|
|
136
|
+
this.runtimeBundleService.setRuntimeModules(this.resolveEffectiveRuntimeModules());
|
|
137
|
+
this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
|
|
138
|
+
this.runtimeDependenciesInitialized = true;
|
|
139
|
+
}
|
|
140
|
+
resolveEffectiveRuntimeModules() {
|
|
141
|
+
const manualModules = this.rendererConfig.runtimeModules ?? [];
|
|
142
|
+
if (!this.routerAdapter || !this.appConfig) {
|
|
143
|
+
return manualModules;
|
|
144
|
+
}
|
|
145
|
+
const discovery = discoverLayoutRuntimeModuleSpecifiers({
|
|
146
|
+
searchDirs: [this.appConfig.absolutePaths.layoutsDir, this.appConfig.absolutePaths.componentsDir].filter(Boolean),
|
|
147
|
+
projectRoot: this.appConfig.absolutePaths.projectDir,
|
|
148
|
+
routerImportPath: this.routerAdapter.bundle.importPath,
|
|
149
|
+
});
|
|
150
|
+
const merged = mergeReactPluginRuntimeModules(manualModules, discovery.specifiers);
|
|
151
|
+
this.rendererConfig.runtimeModules = merged;
|
|
152
|
+
if (discovery.mode === 'provider-scoped-fallback') {
|
|
153
|
+
appLogger.debug('Layout runtime auto-vendoring is using provider-scoped fallback discovery. Set runtimeProvider: true on provider root layouts to scope discovery explicitly.');
|
|
154
|
+
}
|
|
155
|
+
if (discovery.specifiers.length > 0) {
|
|
156
|
+
appLogger.debug(`Auto-vendoring layout runtime modules for persisted SPA layouts: ${discovery.specifiers.join(', ')}`);
|
|
157
|
+
}
|
|
158
|
+
return merged;
|
|
159
|
+
}
|
|
160
|
+
get plugins() {
|
|
161
|
+
if (this.mdxLoaderPlugin) {
|
|
162
|
+
return [this.mdxLoaderPlugin];
|
|
163
|
+
}
|
|
164
|
+
return [];
|
|
165
|
+
}
|
|
166
|
+
get browserRuntimeManifest() {
|
|
167
|
+
this.ensureRuntimeDependencies();
|
|
168
|
+
return this.runtimeBundleService.getRuntimeManifest();
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Ensures the optional React MDX loader exists before either config-time
|
|
172
|
+
* manifest sealing or runtime setup needs it.
|
|
173
|
+
*/
|
|
174
|
+
async ensureMdxLoaderPlugin() {
|
|
175
|
+
if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
|
|
176
|
+
return;
|
|
177
|
+
}
|
|
178
|
+
this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Prepares React's build-facing loader contributions before config build seals
|
|
182
|
+
* the app manifest.
|
|
183
|
+
*/
|
|
184
|
+
async prepareBuildContributions() {
|
|
185
|
+
this.ensureRuntimeDependencies();
|
|
186
|
+
await this.ensureMdxLoaderPlugin();
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* Performs runtime-only React setup after build contributions are already
|
|
190
|
+
* materialized.
|
|
191
|
+
*/
|
|
192
|
+
async setup() {
|
|
193
|
+
this.ensureRuntimeDependencies();
|
|
194
|
+
await this.ensureMdxLoaderPlugin();
|
|
195
|
+
await super.setup();
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Provides React-specific HMR strategy with Fast Refresh support.
|
|
199
|
+
*
|
|
200
|
+
* The strategy shares a React-only page metadata cache with the renderer so
|
|
201
|
+
* save-time rebuilds can reuse declared-module analysis without expanding the
|
|
202
|
+
* core HMR interfaces.
|
|
203
|
+
*
|
|
204
|
+
* @returns ReactHmrStrategy instance for handling React component updates
|
|
205
|
+
*/
|
|
206
|
+
setHmrManager(hmrManager) {
|
|
207
|
+
super.setHmrManager(hmrManager);
|
|
208
|
+
const strategy = this.getHmrStrategy();
|
|
209
|
+
if (!strategy || !this.appConfig) {
|
|
210
|
+
return;
|
|
211
|
+
}
|
|
212
|
+
hmrManager.registerDevTransformContributor(new ReactDevTransformContributor({
|
|
213
|
+
strategy: strategy,
|
|
214
|
+
}));
|
|
215
|
+
}
|
|
216
|
+
getHmrStrategy() {
|
|
217
|
+
if (!this.hmrManager || !this.appConfig) {
|
|
218
|
+
return undefined;
|
|
219
|
+
}
|
|
220
|
+
if (!this.hmrStrategy) {
|
|
221
|
+
this.hmrStrategy = new ReactHmrStrategy({
|
|
222
|
+
context: this.hmrManager.getDefaultContext(),
|
|
223
|
+
pageMetadataCache: this.hmrPageMetadataCache,
|
|
224
|
+
runtimeManifest: this.runtimeBundleService.getRuntimeManifest('development'),
|
|
225
|
+
mdxCompilerOptions: this.mdxCompilerOptions,
|
|
226
|
+
ownedTemplateExtensions: this.extensions,
|
|
227
|
+
allTemplateExtensions: this.appConfig.templatesExt,
|
|
228
|
+
clientGraphBoundaryCache: this.clientGraphBoundaryCache,
|
|
229
|
+
});
|
|
230
|
+
}
|
|
231
|
+
return this.hmrStrategy;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* Factory function to create a React plugin instance
|
|
236
|
+
* @param options Configuration options for the React plugin
|
|
237
|
+
* @returns A new ReactPlugin instance
|
|
238
|
+
*/
|
|
239
|
+
export function reactPlugin(options) {
|
|
240
|
+
return new ReactPlugin(options);
|
|
241
|
+
}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
|
|
2
|
+
import type { CompileOptions } from '@mdx-js/mdx';
|
|
3
|
+
import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
|
|
4
|
+
import type { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
|
|
5
|
+
import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from '../bundling/runtime-modules.js';
|
|
6
|
+
import type { ClientGraphBoundaryCache } from '../client-graph/boundary-cache.js';
|
|
7
|
+
/**
|
|
8
|
+
* MDX configuration options for the React plugin.
|
|
9
|
+
*/
|
|
10
|
+
export type ReactMdxOptions = {
|
|
11
|
+
/**
|
|
12
|
+
* Whether to enable MDX support.
|
|
13
|
+
* @default false
|
|
14
|
+
*/
|
|
15
|
+
enabled: boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Compiler options for MDX.
|
|
18
|
+
* @default undefined
|
|
19
|
+
*/
|
|
20
|
+
compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
|
|
21
|
+
/**
|
|
22
|
+
* Remark plugins.
|
|
23
|
+
* @default undefined
|
|
24
|
+
*/
|
|
25
|
+
remarkPlugins?: CompileOptions['remarkPlugins'];
|
|
26
|
+
/**
|
|
27
|
+
* Rehype plugins.
|
|
28
|
+
* @default undefined
|
|
29
|
+
*/
|
|
30
|
+
rehypePlugins?: CompileOptions['rehypePlugins'];
|
|
31
|
+
/**
|
|
32
|
+
* Recma plugins.
|
|
33
|
+
* @default undefined
|
|
34
|
+
*/
|
|
35
|
+
recmaPlugins?: CompileOptions['recmaPlugins'];
|
|
36
|
+
/**
|
|
37
|
+
* Custom extensions to be treated as MDX files.
|
|
38
|
+
* @default ['.mdx']
|
|
39
|
+
*/
|
|
40
|
+
extensions?: string[];
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* Options for the React plugin.
|
|
44
|
+
*/
|
|
45
|
+
export type ReactPluginOptions = {
|
|
46
|
+
extensions?: string[];
|
|
47
|
+
dependencies?: AssetDefinition[];
|
|
48
|
+
/**
|
|
49
|
+
* When true, always emit the page browser graph / hydration assets for React
|
|
50
|
+
* page entries, even when the page does not declare `dependencies.modules`
|
|
51
|
+
* and no router adapter is configured.
|
|
52
|
+
*
|
|
53
|
+
* @remarks
|
|
54
|
+
* This does not skip the client-graph AST boundary. Server-only
|
|
55
|
+
* `eco.page(...)` options such as `middleware` and `requires` are still
|
|
56
|
+
* stripped from browser bundles.
|
|
57
|
+
*
|
|
58
|
+
* With a router adapter, page hydration is already always enabled, so this
|
|
59
|
+
* option is redundant for SPA apps.
|
|
60
|
+
*
|
|
61
|
+
* @default false
|
|
62
|
+
*/
|
|
63
|
+
explicitGraph?: boolean;
|
|
64
|
+
/**
|
|
65
|
+
* Router adapter for SPA navigation.
|
|
66
|
+
* When provided, pages with layouts will be wrapped in the router for client-side navigation.
|
|
67
|
+
* @example
|
|
68
|
+
* ```ts
|
|
69
|
+
* import { ecoRouter } from '@ecopages/react-router';
|
|
70
|
+
* reactPlugin({ router: ecoRouter() })
|
|
71
|
+
* ```
|
|
72
|
+
*/
|
|
73
|
+
router?: ReactRouterAdapter;
|
|
74
|
+
/**
|
|
75
|
+
* Optional shared browser runtime vendors.
|
|
76
|
+
*
|
|
77
|
+
* With `router`, npm packages reachable from `eco.layout()` **render graphs**
|
|
78
|
+
* under the app's configured `layouts/` and `components/` directories are
|
|
79
|
+
* discovered automatically and registered as shared vendors (alongside React
|
|
80
|
+
* and React DOM). This prevents duplicate module instances when persisted
|
|
81
|
+
* layouts stay mounted across SPA navigation.
|
|
82
|
+
*
|
|
83
|
+
* Without `router`, only explicit entries here are vendored.
|
|
84
|
+
*
|
|
85
|
+
* @remarks
|
|
86
|
+
* Discovery follows client reachability from each layout's `render` path,
|
|
87
|
+
* resolves relative and tsconfig path aliases, and collects npm package roots
|
|
88
|
+
* imported from provider/context modules in that graph (for example files named
|
|
89
|
+
* `query-provider.tsx` or modules using `QueryClientProvider` / `createContext`).
|
|
90
|
+
* It does not vendor every npm dependency reachable from shell or page UI.
|
|
91
|
+
*
|
|
92
|
+
* Layouts that mount shared runtime state should set `runtimeProvider: true` in
|
|
93
|
+
* `eco.layout({ ... })`. Flagged layouts become the only discovery roots and
|
|
94
|
+
* vendor every reachable npm package in that layout graph. When no layout opts
|
|
95
|
+
* in, discovery falls back to scanning all layouts with provider-scoped npm
|
|
96
|
+
* collection.
|
|
97
|
+
*
|
|
98
|
+
* @example
|
|
99
|
+
* ```ts
|
|
100
|
+
* export const QueryRootLayout = eco.layout({
|
|
101
|
+
* runtimeProvider: true,
|
|
102
|
+
* render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
|
|
103
|
+
* });
|
|
104
|
+
*
|
|
105
|
+
* reactPlugin({
|
|
106
|
+
* router: ecoRouter(),
|
|
107
|
+
* });
|
|
108
|
+
* ```
|
|
109
|
+
*
|
|
110
|
+
* Manual entries override auto-discovered entries for the same specifier.
|
|
111
|
+
* Subpath imports such as `@acme/ui/button` dedupe to the registered package
|
|
112
|
+
* root vendor URL when `@acme/ui` is configured here or auto-discovered.
|
|
113
|
+
*
|
|
114
|
+
* @example Advanced vendor config
|
|
115
|
+
* ```ts
|
|
116
|
+
* runtimeModules: [
|
|
117
|
+
* { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] },
|
|
118
|
+
* ]
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
runtimeModules?: ReactPluginRuntimeModule[];
|
|
122
|
+
/**
|
|
123
|
+
* MDX configuration for handling .mdx files within the React plugin.
|
|
124
|
+
* When enabled, MDX files are treated as React pages with full router support.
|
|
125
|
+
* @example
|
|
126
|
+
* ```ts
|
|
127
|
+
* reactPlugin({
|
|
128
|
+
* router: ecoRouter(),
|
|
129
|
+
* mdx: {
|
|
130
|
+
* enabled: true,
|
|
131
|
+
* extensions: ['.mdx', '.md'],
|
|
132
|
+
* remarkPlugins: [remarkGfm],
|
|
133
|
+
* rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
|
|
134
|
+
* }
|
|
135
|
+
* })
|
|
136
|
+
* ```
|
|
137
|
+
*/
|
|
138
|
+
mdx?: ReactMdxOptions;
|
|
139
|
+
};
|
|
140
|
+
export type ReactRendererConfig = {
|
|
141
|
+
routerAdapter?: ReactRouterAdapter;
|
|
142
|
+
runtimeModules?: ResolvedReactPluginRuntimeModule[];
|
|
143
|
+
mdxCompilerOptions?: CompileOptions;
|
|
144
|
+
mdxExtensions?: string[];
|
|
145
|
+
hmrPageMetadataCache?: HmrPageMetadataCache;
|
|
146
|
+
/** Persistent React-plugin-owned cache shared by bundles and HMR transforms. */
|
|
147
|
+
clientGraphBoundaryCache?: ClientGraphBoundaryCache;
|
|
148
|
+
/**
|
|
149
|
+
* When true, always emit page browser graph / hydration assets for React pages.
|
|
150
|
+
*
|
|
151
|
+
* @remarks
|
|
152
|
+
* Mapped from the public `explicitGraph` plugin option. Does not skip the
|
|
153
|
+
* client-graph AST strip of server-only `eco.page(...)` options.
|
|
154
|
+
*/
|
|
155
|
+
forceBrowserGraph?: boolean;
|
|
156
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ownership helpers for deciding whether a component stays in the React render lane.
|
|
3
|
+
*/
|
|
4
|
+
import type { EcoComponent, EcoComponentConfig, EcoPagesElement } from '@ecopages/core';
|
|
5
|
+
import type { FunctionComponent } from 'react';
|
|
6
|
+
export type SerializableProps = Record<string, unknown>;
|
|
7
|
+
export type ReactRenderableComponent<P extends SerializableProps = SerializableProps> = FunctionComponent<P> & {
|
|
8
|
+
config?: EcoComponentConfig;
|
|
9
|
+
requires?: string | readonly string[];
|
|
10
|
+
};
|
|
11
|
+
export type RequiresAwareComponent = {
|
|
12
|
+
requires?: string | readonly string[];
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* Reads the declared integration name for a component or layout.
|
|
16
|
+
*
|
|
17
|
+
* @remarks
|
|
18
|
+
* Honors both the explicit `config.integration` override and build-time
|
|
19
|
+
* `getComponentIdentity(component)?.integration` attribution.
|
|
20
|
+
*/
|
|
21
|
+
export declare function getComponentIntegration(component?: {
|
|
22
|
+
config?: EcoComponentConfig;
|
|
23
|
+
} | null): string | undefined;
|
|
24
|
+
/**
|
|
25
|
+
* Returns whether a component should stay inside the React render lane.
|
|
26
|
+
*
|
|
27
|
+
* @remarks
|
|
28
|
+
* Components without explicit integration metadata are treated as React-owned
|
|
29
|
+
* because this renderer only receives them after the route pipeline has already
|
|
30
|
+
* selected the React integration.
|
|
31
|
+
*/
|
|
32
|
+
export declare function isReactManagedComponent(component: {
|
|
33
|
+
config?: EcoComponentConfig;
|
|
34
|
+
} | null | undefined, reactIntegrationName: string): boolean;
|
|
35
|
+
export declare function getComponentRequires(component?: (EcoComponent & RequiresAwareComponent) | null): string | readonly string[] | undefined;
|
|
36
|
+
/**
|
|
37
|
+
* Commits a framework-agnostic component to React semantics.
|
|
38
|
+
*
|
|
39
|
+
* @remarks
|
|
40
|
+
* Core keeps `EcoComponent` broad so integrations can share the same public surface;
|
|
41
|
+
* once the React renderer is executing, `createElement()` needs a concrete React
|
|
42
|
+
* component signature.
|
|
43
|
+
*/
|
|
44
|
+
export declare function asReactComponent<P extends SerializableProps>(component: unknown): ReactRenderableComponent<P>;
|
|
45
|
+
/**
|
|
46
|
+
* Commits a mixed-shell component to the string-returning contract required by
|
|
47
|
+
* non-React layouts and HTML templates.
|
|
48
|
+
*/
|
|
49
|
+
export declare function asNonReactShellComponent<P extends SerializableProps>(component: unknown): (props: P) => EcoPagesElement | Promise<EcoPagesElement>;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ownership helpers for deciding whether a component stays in the React render lane.
|
|
3
|
+
*/
|
|
4
|
+
/**
|
|
5
|
+
* Reads the declared integration name for a component or layout.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Honors both the explicit `config.integration` override and build-time
|
|
9
|
+
* `getComponentIdentity(component)?.integration` attribution.
|
|
10
|
+
*/
|
|
11
|
+
export function getComponentIntegration(component) {
|
|
12
|
+
return component?.config?.integration ?? component?.config?.identity?.integration;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Returns whether a component should stay inside the React render lane.
|
|
16
|
+
*
|
|
17
|
+
* @remarks
|
|
18
|
+
* Components without explicit integration metadata are treated as React-owned
|
|
19
|
+
* because this renderer only receives them after the route pipeline has already
|
|
20
|
+
* selected the React integration.
|
|
21
|
+
*/
|
|
22
|
+
export function isReactManagedComponent(component, reactIntegrationName) {
|
|
23
|
+
const integration = getComponentIntegration(component);
|
|
24
|
+
return integration === undefined || integration === reactIntegrationName;
|
|
25
|
+
}
|
|
26
|
+
export function getComponentRequires(component) {
|
|
27
|
+
return component?.requires;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Commits a framework-agnostic component to React semantics.
|
|
31
|
+
*
|
|
32
|
+
* @remarks
|
|
33
|
+
* Core keeps `EcoComponent` broad so integrations can share the same public surface;
|
|
34
|
+
* once the React renderer is executing, `createElement()` needs a concrete React
|
|
35
|
+
* component signature.
|
|
36
|
+
*/
|
|
37
|
+
export function asReactComponent(component) {
|
|
38
|
+
return component;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Commits a mixed-shell component to the string-returning contract required by
|
|
42
|
+
* non-React layouts and HTML templates.
|
|
43
|
+
*/
|
|
44
|
+
export function asNonReactShellComponent(component) {
|
|
45
|
+
return component;
|
|
46
|
+
}
|