@ecopages/react 0.2.0-beta.9 → 0.2.0-rc.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 (142) hide show
  1. package/README.md +179 -7
  2. package/package.json +53 -28
  3. package/src/app/client-only.js +15 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/app/dynamic.test.browser.js +31 -0
  6. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  7. package/src/bundling/bootstrap-package-paths.js +5 -0
  8. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +23 -8
  9. package/src/bundling/bundle.js +120 -0
  10. package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
  11. package/src/bundling/discover-layout-runtime-modules.js +185 -0
  12. package/src/bundling/runtime-alias-map.d.ts +13 -0
  13. package/src/bundling/runtime-alias-map.js +113 -0
  14. package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +25 -4
  15. package/src/bundling/runtime-bundle.js +258 -0
  16. package/src/bundling/runtime-interop-plugin.js +34 -0
  17. package/src/bundling/runtime-mode.d.ts +9 -0
  18. package/src/bundling/runtime-mode.js +11 -0
  19. package/src/bundling/runtime-modules.d.ts +29 -0
  20. package/src/bundling/runtime-modules.js +49 -0
  21. package/src/client-graph/ast-transform.d.ts +18 -0
  22. package/src/client-graph/ast-transform.js +426 -0
  23. package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +23 -13
  24. package/src/client-graph/boundary-cache.js +182 -0
  25. package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
  26. package/src/client-graph/boundary-plugin.js +149 -0
  27. package/src/client-graph/component-config-traversal.js +77 -0
  28. package/src/client-graph/declared-modules.js +69 -0
  29. package/src/client-graph/module-classification.d.ts +3 -0
  30. package/src/client-graph/module-classification.js +43 -0
  31. package/src/{utils → client-graph}/reachability-analyzer.d.ts +4 -12
  32. package/src/client-graph/reachability-analyzer.js +515 -0
  33. package/src/client-graph/specifier-classification.d.ts +75 -0
  34. package/src/client-graph/specifier-classification.js +214 -0
  35. package/src/contracts/router-adapter.js +6 -0
  36. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  37. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  38. package/src/hmr/hmr-scripts.js +44 -0
  39. package/src/hmr/hmr-strategy.d.ts +74 -0
  40. package/src/hmr/hmr-strategy.js +351 -0
  41. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  42. package/src/hmr/page-metadata-cache.js +44 -0
  43. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  44. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  45. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  46. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  47. package/src/hydration/bootstrap-imports.d.ts +25 -0
  48. package/src/hydration/bootstrap-imports.js +33 -0
  49. package/src/hydration/hydration-asset.d.ts +84 -0
  50. package/src/hydration/hydration-asset.js +227 -0
  51. package/src/hydration/hydration-scripts.d.ts +104 -0
  52. package/src/hydration/hydration-scripts.js +483 -0
  53. package/src/hydration/hydration-scripts.test.browser.js +199 -0
  54. package/src/hydration/page-data-manifest.d.ts +58 -0
  55. package/src/hydration/page-data-manifest.js +97 -0
  56. package/src/hydration/page-data-reader.d.ts +31 -0
  57. package/src/hydration/page-data-reader.js +77 -0
  58. package/src/hydration/page-payload.d.ts +67 -0
  59. package/src/hydration/page-payload.js +106 -0
  60. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  61. package/src/hydration/serialize-page-data-script.js +30 -0
  62. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +6 -6
  63. package/src/mdx/mdx-config-dependency.js +110 -0
  64. package/src/mdx/mdx-loader-plugin.d.ts +2 -0
  65. package/src/mdx/mdx-loader-plugin.js +8 -0
  66. package/src/page/page-module.d.ts +46 -0
  67. package/src/page/page-module.js +74 -0
  68. package/src/plugin/react.constants.js +1 -0
  69. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +9 -3
  70. package/src/plugin/react.plugin.js +241 -0
  71. package/src/plugin/react.types.d.ts +156 -0
  72. package/src/plugin/react.types.js +1 -0
  73. package/src/render/component-ownership.d.ts +49 -0
  74. package/src/render/component-ownership.js +46 -0
  75. package/src/render/component-ssr.d.ts +113 -0
  76. package/src/render/component-ssr.js +180 -0
  77. package/src/render/eco-embed.js +9 -0
  78. package/src/render/errors.d.ts +16 -0
  79. package/src/render/errors.js +23 -0
  80. package/src/render/html-boundary.js +59 -0
  81. package/src/render/layout-compose.d.ts +66 -0
  82. package/src/render/layout-compose.js +134 -0
  83. package/src/render/react-renderer.d.ts +139 -0
  84. package/src/render/react-renderer.js +450 -0
  85. package/src/render/react-runtime.d.ts +13 -0
  86. package/src/render/react-runtime.js +26 -0
  87. package/src/render/unified-layout-composition.d.ts +53 -0
  88. package/src/render/unified-layout-composition.js +78 -0
  89. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
  90. package/src/eco-embed.js +0 -11
  91. package/src/react-hmr-strategy.d.ts +0 -230
  92. package/src/react-hmr-strategy.js +0 -657
  93. package/src/react-renderer.d.ts +0 -233
  94. package/src/react-renderer.js +0 -622
  95. package/src/react.constants.js +0 -4
  96. package/src/react.plugin.js +0 -209
  97. package/src/react.types.d.ts +0 -88
  98. package/src/react.types.js +0 -0
  99. package/src/router-adapter.js +0 -0
  100. package/src/services/pages-index.d.ts +0 -64
  101. package/src/services/pages-index.js +0 -73
  102. package/src/services/react-bundle.service.js +0 -86
  103. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  104. package/src/services/react-hydration-asset.service.d.ts +0 -84
  105. package/src/services/react-hydration-asset.service.js +0 -217
  106. package/src/services/react-mdx-config-dependency.service.js +0 -122
  107. package/src/services/react-page-module.service.d.ts +0 -88
  108. package/src/services/react-page-module.service.js +0 -166
  109. package/src/services/react-page-payload.service.d.ts +0 -46
  110. package/src/services/react-page-payload.service.js +0 -67
  111. package/src/services/react-runtime-bundle.service.js +0 -192
  112. package/src/utils/client-graph-boundary-cache.js +0 -116
  113. package/src/utils/client-graph-boundary-plugin.js +0 -552
  114. package/src/utils/client-only.js +0 -19
  115. package/src/utils/component-config-traversal.js +0 -54
  116. package/src/utils/declared-modules.js +0 -47
  117. package/src/utils/dynamic.js +0 -12
  118. package/src/utils/dynamic.test.browser.js +0 -33
  119. package/src/utils/hmr-scripts.js +0 -31
  120. package/src/utils/html-boundary.js +0 -55
  121. package/src/utils/hydration-scripts.d.ts +0 -92
  122. package/src/utils/hydration-scripts.js +0 -358
  123. package/src/utils/hydration-scripts.test.browser.js +0 -198
  124. package/src/utils/reachability-analyzer.js +0 -339
  125. package/src/utils/react-dom-runtime-interop-plugin.js +0 -38
  126. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  127. package/src/utils/react-mdx-loader-plugin.js +0 -45
  128. package/src/utils/react-runtime-alias-map.d.ts +0 -8
  129. package/src/utils/react-runtime-alias-map.js +0 -90
  130. /package/src/{utils → app}/client-only.d.ts +0 -0
  131. /package/src/{utils → app}/dynamic.d.ts +0 -0
  132. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  133. /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
  134. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  135. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  136. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  137. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  138. /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
  139. /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
  140. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  141. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  142. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Unified React layout + page composition for SSR document shells.
3
+ *
4
+ * @remarks
5
+ * When every shell layout is React-managed, compose one element tree via
6
+ * {@link composeLayoutPageTree} / {@link composeLayoutPageTreeFromShell} instead of
7
+ * rendering each tier separately. This keeps SSR DOM shape aligned with client
8
+ * hydration through `@ecopages/react/layout-compose`.
9
+ */
10
+ import type { ComponentRenderInput, EcoComponent } from '@ecopages/core';
11
+ import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
12
+ import type { DocumentShellComposeChildrenContext, DocumentShellComposeChildrenResult, DocumentShellLayoutInput } from '@ecopages/core/route-renderer/orchestration/document-shell/document-shell-render.service';
13
+ import type { ReactElement } from 'react';
14
+ import type { ReactForeignSubtreeResolutionContext } from './component-ssr.js';
15
+ import type { ReactRuntimeModules } from './react-runtime.js';
16
+ import { type ComposablePage, type LayoutComposeOptions } from './layout-compose.js';
17
+ export declare function composeReactLayoutPageTree(Page: ComposablePage, pageProps: Record<string, unknown>, shellEntries: Array<{
18
+ component: EcoComponent;
19
+ props?: Record<string, unknown>;
20
+ }>, options: LayoutComposeOptions): ReactElement;
21
+ export declare function shouldUseUnifiedReactLayoutComposition(options: {
22
+ page: EcoComponent;
23
+ shellLayouts: DocumentShellLayoutInput[];
24
+ reactIntegrationName: string;
25
+ }): boolean;
26
+ export declare function resolveComposeChildren(options: {
27
+ page: {
28
+ component: EcoComponent;
29
+ props: Record<string, unknown>;
30
+ };
31
+ shellLayouts: DocumentShellLayoutInput[];
32
+ reactIntegrationName: string;
33
+ composeChildren: (page: {
34
+ component: EcoComponent;
35
+ props: Record<string, unknown>;
36
+ }, context: DocumentShellComposeChildrenContext) => Promise<DocumentShellComposeChildrenResult>;
37
+ }): ((context: DocumentShellComposeChildrenContext) => Promise<DocumentShellComposeChildrenResult>) | undefined;
38
+ export declare function composeReactLayoutPageChildren(options: {
39
+ page: {
40
+ component: EcoComponent;
41
+ props: Record<string, unknown>;
42
+ };
43
+ context: DocumentShellComposeChildrenContext;
44
+ runtime: ReactRuntimeModules;
45
+ integrationName: string;
46
+ normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
47
+ getRootTagName: (html: string) => string | undefined;
48
+ getQueuedForeignSubtreeResolutionContext: (input: ComponentRenderInput) => ReactForeignSubtreeResolutionContext | undefined;
49
+ resolveQueuedForeignSubtreeHtml: (html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined) => Promise<{
50
+ assets: ProcessedAsset[];
51
+ html: string;
52
+ }>;
53
+ }): Promise<DocumentShellComposeChildrenResult>;
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Unified React layout + page composition for SSR document shells.
3
+ *
4
+ * @remarks
5
+ * When every shell layout is React-managed, compose one element tree via
6
+ * {@link composeLayoutPageTree} / {@link composeLayoutPageTreeFromShell} instead of
7
+ * rendering each tier separately. This keeps SSR DOM shape aligned with client
8
+ * hydration through `@ecopages/react/layout-compose`.
9
+ */
10
+ import { hasSingleRootElement } from './html-boundary.js';
11
+ import { isReactManagedComponent } from './component-ownership.js';
12
+ import { assertComposablePage, composeLayoutPageTree, composeLayoutPageTreeFromShell, resolveLayoutContextFromShell, } from './layout-compose.js';
13
+ export function composeReactLayoutPageTree(Page, pageProps, shellEntries, options) {
14
+ const hasNormalizedLayouts = Boolean(Page.config?.layoutEntries?.length) || Boolean(Page.config?.layouts?.length);
15
+ if (hasNormalizedLayouts) {
16
+ return composeLayoutPageTree(Page, pageProps, options);
17
+ }
18
+ return composeLayoutPageTreeFromShell(Page, pageProps, shellEntries, options);
19
+ }
20
+ export function shouldUseUnifiedReactLayoutComposition(options) {
21
+ const { page, shellLayouts, reactIntegrationName } = options;
22
+ if (!isReactManagedComponent(page, reactIntegrationName)) {
23
+ return false;
24
+ }
25
+ const composablePage = assertComposablePage(page);
26
+ const configLayouts = composablePage.config?.layouts ?? composablePage.config?.layoutEntries?.map((entry) => entry.component) ?? [];
27
+ const layoutComponents = shellLayouts.length > 0 ? shellLayouts.map((layout) => layout.component) : configLayouts;
28
+ if (layoutComponents.length === 0) {
29
+ return false;
30
+ }
31
+ return layoutComponents.every((component) => isReactManagedComponent(component, reactIntegrationName));
32
+ }
33
+ export function resolveComposeChildren(options) {
34
+ const { page, shellLayouts, reactIntegrationName, composeChildren } = options;
35
+ if (!shouldUseUnifiedReactLayoutComposition({
36
+ page: page.component,
37
+ shellLayouts,
38
+ reactIntegrationName,
39
+ })) {
40
+ return undefined;
41
+ }
42
+ return (context) => composeChildren(page, context);
43
+ }
44
+ export async function composeReactLayoutPageChildren(options) {
45
+ const { page, context, runtime, integrationName, normalizeUnresolvedMarkerArtifactHtml, getRootTagName, getQueuedForeignSubtreeResolutionContext, resolveQueuedForeignSubtreeHtml, } = options;
46
+ const pageComponent = assertComposablePage(page.component);
47
+ const shellEntries = context.layouts.map((layout) => ({
48
+ component: layout.component,
49
+ props: layout.props,
50
+ }));
51
+ const { react, reactDomServer } = runtime;
52
+ const tree = composeReactLayoutPageTree(pageComponent, page.props, shellEntries, {
53
+ context: resolveLayoutContextFromShell(page.props, shellEntries),
54
+ react,
55
+ });
56
+ const runtimeInput = {
57
+ component: page.component,
58
+ props: page.props,
59
+ integrationContext: {
60
+ rendererCache: context.rendererCache,
61
+ },
62
+ };
63
+ const runtimeContext = getQueuedForeignSubtreeResolutionContext(runtimeInput);
64
+ const html = normalizeUnresolvedMarkerArtifactHtml(reactDomServer.renderToString(tree));
65
+ const resolved = await resolveQueuedForeignSubtreeHtml(html, runtimeContext);
66
+ const primaryRender = {
67
+ html: resolved.html,
68
+ canAttachAttributes: hasSingleRootElement(resolved.html),
69
+ rootTag: getRootTagName(resolved.html),
70
+ integrationName,
71
+ assets: resolved.assets.length > 0 ? resolved.assets : undefined,
72
+ };
73
+ return {
74
+ children: resolved.html,
75
+ layoutRenders: [],
76
+ primaryRender,
77
+ };
78
+ }
@@ -1,56 +1,54 @@
1
- import { useDebugValue, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
1
+ /* eslint-disable react-hooks/exhaustive-deps -- shim mirrors upstream ref-based hook semantics */
2
+ import { useDebugValue, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
2
3
  const objectIs = Object.is;
3
- function useSyncExternalStoreWithSelector(subscribe, getSnapshot, getServerSnapshot, selector, isEqual) {
4
- const instRef = useRef({ hasValue: false, value: void 0 });
5
- const memoizedSelectionRef = useMemo(() => {
6
- let hasMemo = false;
7
- let memoizedSnapshot;
8
- let memoizedSelection;
9
- const maybeGetServerSnapshot = getServerSnapshot === void 0 ? null : getServerSnapshot;
10
- const memoizedSelector = (nextSnapshot) => {
11
- if (!hasMemo) {
12
- hasMemo = true;
13
- memoizedSnapshot = nextSnapshot;
14
- const nextSelection2 = selector(nextSnapshot);
15
- const inst = instRef.current;
16
- if (isEqual !== void 0 && inst.hasValue) {
17
- const currentSelection2 = inst.value;
18
- if (isEqual(currentSelection2, nextSelection2)) {
19
- memoizedSelection = currentSelection2;
20
- return currentSelection2;
21
- }
22
- }
23
- memoizedSelection = nextSelection2;
24
- return nextSelection2;
25
- }
26
- const currentSelection = memoizedSelection;
27
- if (objectIs(memoizedSnapshot, nextSnapshot)) {
28
- return currentSelection;
29
- }
30
- const nextSelection = selector(nextSnapshot);
31
- if (isEqual !== void 0 && isEqual(currentSelection, nextSelection)) {
32
- memoizedSnapshot = nextSnapshot;
33
- return currentSelection;
34
- }
35
- memoizedSnapshot = nextSnapshot;
36
- memoizedSelection = nextSelection;
37
- return nextSelection;
38
- };
39
- return [
40
- () => memoizedSelector(getSnapshot()),
41
- maybeGetServerSnapshot === null ? void 0 : () => memoizedSelector(maybeGetServerSnapshot())
42
- ];
43
- }, [getSnapshot, getServerSnapshot, selector, isEqual]);
44
- const value = useSyncExternalStore(subscribe, memoizedSelectionRef[0], memoizedSelectionRef[1]);
45
- useEffect(() => {
46
- instRef.current = {
47
- hasValue: true,
48
- value
49
- };
50
- }, [value]);
51
- useDebugValue(value);
52
- return value;
4
+ export function useSyncExternalStoreWithSelector(subscribe, getSnapshot, getServerSnapshot, selector, isEqual) {
5
+ const instRef = useRef({ hasValue: false, value: undefined });
6
+ const memoizedSelectionRef = useMemo(() => {
7
+ let hasMemo = false;
8
+ let memoizedSnapshot;
9
+ let memoizedSelection;
10
+ const maybeGetServerSnapshot = getServerSnapshot === undefined ? null : getServerSnapshot;
11
+ const memoizedSelector = (nextSnapshot) => {
12
+ if (!hasMemo) {
13
+ hasMemo = true;
14
+ memoizedSnapshot = nextSnapshot;
15
+ const nextSelection = selector(nextSnapshot);
16
+ const inst = instRef.current;
17
+ if (isEqual !== undefined && inst.hasValue) {
18
+ const currentSelection = inst.value;
19
+ if (isEqual(currentSelection, nextSelection)) {
20
+ memoizedSelection = currentSelection;
21
+ return currentSelection;
22
+ }
23
+ }
24
+ memoizedSelection = nextSelection;
25
+ return nextSelection;
26
+ }
27
+ const currentSelection = memoizedSelection;
28
+ if (objectIs(memoizedSnapshot, nextSnapshot)) {
29
+ return currentSelection;
30
+ }
31
+ const nextSelection = selector(nextSnapshot);
32
+ if (isEqual !== undefined && isEqual(currentSelection, nextSelection)) {
33
+ memoizedSnapshot = nextSnapshot;
34
+ return currentSelection;
35
+ }
36
+ memoizedSnapshot = nextSnapshot;
37
+ memoizedSelection = nextSelection;
38
+ return nextSelection;
39
+ };
40
+ return [
41
+ () => memoizedSelector(getSnapshot()),
42
+ maybeGetServerSnapshot === null ? undefined : () => memoizedSelector(maybeGetServerSnapshot()),
43
+ ];
44
+ }, [getSnapshot, getServerSnapshot, selector, isEqual]);
45
+ const value = useSyncExternalStore(subscribe, memoizedSelectionRef[0], memoizedSelectionRef[1]);
46
+ useEffect(() => {
47
+ instRef.current = {
48
+ hasValue: true,
49
+ value,
50
+ };
51
+ }, [value]);
52
+ useDebugValue(value);
53
+ return value;
53
54
  }
54
- export {
55
- useSyncExternalStoreWithSelector
56
- };
package/src/eco-embed.js DELETED
@@ -1,11 +0,0 @@
1
- import { eco } from "@ecopages/core";
2
- function EcoEmbed({
3
- component,
4
- props,
5
- children
6
- }) {
7
- return eco.embed(component, props, children);
8
- }
9
- export {
10
- EcoEmbed
11
- };
@@ -1,230 +0,0 @@
1
- /**
2
- * React HMR Strategy
3
- *
4
- * Handles hot module replacement for React components.
5
- * Triggers module invalidation on changes to ensure fresh component re-renders.
6
- *
7
- * @module
8
- */
9
- import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
10
- import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
11
- import type { DefaultHmrContext } from '@ecopages/core';
12
- import type { CompileOptions } from '@mdx-js/mdx';
13
- import { ClientGraphBoundaryCache } from './utils/client-graph-boundary-cache.js';
14
- import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
15
- export interface ReactHmrStrategyOptions {
16
- context: DefaultHmrContext;
17
- pageMetadataCache: ReactHmrPageMetadataCache;
18
- runtimeManifest: BrowserRuntimeManifest;
19
- mdxCompilerOptions?: CompileOptions;
20
- ownedTemplateExtensions?: string[];
21
- allTemplateExtensions?: string[];
22
- explicitGraphEnabled?: boolean;
23
- /**
24
- * Per-app cache for client-graph-boundary transform results. Owned by
25
- * the React plugin for the app's lifetime. When omitted, the strategy
26
- * uses a fresh in-memory cache that does not persist across HMR
27
- * rebuilds.
28
- */
29
- clientGraphBoundaryCache?: ClientGraphBoundaryCache;
30
- }
31
- /**
32
- * Strategy for handling React component HMR updates.
33
- *
34
- * This strategy provides React-specific HMR handling by rebuilding entrypoints
35
- * and injecting HMR acceptance handlers that trigger module invalidation.
36
- *
37
- * The processing steps are:
38
- * 1. Check if any React entrypoints are registered
39
- * 2. Rebuild all React entrypoints (the changed file could be a dependency)
40
- * 3. Rebuild browser output through the shared browser bundle service while
41
- * preserving React-specific runtime aliases and graph policy
42
- * 4. Read page config metadata through the shared server-module loading path
43
- * 5. Inject HMR acceptance handler
44
- * 6. Broadcast update events for each rebuilt entrypoint
45
- *
46
- * @remarks
47
- * This strategy has higher priority than generic JsHmrStrategy, allowing it
48
- * to handle React files specially while falling back to generic handling for
49
- * non-React files.
50
- *
51
- * Future enhancement: Track dependencies using Bun's transpiler API to only
52
- * rebuild affected entrypoints instead of all of them.
53
- *
54
- * @see https://bun.sh/docs/runtime/transpiler
55
- *
56
- * @example
57
- * ```typescript
58
- * const context = {
59
- * getWatchedFiles: () => watchedFilesMap,
60
- * getDistDir: () => '/path/to/dist/_hmr',
61
- * getPlugins: () => [],
62
- * getSrcDir: () => '/path/to/src',
63
- * getLayoutsDir: () => '/path/to/src/layouts'
64
- * };
65
- * const strategy = new ReactHmrStrategy({
66
- * context,
67
- * pageMetadataCache,
68
- * runtimeManifest
69
- * });
70
- * ```
71
- */
72
- export declare class ReactHmrStrategy extends HmrStrategy {
73
- readonly type: 100;
74
- private mdxCompilerOptions?;
75
- private readonly ownedTemplateExtensions;
76
- private readonly allTemplateExtensions;
77
- private importNodePageModule;
78
- /**
79
- * Creates a new React HMR strategy instance.
80
- *
81
- * @param options - React HMR runtime services and behavior flags.
82
- */
83
- private context;
84
- private pageMetadataCache;
85
- private explicitGraphEnabled;
86
- private readonly runtimeManifest;
87
- private readonly clientGraphBoundaryCache;
88
- private readonly pagesIndex;
89
- constructor(options: ReactHmrStrategyOptions);
90
- /**
91
- * Returns build plugins for React HMR bundling.
92
- *
93
- * Includes the client graph boundary plugin to prevent undeclared imports
94
- * (including `node:*`) from breaking the browser bundle.
95
- *
96
- * @remarks
97
- * HMR builds receive the React runtime manifest and rewrite manifest-owned
98
- * runtime imports to concrete asset URLs before module resolution.
99
- */
100
- private getBuildPlugins;
101
- private isReactEntrypoint;
102
- /**
103
- * Returns true when a route file uses a compound extension like `page.foo.tsx`.
104
- *
105
- * @remarks
106
- * React integration owns plain `.tsx` route templates. Compound extensions in
107
- * pages/layouts are integration-specific route templates and should not be
108
- * claimed by React HMR strategy.
109
- */
110
- private isRouteTemplate;
111
- private resolveTemplateExtension;
112
- private ownsWatchedEntrypoint;
113
- private configContainsFile;
114
- private pageModuleRequiresLayoutRefresh;
115
- private hasLayoutOwnedDependencyTarget;
116
- /**
117
- * Determines if the file is a React/MDX entrypoint that's registered for HMR.
118
- *
119
- * Uses a three-way decision strategy for selective invalidation:
120
- * 1. If the file is a watched entrypoint, check if React owns it
121
- * 2. If the file is a dependency of watched entrypoints (via dependency graph),
122
- * check if any affected entrypoints are React-owned. Returns false if hits
123
- * exist but none are owned (prevents unnecessary rebuilds).
124
- * 3. Otherwise, check if the file itself is a React entrypoint template
125
- *
126
- * @param filePath - Absolute path to the changed file
127
- * @returns True if this file should trigger React HMR rebuilds
128
- */
129
- matches(filePath: string): boolean;
130
- /**
131
- * Checks if a file is a layout file.
132
- *
133
- * Layout files require special HMR handling because they wrap multiple pages and affect
134
- * the entire page structure. When a layout changes, we trigger a 'layout-update' event
135
- * instead of a regular 'update' event, which instructs the browser to perform a full
136
- * page reload (or clear cache and re-render) rather than attempting module-level HMR.
137
- *
138
- * @param filePath - Absolute path to the file
139
- * @returns True if the file is in the layouts directory
140
- */
141
- private isLayoutFile;
142
- private isPageEntrypoint;
143
- private getEntrypointOutput;
144
- private getRolldownEntryKey;
145
- private getTempFileBasename;
146
- private collectReactPageBuildTargets;
147
- /**
148
- * Expands one HMR request into the full React page build cohort when needed.
149
- *
150
- * @remarks
151
- * Page and layout changes need one shared rebuild pass so sibling routes keep
152
- * a consistent client module graph. Non-page changes that do not touch a page
153
- * cohort can stay scoped to the originally requested targets.
154
- */
155
- private resolveBuildTargets;
156
- private partitionBuildTargets;
157
- /**
158
- * Processes a React file change by rebuilding affected React entrypoints.
159
- *
160
- * Uses a three-way decision strategy for selective invalidation:
161
- * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
162
- * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
163
- * If hits exist but none map to React-owned entrypoints, return 'none' to
164
- * prevent unnecessary rebuilds.
165
- * 3. Dependency graph miss: fall back to rebuilding all watched entrypoints
166
- *
167
- * For layout files, broadcasts a 'layout-update' event to trigger full page reload.
168
- * For regular components/pages, broadcasts 'update' events for module-level HMR.
169
- *
170
- * @param _filePath - Absolute path to the changed file
171
- * @returns Action to broadcast update events (layout-update for layouts, update for components)
172
- */
173
- process(_filePath: string): Promise<HmrAction>;
174
- /**
175
- * Bundles a single React/MDX entrypoint with HMR support.
176
- *
177
- * After successful bundling, populates the entrypoint dependency graph with
178
- * the build's dependency metadata. This enables selective invalidation on
179
- * subsequent file changes, so only entrypoints affected by a changed
180
- * dependency are rebuilt.
181
- *
182
- * @param entrypointPath - Absolute path to the source file
183
- * @param outputUrl - URL path for the bundled file
184
- * @returns True if bundling was successful
185
- */
186
- private bundleReactEntrypoint;
187
- /**
188
- * Bundles multiple React/MDX entrypoints in a single build pass.
189
- *
190
- * Uses code splitting to share common dependencies across entrypoints.
191
- * After successful bundling, populates the entrypoint dependency graph with
192
- * the build's dependency metadata for selective invalidation.
193
- *
194
- * @param entrypoints - Array of entrypoint paths and their output URLs
195
- * @returns Array of output URLs that were successfully built
196
- */
197
- private bundleReactEntrypoints;
198
- private resolveTempOutputPath;
199
- /**
200
- * Clears stale HMR output from a directory before a rebuild.
201
- *
202
- * Only removes:
203
- * - `*.tmp.js` files (the per-build bundler output the strategy owns)
204
- * - the `chunks/` subdirectory (the bundler's splitting target)
205
- *
206
- * The HMR runtime script (`_hmr_runtime.js`) and any user-authored
207
- * assets in the outdir are preserved. This is the minimal set of
208
- * files that, if left from a previous build, can cause the bundler
209
- * to emit `ENOENT` for chunk references that point to entrypoints
210
- * whose hash has since changed.
211
- */
212
- private clearHmrOutdir;
213
- /**
214
- * Encodes dynamic route segments (brackets) in file paths.
215
- * Converts `[slug]` to `_slug_` to avoid filesystem issues.
216
- */
217
- private encodeDynamicSegments;
218
- private rewriteChunkImportUrls;
219
- private isMissingTempOutputError;
220
- /**
221
- * Processes bundled output and injects the React HMR handler.
222
- * Writes to temp file first, then renames atomically to avoid conflicts.
223
- *
224
- * @param tempPath - Path to the temporary bundled file
225
- * @param finalPath - Final destination path
226
- * @param url - URL path for logging
227
- * @returns True if processing was successful
228
- */
229
- private processOutput;
230
- }