Custom-module hazards
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 servedYour 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.
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 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.
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).