Skip to content

Rendering a page in coupled mode

One catch-all route resolves the node, personalizes it, hydrates feeds, nav and components, runs your layout transform, then prunes the unserved arms.

Every public URL on a coupled host is served by one optional catch-all route, generated wiring you are not meant to edit — three imports, one createPublicPage({ runtime, layers }), three exports; dynamic has to be a literal string, not page.dynamic, or the build fails. See The host app contract for the file itself and why. What matters here is the pipeline behind it, because its order is a contract two of the stages depend on.

Resolution, and the one fallback

/ resolves the seeded Home node. Every other URL resolves by the full Site Tree path, locale-aware, so a page slugged pricing under platform answers at /platform/pricing and nowhere else. There is exactly one fallback: a single-segment URL may fall back to a flat slug lookup, and only if the node it finds has no parent. Anything unpublished or missing is a 404. The resolution is shared with generateMetadata through React's request cache, so a render is one query, not two.

The site comes from the request's Host header, and its database id — never the runtime's default site id — keys everything after it. See One config, several sites.

The layout pipeline, in this order

Six passes over the layout document

The stored layout document is transformed six times between the database and the renderer, and the order is fixed. Two positions are load-bearing rather than incidental: components resolve before your transform so it sees real nodes, and the prune runs after it so it cannot undo the prune.

NameTypeDefaultDescription
personalizeLayoutsync—
Applies this visitor's audience page variant and strips the others.
hydrateLayoutFeedsasync—
Resolves every Feed Display module against the saved feed's query, scoped to this site.
hydrateLayoutNavasync—
Resolves navMenu / navigation / siteMap modules — a named menu, or the tree.
resolveLayoutComponentsasync—
Materialises linked reusable components into the document. Server-side, because the renderer is a client component and its resolver props are functions.
templates.hydrateLayoutyour layer—
The one seam your project owns. Optional; absent means the document passes through.
pruneLayoutToServedArmssync—
Removes every variant arm this visitor was not served. Always last.

Where your code joins

A site or theme layer may supply a hydrateLayout — a server-side transform over the whole document. It is the supported way to do server work a custom module cannot do for itself: custom modules are client components and can never query the database, so injecting their data here is what makes them complete in the first paint and with JavaScript off.

hydrateLayout?: (
  layout: LayoutDocument,
  ctx: { runtime: KywiRuntime; siteId: string; site: SiteConfig },
) => Promise<LayoutDocument> | LayoutDocument
Resolved from the layer chain, theme over site. Runs once per request, only when the page has a renderable layout.

The prune is a privacy control

Arm selection was always server-side, but until the prune existed the losing arms travelled into the RSC payload and were readable in view-source. Pruning last is what closes that, and it is why your transform runs before it rather than after: a transform that put an unserved arm back on the document cannot leak it, because the prune still gets the last word. Structured data is treated the same way — JSON-LD is built from the served document, so a matched visitor's page cannot ship the default arm's copy in its schema. See What is public about a personalized page.

Two things that are not the layout path

A page whose layout has no section in any region skips the pipeline entirely and renders the Body rich text plus the Featured Image. That is the fallback for any page that reaches render with an empty layout — one created through the API and never opened in the Layout tab, or one created in the admin and never given a section — not an error state either way.

And edit permissions resolve on every request, not only on ?kywi-edit=1. It is a cookie read and a JWT verify with no database round trip, so an anonymous visitor's cost is a fast null and no edit markup is emitted at all — not even the browse toolbar. A signed-in editor gets the overlay handed the stored layout rather than the pruned one, because an editor needs every arm. See Turning on edit mode.