# Build a custom module: the three-part contract

URL: https://kywi-docs-production.up.railway.app/developing/build-a-custom-module-the-three-part-contract
Type: docPage

A custom module is three things that must agree — a defineModule entry, a client component, and one entry in the layer’s module map.

A custom module exists only when three separate artefacts agree on one string: a `defineModule` entry in `kywi.config.ts`, a client component, and one key in the module map your site layer exports. Miss any of the three and the failure is somewhere else — a module missing from the palette, an "Unknown module" box on both the public page and the editor canvas, or an app that refuses to boot.

The step-by-step recipe ships with the scaffold as the `kywi-custom-modules` skill, in `.claude/skills/`, so an agent in your project already has it.

## One: the config entry

defineModule({ name: string // the layout node's type, and the MCP add_module type label: string // what the owner sees in the palette component: string // the key you map in step three category?: string // palette grouping props?: Record<string, ModulePropDefinition> propGroups?: Record<string, ModulePropGroup> // props-panel sections (0.30.0+) deprecated?: boolean // hide from the palette; existing placements keep rendering })

Changing it after pages exist orphans every placement.

export const docsModules: ModuleConfig[] = [ defineModule({ name: 'callout', label: 'Callout', component: 'callout', category: 'Docs', props: { kind: { type: 'select', label: 'Kind', options: [ { value: 'note', label: 'Note' }, { value: 'tip', label: 'Tip' }, { value: 'warning', label: 'Warning' }, { value: 'danger', label: 'Danger' }, ], defaultValue: 'note', }, title: { type: 'text', label: 'Title (optional)', defaultValue: '' }, body: { type: 'richText', label: 'Body', defaultValue: '' }, addedIn: { type: 'text', label: 'Added in version — e.g. 0.22.0', defaultValue: '' }, }, }), // … ]

## lib/docs/modules.config.ts — this site’s own kit

## Two: the component

A `'use client'` React component taking a single `{ props }` object. Every value in it arrives as `unknown` out of a JSONB document, so each one is coerced at the point of use — see [Designing module props](/developing/designing-module-props-for-the-person-who-edits-the-page/) for what the types mean to the owner, and [Custom-module hazards](/developing/custom-module-hazards/) for what a throw in here takes down with it.

## Three: the map, and how it reaches core

The map is a `ModuleComponentMap` keyed by the `name` from step one. Under the layer chain it does not reach core as a constructor argument: the site layer exports it, and the generated layer registry is what `createPublicPage` and `createAdminPage` read.

// lib/docs/index.ts — keys must match the defineModule names export const docsModuleComponents = { codeBlock: CodeBlock, callout: Callout, agentPrompt: AgentPrompt, // … } satisfies ModuleComponentMap // sites/docs/index.ts — the entire file export { moduleComponents as modules } from '../../lib/modules'

## lib/docs/index.ts, then sites/docs/index.ts

Three sites in this project export that same line, which is how one authored map serves all of them. The scaffold writes that re-export for you: `create-kywi-app` generates every `sites/<id>/index.ts` as exactly this line, so registering a module never means hunting for a fourth file — you edit the project-wide component map (this project's `lib/modules.tsx`) and the site layer already points at it. Within the chain a theme layer's entry for a name wins over the site layer's, and both win over the `modules` option still accepted by `createPublicPage` — that option, along with `frontEdit` and `personalizationRuntime`, is deprecated in favour of the layer.

An entry whose key is a built-in module's name replaces that built-in, on the public page and in the editor canvas alike: the renderer looks in the injected map first and only falls back to the built-ins. That is the supported way to change what a built-in module renders. `create-kywi-app eject <artifact>` does hand you a copy of one of core's own render artefacts to fork, but only for the four on its list — `nav`, `frontEdit`, `personalizationRuntime`, `jsLoader` — and a built-in module's renderer is not one of them; see [Upgrading core inside your project](/developing/upgrading-core-inside-your-project/) for what eject does and what it costs, and [The module palette](/authoring/the-module-palette-47-built-ins-in-seven-categories/) for the full list of built-ins.

## A map key with no config entry stops the app booting

The layer assertion runs at boot and throws `Unknown layered module "<name>" in sites.<site>. Define it in kywi.config.ts modules or use a built-in module name.` for any key in a layer's map that is neither a built-in nor present in `config.modules`. Registering in the config is load-bearing, not documentation — and the failure is a hard boot error, not a missing palette entry.

## Component references cross the RSC boundary; functions do not

The map is serialised into the flight payload for the client admin, so its values must be resolved client-component references — a resolver function there throws "Functions cannot be passed directly to Client Components" and 500s the page. The admin entry point additionally projects the layer registry through `clientLayerRegistry`, which strips the `templates` key wholesale; that is what lets a site layer hold a server `shell` or a `hydrateLayout` pass beside its modules without taking the admin down.

## Retiring one

`deprecated: true` hides a module from the palette and from the MCP `list_module_types` catalogue while every existing placement keeps rendering. Deleting the entry instead turns each of those placements into an "Unknown module" box. This is how the legacy `variantContainer` was retired, and it is the right move whenever pages already carry the module you are replacing.
