Route rendering

Once a request matches a Page or an explicit view (Routing), one Integration renderer turns it into HTML. Every path, whether a filesystem Page, ctx.render, app.static, an error page or static export, converges on IntegrationRenderer.execute(). This page covers that pipeline. What preparation puts in the Page Package is in From graph to HTML; how Components of other Integrations render inside it is in Integrations and foreign children.

yesnoIntegrationRenderer.executeActivate Integration runtimerenderRemote hook returnsa result?Route resultOpen render sessionprepareRenderOptions:module, props, graph, PagePackageRender Page, Layouts andHtml shellStamp document attributesHTML transform injects thePage PackagefinalizeDocument hook

From request to response

A filesystem Page request crosses these steps. The middle of the diagram is execute(); the sections below cover each part.

hitmissecopages start: read from theledgerecopages build: process once,recorddevelopment: process on everyrenderRequestRouteRegistry.matchRequest:compiled patternsFile route middlewarePageRequestCacheCoordinator:cached HTML for the key?ResponseIntegrationRenderer.executeprepareRenderOptionsShell graph, ownershipcheck, Page dependenciesShell DependenciesPage Browser Graph, clientplan, Page PackagerenderRouteBody: HTMLstays a stringStamp document attributestransformRouteHtml: injectthe Page Package, thenfinalizeDocumentStore under the cachestrategy

captureHtmlRender reads the body once, as a string; a streamed body is the only case that reads a Response. The transform takes that string and returns one, so nothing wraps the document in a Response between the renderer and the page cache. In production without HMR the shell branch is a ledger read, so ecopages start never packages a stylesheet (Ledger and start).

Choosing the renderer

RouteRendererFactory maps a route file to its Integration (findIntegrationForFile) or an explicit view to the Integration it names, and returns that Integration's shared renderer. The same instance serves route renders, explicit views and Foreign Child handoffs. Integrations build renderers with createIntegrationRenderer() and hooks (Custom Integration); StringMarkupRenderer is a typed base for string-markup Integrations with no behavior of its own.

The execute pipeline

execute() activates the Integration runtime, gives the optional renderRemote hook first refusal, then opens a render session and hands off to RouteRenderOrchestrator:

  1. prepareRenderOptions() loads the Page module and final props, builds and validates the prepared component graph and builds the Page Package. Route params and query take precedence over extra props of the same name. A planned route from static export passes its preparation back in, so its data hooks run once per build.
  2. The renderer renders the Page, Layouts and Html shell. Foreign Children go to their owning renderer.
  3. executePrepared() captures the body, stamps document attributes, runs the HTML transform with the prepared Page Package, and lets the Integration's finalizeDocument hook reconcile its own markup.

Core wraps whatever the route render throws as Error rendering page, with the original error as cause, and passes an HttpError through unchanged, so a Page that throws NotFound still answers 404. A renderRoute hook must not catch and re-wrap. A renderer with its own document model, such as the HTML Page renderer, overrides renderRouteDocument() rather than render(), so its errors are wrapped the same way.

Page shape

A route module is imported through importRouteModule(), which the loadPageModule() entry point and prepareRenderOptions() share, so a route whose default export is not a Page fails before any Page option is read. The legacy-export check runs first, then assertPageModule() requires a declared component (an eco.page() result; HTML Pages and MDX modules carry an identity too) whose config.identity.file, resolved against rootDir, is the route file. The identity transform stamps the file that holds the literal eco.page(...) call, so a Page made by a wrapper in another file, or re-exported from one, names that other file and fails. A rejected module fails with the file and the fixes: a _ prefix, a role suffix, or moving it out of the pages directory (the last two are left out for a file outside it). A function that has a config but is not attributed to the route file gets the literal-call message instead: the build finds eco.page, eco.layout, eco.component and eco.html by their literal call, so a wrapper, an alias or a re-export hides the declaration. The check keeps no state, so in development the next request after a fix imports the corrected module. The same literal-call check (page-declaration.ts) runs on a view that is loaded from a file, with that file in place of the route file: resolveExplicitViewRenderer() checks the loader's filePath for app.static(), error-page loaders and static generation, and ctx.render checks a View Reference's filePath after importing it. Only the literal-call failure applies to views, since a view need not be a Page. A component passed directly, with no source file known, is not checked.

Render sessions and context

Each execute() opens a session that holds the render's cache of owning renderers. The component render context, which names the current Integration and holds the foreign-child runtime, lives in node:async_hooks AsyncLocalStorage. Nested and concurrent renders therefore never see each other's state, and static export can render several Pages of one Integration at once. Every component render runs under a context that names its Integration, even with no foreign-child runtime, so an ownership guard such as the content Processor's getComponent() can tell which Integration is rendering.

Document shell

composeDocumentShell wraps the Page in its Layouts and the Html template as strings, one tier at a time. An Integration that composes a single tree, such as React, supplies composeChildren instead and still delegates Foreign Subtrees through renderComponentWithForeignChildren. Sequential wrapping checks that each Layout rendered its children; Pages, layouts and components covers the outcome per mode.

Explicit views

An explicit view is an eco.page() value passed to ctx.render, app.static() or an error-page helper rather than found on disk.

  • resolveExplicitViewRenderer finds the view's renderer without reading props, so static export can plan a dynamic route before any slug exists. prepareExplicitStaticRender then runs props with the route's Params.
  • A full render goes through executeExplicitView (route result with metadata, used by static export for sitemap eligibility) or renderExplicitView (a response). Both call execute with the view as the Page module and skipPropsHook, so the view gets the same Layouts, metadata and client plan as a filesystem Page, and the call's props, Params, query and locals reach the view and its metadata.
  • A partial render (ctx.renderPartial) stays on the component path: it opens its own session, builds no browser assets and is not checked against a prepared graph.

Error pages

ErrorPageRenderer serves the semantic statuses 400, 401, 403, 404, 409 and 500, for requests and static export alike. Any other 5xx uses the 500 page; any other 4xx gets a built-in document. The source is chosen in order:

  1. a filesystem page (src/pages/404.* and the like), which still counts when the source is gone but ecopages build recorded it in the server-modules map;
  2. a view registered with app.notFound() and similar, prepared with prepareExplicitStaticRender;
  3. the built-in document.

A failing custom page propagates its error; the request adapter then calls renderBuiltIn(), which never re-enters a custom source. Built-in pages show diagnostics only for a 5xx in development, with the stack of every wrapped cause, and show the message on its own only when the stack does not open with it; production pages never include a stack. During static export, SemanticErrorPageExporter writes one file per semantic status pathname (/404, …) unless a generated route already owns it. Adapters classify route failures and build the HTTP response; the renderer only chooses and renders the source. The classification and the error classes are in Errors and utilities.

Page cache

PageCacheService stores rendered HTML for request-time Pages under their cache strategy. The strategies and their headers are in Caching. Internally:

  • A stale revalidate hit returns the stored HTML and regenerates once in the background, deduplicated per key. App shutdown waits for in-flight regenerations before Integration teardown.
  • Invalidations advance a generation counter before waiting for in-flight writes, so a render that began earlier cannot repopulate an entry after an invalidation.
  • Each entry is bound to the source files it read (collectHtmlCacheSourceDependencyPaths): the route module closure, identity files and watch hops of the whole declared Component graph, Page Browser Graph inputs, processed assets and the Html template's imports. A development edit evicts only the entries bound to the changed file; see Watcher and invalidation. Path invalidation also releases the entry's build-input bindings.
  • PageRequestCacheCoordinator applies the policy to one request and builds the response headers, including the ETag and 304 for static HTML.

Custom-element SSR scripts

Lit and Ecopages JSX register custom elements on the server by importing the dependencies.scripts entries marked ssr: true before they render, through a shared CustomElementScriptPreloader. A renderer does not construct its preloader: it asks the createSsrScriptPreloader() option of its hook factory for one, passing its Integration name, cacheScope, importServerModule and logLabel, and core builds it from the Integration's ssrScriptPreload declaration. Each preloader has a cacheScope on the app's AppRuntime, which deduplicates imports across concurrent renders and lets development invalidation clear only that app's state.

A script is always evaluated through the preloader's importServerModule, never by a native import, because a native import skips the server loaders for its CSS, MDX and asset imports. Two importers exist:

ImporterUsed byWhy
createCustomElementServerModuleImporterLitCompiles through the app module loader into a separate outdir per registry under the work directory.
createSharedServerModuleImporterEcopages JSXCompiles into the shared page server-module outdir, since a separate copy would load a second Radiant graph and break host SSR.

Every ssr: true entry is preloaded, eager or lazy, and assigned to one preloader, so an element's module graph does not load twice. Each Integration states which scripts its preloader takes with ssrScriptPreload on IntegrationPlugin, and assignSsrPreloadScripts assigns every script found in the Dependency tree once per Page render. IntegrationRenderer.render() makes that assignment over the Page, its Layouts, the Html template and the Page's dependency Components, then has each assigned Integration preload its share, activating one other than the owner first. No hook decides from the part of the tree it sees, and a Page owned by Kita or React still has its Lit scripts evaluated. The assignment follows these rules:

  • A script declared by a Component whose Integration preloads ('own' or 'own-and-foreign') goes to that Integration. When Components of several preloading Integrations declare it, the first in config order takes it.
  • Any other script, such as one on a Kita, React or plain Component, goes to the first 'own-and-foreign' Integration in config order: Lit. Without one, it is not evaluated on the server.

A script that throws while it is preloaded is recorded as failed, and is not evaluated again until a save of it invalidates it or any file change clears every failed preload in development (clearFailedCustomElementScriptPreloads), since the cause can be a module it imports. The Page still renders with a 200, and the element renders without server rendering unless an earlier evaluation of the script already registered it. In ecopages dev outside static generation, the preloader's onPreloadFailure shows the error in the overlay when the script fails, and a script that is still broken after the next change fails and is reported again on its next render; a script that only needs the browser (window is not defined) is not reported. Static generation, and with it ecopages build, fails instead: the callback throws an error naming the script and the cause, so a build cannot exit 0 with elements that lack their server output. ecopages start only logs the warning, since it renders at request time and a throw would turn one broken script into failing Pages.

Ecopages JSX declares 'own' when Radiant is enabled, and Lit declares 'own-and-foreign'. The declaration is the only statement of whether an Integration preloads, so the two cannot drift. A renderer that builds a preloader for an Integration with no ssrScriptPreload throws, and so does an Integration that declares one whose renderer builds none; getRenderer() reports both when it creates the renderer.

yes ('own' or 'own-and-foreign')noyesnoPage, Layouts, Html shelland dependencyComponentsassignSsrPreloadScripts:each ssr: true scriptassigned onceDeclaring Component'sIntegration preloads?That Integration; first inconfig order if severalAn 'own-and-foreign'Integration exists?First one in config order(Lit)Not evaluated on the serverActivate Integration if notthe owner, preload its shareRender route to a stringrenderCustomElementshook of each assignedIntegration

After the route renders, render() passes a string document through the renderCustomElements hook of each Integration it assigned scripts to, whichever Integration owns the Page. A Page with no assigned script runs no hook and pays nothing; a body that is not a string is returned as it is (every in-tree renderer, React included, produces a complete string). The Integration also counts as taking part in the Page for its global scripts, so Lit's hydration support precedes the element scripts on a Kita Page that only declares a Lit element on a Kita Component.

renderComponent also preloads the scripts of the Component it receives, for a partial render that has no Page. That assignment sees only the Component's tree, so a preloader skips any script another Integration's preloader has already loaded, failed on or is loading for the same registry: a script declared on a Kita and an Ecopages JSX Component is evaluated once, by Ecopages JSX. Neither path builds a browser bundle for a preloaded script; lazy still controls browser loading. Per-Integration details: Lit, Ecopages JSX.

Sources

This page describes the code below.