Skip to content

Build a custom module: the three-part contract

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.

lib/docs/modules.config.ts — this site’s own kitts
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: '' },
    },
  }),
  // …
]

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 for what the types mean to the owner, and 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, then sites/docs/index.tsts
// 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'

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 for what eject does and what it costs, and The module palette for the full list of built-ins.

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.