Ecopages JSX
@ecopages/ecopages-jsx owns .tsx Pages compiled against the @ecopages/jsx runtime. It optionally adds Radiant, the web-component layer, for server rendering and in-place hydration, and optionally compiles MDX.
What it plugs into core
| Contract | Ecopages JSX |
|---|---|
| Plugin name / extensions | ecopages-jsx / ['.tsx'] by default; extensions replaces it, and mdx.extensions (default ['.mdx']) is appended when mdx is set |
jsxImportSource | @ecopages/jsx |
| Renderer | createEcopagesJsxRenderer(jsxConfig) on createIntegrationRenderer; jsxConfig carries mdxExtensions and radiantSsrEnabled |
bundlesPageDependencies | true |
serverDom | { kind: 'complete' } installing Radiant's light DOM when radiant is on (default); otherwise none |
| Global dependency | with Radiant, @ecopages/radiant/client/install-hydrator as a head script, bundle: false, id ecopages-jsx-radiant-hydrator |
| Build plugins | the ecopages-jsx-mdx-loader plugin when mdx is set; none otherwise |
prepareAssetDependencies | tags page-owned content scripts into the app-wide client bundle |
| HMR | EcopagesJsxHmrStrategy plus EcopagesJsxDevTransformContributor |
SSR policy
JSX is rendered with renderToString from @ecopages/jsx/server. Radiant lives in EcopagesJsxRadiantSsrPolicy, which wraps each render in a server custom-element render hook: a registered intrinsic tag that has an element instance is serialized through Radiant's renderHostToString, so framework-specific host rendering stays out of page code.
- Radiant's server bridge is loaded lazily, once per policy instance, because most renders never need it.
- The DOM constructors are not installed here. Core installs them at Integration setup (
serverDom), before any element is defined; the policy only fills in when no registry exists. - With
radiant: falsethe policy is disabled andserverDomis undefined.
ssr: true scripts
Components declare element registration once in dependencies.scripts. A CustomElementScriptPreloader imports entries marked ssr: true before render so the host can SSR without a redundant import in the component file. Core preloads the scripts it assigns to Ecopages JSX before it renders a Page, and renderComponent preloads those of the Component it receives. The renderer builds the preloader only when Radiant is enabled, from createSsrScriptPreloader(), and its state lives on the AppRuntime, so apps do not share preload history. With Radiant, EcopagesJsxPlugin declares ssrScriptPreload: 'own', so core gives it the ssr: true scripts of Ecopages JSX Components wherever they sit in the tree, and no other preloader, Lit included, evaluates them (Route rendering). In development a changed script entrypoint invalidates its registration (invalidateRadiantRegisteredScriptSsrRegistration).
Hydration story
There is no island entry generator here. The two pieces are:
- Page-level scripts are Component Dependencies; with
bundlesPageDependenciesandprepareAssetDependencies, page-owned content scripts join the app-wide client bundle (Build pipeline). File scripts of Components and Integration runtime assets stay ungrouped. - Radiant hosts hydrate in place only when SSR markers and the client hydrator both exist. The hydrator script is loaded explicitly in the head so it runs before any custom-element module connects; relying on elements to install it opportunistically is not supported. Without it Radiant falls back to a fresh client render on first connect.
RadiantElement preserves SSR light-DOM nodes (focus, input state, media). RadiantController activation re-mounts its template into the host, so child nodes are rebuilt.
MDX
ecopages-jsx-mdx.ts wraps the shared @ecopages/mdx/core helpers with jsxImportSource: '@ecopages/jsx', format: 'detect' and outputFormat: 'program'. The renderer's normalizePageModule hook adapts MDX Page modules (layouts via ensurePageConfigLayouts). See MDX.
HMR
The strategy matches a changed file under the source directory (excluding the includes directory) when it is a Page or Layout file with a JSX template extension (see HMR strategies for how those are known), or a file the latest render used. It returns a layout-update broadcast, so the navigation runtime refreshes the current Page (HMR strategies, Navigation). Registered script entrypoints are skipped; script HMR handles them.
"Used by the latest render" comes from a module-scoped ownership set recorded by withEjsxHmrOwnershipScope / recordEjsxHmrOwnership, so the watcher need not walk the component tree. Only the latest top-level render is kept, so a file used only by an earlier-rendered Page does not match until that Page renders again.
The dev-transform contributor claims Page and Layout entrypoints and supplies the MDX loader for .mdx modules.
Mixed rendering
normalizeForeignChildPropsserializes JSXchildrento HTML when the target Integration is notecopages-jsx(DOM-like nodes useouterHTML; arrays, React-like elements and template results go throughrenderToString).renderQueuedChildrenresolves queued foreign tokens in the serialized children.- Cross-Integration shell stacks use
EcoEmbedfrom@ecopages/ecopages-jsx/eco-embed. - Components that may render Foreign Children declare them in
config.dependencies.components(Integrations and Foreign Children).
See also
Islands and hydration, Plugin pipeline, Lit (the other Integration that registers custom elements).
Sources
This page describes the code below.
packages/integrations/ecopages-jsx/src/ecopages-jsx.plugin.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-renderer.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-radiant-ssr-policy.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-radiant-light-dom.tspackages/integrations/ecopages-jsx/src/resolve-radiant-install-hydrator.tspackages/integrations/ecopages-jsx/src/radiant-registered-script-ssr-invalidation.tspackages/integrations/ecopages-jsx/src/page-owned-content-script-grouping.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-mdx.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-hmr-strategy.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-hmr-ownership.tspackages/integrations/ecopages-jsx/src/dev-transform/packages/integrations/ecopages-jsx/README.md