# Custom-module hazards

URL: https://kywi-docs-production.up.railway.app/developing/custom-module-hazards
Type: docPage

Modules render in the editor canvas and on the public page from one map, so a throw, a fetch or a non-deterministic id breaks both surfaces at once.

One module map is handed to two renderers: the public page and the admin's editor canvas. Everything on this page follows from that. A module that throws does not degrade a band on the site — it takes down the surface the owner would use to fix it, and the report you get is "the layout editor is broken", not "the module is broken".

The checklist form of these hazards ships with the scaffold as the `kywi-custom-modules` skill (`.claude/skills/`, §6) — an agent in your project already has it. What follows is grounded in core's own source: which surface each hazard actually breaks, and why.

## Render must be deterministic

Generate ids with `React.useId()` — a module-scope counter, `Date.now()` or `Math.random()` in render mismatches server and client, and the hydration error that surfaces points nowhere near your module.

## Do not fetch

A custom module is a client component: it cannot reach the database, and one that fetches from an effect gives the editor canvas content that appears only after a round trip. Data arrives as props, and anything not authored in the props panel is injected server-side before the document crosses into the renderer:

personalizeLayout the audience's variant; other variants stripped hydrateLayoutFeeds feedDisplay modules only hydrateLayoutNav navMenu / navigation / siteMap modules resolveLayoutComponents linked components materialised into the document templates.hydrateLayout YOUR layer's pass — anything else pruneLayoutToServedArms keep only the arm this visitor is served

Your pass runs after linked components are materialised, so it reaches a module placed inside a saved component rather than a bare `componentId` placeholder — and before the prune, so it cannot put an unserved arm back on the wire. That position is the contract, not an implementation detail. This project uses the seam for its `capabilityGrid`, because core's feed pass serves only `feedDisplay` and flattens rows to title/summary/image, dropping the two fields that grid exists to show.

## Read ctx.siteId, never runtime.siteId

A `hydrateLayout` transform is given `{ runtime, siteId, site }`. `siteId` is the site this REQUEST is for, resolved from the Host header. `runtime.siteId` is the DEFAULT site, resolved once at boot — a process-level fallback that public render code must not key on. A transform that queries with `runtime.siteId` serves the first site's rows on every other domain, and does it silently, because the shape of the data is right. This is not hypothetical: this project hit exactly that and now passes `siteId` explicitly — `hydrateLayout: (layout, { runtime, siteId }) => hydrateCapabilityGrids(layout, runtime, siteId)` in `sites/default/index.ts`.

## What survives with JavaScript off

A `'use client'` module still server-renders its initial HTML, so a visitor with JavaScript off sees whatever render produced — the tab open by default has to contain something rather than fill in on mount.

The `<path>.md` twin and `llms-full.txt` are a different surface with a different rule: they never call your component at all. A node's Markdown projection reads the stored `body` column when there is one, and otherwise projects the stored LAYOUT DOCUMENT straight to HTML — a walk over the prop schema, not a render of your component. For a custom module that means only PROP VALUES reach the twin — by default the `text`/`textarea`/`richText` ones, and whatever a prop's `ax` hint adds or removes — exactly as [Designing module props](/developing/designing-module-props-for-the-person-who-edits-the-page/) describes for search. Copy your component renders that no prop holds never reaches it.

The editor canvas announces itself through a React context, not a prop — one that defaults to false and that the public renderer never provides. That is how the built-in form modules render a form-less preview inside the editor's own form. Read the context, don't sniff the URL.

## Owner copy inside a JSON-LD script tag ends the tag

If a module emits `<script type="application/ld+json">` built from props, escape it: every `<` as its JavaScript escape, `-->` broken up, and U+2028/U+2029 escaped. Serialising owner text straight in means one angle bracket typed into a headline closes the script early and takes the rest of the document's structured data with it. This is a hazard specific to props: the value is authored by someone who has no idea it ends up in a script tag.

## Two smaller ones

Style through `--kywi-*` tokens rather than literal colours, so a theme retune from the config carries your module with it ([Themes and design tokens](/developing/themes-and-design-tokens/)).
