React

@ecopages/react renders React Pages, Layouts and Components on the server and hydrates them in the browser, either as a full Page or as Island Hosts inside a Page owned by another Integration.

What it plugs into core

ContractReact
Plugin name / extensionsreact / ['.tsx'] by default; extensions replaces it and mdx.extensions (default ['.mdx']) is appended
jsxImportSourcereact
RendererReactRenderer on createIntegrationRenderer; the plugin overrides createRenderer to pass reactConfig
bundlesPageDependenciestrue
Build pluginsreact-mdx-loader when mdx is set; none otherwise
Global dependenciesnone of its own; dependencies adds the app's
HMRReactHmrStrategy plus ReactDevTransformContributor

Options worth knowing: router (a ReactRouterAdapter), mdx, explicitGraph, dependencies, and renderTimeoutMs (whole milliseconds, validated at construction).

SSR policy

  • App's own React. resolveReactRuntimeModules(rootDir) prefers the app's react, react-dom/static and react-dom/server, and falls back to the Integration's copy only when the app cannot resolve them.
  • Complete document, not streamed. The server waits for every <Suspense> boundary before returning HTML. One deadline (REACT_SSR_RENDER_TIMEOUT_MS, 10 s, or renderTimeoutMs) covers the whole Page render through runWithRenderBudget. Unfinished boundaries stay in their fallback for the browser to retry and a warning names the Page.
  • Layouts. Layout stacks compose through the shared composeLayoutPageTree so provider context reaches nested Pages and useId values match the browser. LayoutRenderTracker reports a Layout that never renders its children.
  • Non-React shells. A Page, Layout or html template owned by another Integration must return a string; React inserts it unescaped.

Hydration and islands

Core decides which Components are Island Hosts and stamps data-eco-island* attributes (Islands and hydration). React supplies the client side:

PieceWhereBehavior
Island entryhydration-island-entry-source.tsgenerated per component identity; imports the module and @ecopages/react/island-hydration, then mountIslands
Island runtimehydration/browser/island-hydration.tskeeps the SSR host and children, calls hydrateRoot()
Page entryhydration-page-entry-source.tsgenerated Page entry using @ecopages/react/page-hydration
Page payloadhydration/page-payload.tsserializes page props; locals keys are limited to those in Page.requires
Foreign Subtreehydration/foreign-subtree.ts, hydration/browser/foreign-boundary.tswraps each Foreign Subtree of a hydrating tree in <eco-foreign-subtree> on the server; the build rewrites React modules' imports of foreign Eco Components to a boundary that keeps that HTML (Islands and hydration)

A Page hydrates when it declares dependencies.modules, when explicitGraph is set, or whenever a router adapter exists (shouldHydratePage). explicitGraph forces hydration assets; it does not turn off client-graph stripping. Both entries import react, react-dom/client and their bootstrap package by package name. A Page entry with a router adapter also imports the router; React in the browser graph says where those imports go.

BrowserBuildServeryesnoReactRenderer composesLayouts and Page into onetreeComplete document HTMLPage hydrates, or Islandroot?Foreign Subtrees wrappedin eco-foreign-subtreeForeign Subtrees resolve inplaceReact module imports aforeign Eco ComponentImport rewritten toforeignBoundarypage-hydration bootstraphydrates the treeforeignBoundary keeps theserver HTMLisland-hydration bootstraphydrates Island Hosts

Client-graph boundary

client-graph/boundary-plugin.ts runs on every module in a browser build (page, island, lazy entry and shared helpers) and:

  1. computes reachability from client roots,
  2. removes disallowed imports (Node built-ins with or without the node: prefix, decided by core's isNodeBuiltinSpecifier, .server modules, content /server modules, named imports outside declared pkg{name} rules).
  3. strips server-only eco.page() options (cache, middleware, dependencies, requires, metadata, props, paths) and declarations only they used,
  4. fails the build, naming binding and file:line:column, if needed browser code still uses a removed import. Both failures (a removed import the render function reaches, and one a kept top-level statement uses) point at the .server fix: move the code into a .server module and call it only from server-only Page options.

A bare side-effect import (import 'x') has no binding to test for reachability, so the boundary keeps it in every module it sees, whatever folder the module sits in and whether it is an entry, a page, a layout, a component, a script or a helper. Only .server modules and Node built-ins are removed from it. A stylesheet import is not stripped here: the build's stylesheet module plugin gives it an empty module because core already discovers and delivers the CSS. A server-only bare import therefore reaches the browser unless it sits in a .server module. MDX files are compiled by the MDX loader and never pass through the boundary, so their bare imports are kept the same way.

Legacy getMetadata, getStaticProps and getStaticPaths exports are never browser roots. Declarations that only removed code used are removed, and an exported name keeps its binding set to undefined.

Build plugins for a client build are assembled in bundling/bundle.ts: the foreign-JSX override (only for files another JSX Integration owns that React's static scan reaches; client-graph/foreign-jsx-reach.ts reads each file's imports from its parsed module, an MDX file from its compiled output, so a specifier in a comment or string is not followed), the graph boundary, the foreign boundary (createForeignBoundaryPlugin, which rewrites imports of foreign Components, gives a shared module its own React form, and leaves React-only modules untouched) and the MDX loader. The decision tree for a server-only import, in the guard and in this boundary, is drawn in Build queue and adapter. They key off the module, not the entry that reached it, because a shared module has one URL and one compiled form (Plugin pipeline, Build pipeline). The foreign-JSX override, the foreign boundary and the MDX loader are one instance per bundler, shared by every entry: a production build merges the entries' plugin lists by identity, so a plugin made per entry would run its hooks once per React Page.

React in the browser graph

React, React DOM, @ecopages/react/layout-compose, the bootstrap packages and the router are ordinary packages: no Integration declares a fixed URL or rewrites their imports.

  • Production. Every Page entry, router or not, and every island hydration entry is an entry of the app-wide browser build (APP_BROWSER_CLIENT_BUNDLE_ID), with code splitting. React and the other shared modules are content-hashed chunks, served immutable, and a page loads one copy of React whether its scripts are a Page entry, island entries or both. Rolldown's CommonJS interop gives the entries React's named exports, and React DOM's require('react') resolves to the same module.
  • Development. The unbundled Page and island entries are content scripts. With HMR, core rewrites their imports like a dev-transform module's (Dev server): each package gets its one vendor URL, and named imports of a CommonJS vendor such as React read its default export.

Both graphs define process.env.NODE_ENV from the current Node environment, so React's CommonJS entry picks its development or production build the same way in each.

HMR

ReactHmrStrategy is an INTEGRATION strategy. It matches watched React entrypoints and files found through the entrypoint dependency graph, ignores registered script entrypoints, and rebuilds the affected targets through the dev transform plugins (including the graph boundary). Result: layout-update when a Layout or Layout dependency changed, otherwise per-URL update events, otherwise none (HMR strategies, HMR client). Whether a changed file is a Page or a Layout comes from the HMR context's isPageFile and isLayoutFile (the Route Registry, and the Layouts rendered Pages referenced), never from a folder. A shared HmrPageMetadataCache lets save-time rebuilds reuse declared-module analysis. page-hydration-hmr.ts is the browser half: handlePageHmr imports the new module, then either calls the navigation runtime's reloadCurrentPage with moduleUrl (when the document owner is react-router; clearCache is set only if the layout stack differs by reference) or fetches the current URL, publishes the parsed document as page.document (the server HTML of the Page's Foreign Subtrees, see Islands and hydration), reads the Page's props (and its module URL, when the envelope carries one) from that document's __ECO_PAGE_DATA__, so an edit that changes what props returns is rendered, and re-renders the active page root with the new Page and those props; a response that is an error throws, so the update is not applied and the next edit retries it. A stale mount generation aborts the update. If an uncaught error tears the root down, the server HTML is restored and the Page's HMR handler rejects so the HMR client reloads the document.

A Page without a router has no Html shell that emits __ECO_PAGE_DATA__ (EcoPropsScript belongs to the router). For a Page the browser hydrates, getHtmlDocumentContributionsHook therefore appends the script to the document head as a contribution, whoever owns the Html template, so hydration and a direct HMR update read the Page's props from it; a Page that never hydrates gets none.

PageModuleService.ensureConfigFileMetadata keeps the identity the build stamped on a config and binds a config without one, such as an MDX Page's layout config, to the Page's path.

Router hookup

A ReactRouterAdapter is data: importPath, the package of the router's browser entry, the components.router and components.pageContent names, and getRouterProps. ecoRouter() from @ecopages/react-router returns one (name: 'eco-router', importPath: '@ecopages/react-router/browser'). With an adapter the plugin:

  • imports the router from importPath in every Page entry and keeps that package in every client graph,
  • hydrates every React Page,
  • sets ECO_DOCUMENT_OWNER_ATTRIBUTE to react-router on the document,
  • contributes router payload to non-React html templates through documentContributions.

Navigation itself lives in React router, with the framework-neutral parts in Browser router and Navigation.

See also

Integrations and Foreign Children, Pages, layouts and components, MDX.

Sources

This page describes the code below.