Plugins: what one can contribute, and when
A plugin may contribute hooks, content types, modules, scope extensions and admin nav items — inline or by package — and can be gated to named sites.
A plugin is a config entry, not a package layout convention — and which of its contributions are live, and when, depends on whether you declared it inline or by package name.
What a plugin entry can carry
Everything a plugin can add to a running Kywi project, in one place: hooks, content types, modules, scope extensions and admin nav items, plus static config and an init function. package is the plugin's identity — it is what the per-site activation registry keys on — and siteIds narrows where its hooks fire.
| Name | Type | Default | Description |
|---|---|---|---|
hooks | Record<string, (payload, ctx) => unknown> | — | Event name → handler, registered on the same registry core's own handlers use. The second argument is { config }. |
contentTypes | ContentTypeConfig[] | — | Folded into config.contentTypes, so the migrator, the scope and the admin see them as if the app declared them. |
modules | ModuleConfig[] | — | Folded into config.modules — the module palette included. |
scopeExtensions | object | (ctx) => object | — | Merged into the scope. The factory form receives { config }, so a helper can close over the plugin's own settings. |
adminExtensions | { navItems: { label, path, icon? }[] } | — | Sidebar rows. Not surfaces — nothing renders the page behind the path for you. |
config | Record<string, unknown> | — | The plugin's static settings, handed to init, every hook and the scope factory. options is the deprecated spelling. |
init | (ctx) => void | Promise<void> | — | Called once at boot, before its hooks are registered. |
Inline and by-package are two different timings
An inline plugin's content types and modules are folded into the resolved config by defineKywiConfig itself, before anything boots. That is what makes them visible to the CLI migrator that creates their tables — a type that only appeared at runtime would have no schema. A package-only entry is resolved by dynamic import at boot instead, and its types join the running maps then, after migrations have already run.
A name clash goes to the app, in silence
A plugin content type or module whose name the app already declares is skipped. No warning, no error, no merge of fields — the app's definition simply stands and the plugin's is discarded. When a plugin's type appears to have no effect, check for a same-named entry in your own contentTypes first. See Designing a content type.
siteIds gates the hooks, not the types
siteIds is validated as an array, but that check runs only through kywi migrate, not at app boot — see Startup assertions — the config errors that fail a deploy. At runtime what actually filters is hook dispatch: each handler is wrapped so it returns early when the payload's site is outside the list. The plugin's content types and modules are already in the resolved config by then and exist everywhere. Per-site activation from the admin works the same way — a missing row means active, only an explicit deactivation stops a handler, and the toggle takes effect on the next event without a restart.
The gate reads the site from payload.siteId, falling back to payload.content.siteId. An event carrying neither is treated as ungated and the handler runs, whatever siteIds says — so a hook on a global event fires for a plugin scoped to one site. See Hooks: content-type hooks and the event bus for which events carry a site.
The CLI sees a thinner plugin than your app does
Anything that loads your config through parseKywiConfig gets the validator's parsed output, and the schema for a plugin entry is { package, options?, siteIds? }. Hooks, content types, modules, scope extensions and init are stripped from that view. The running app imports kywi.config.ts directly and keeps all of them — the two views genuinely differ, which is why a tool reporting on your config can disagree with the site.
BEFORE theme keys: [ 'name', 'regions', 'tokens', 'personalization' ]
BEFORE plugin keys: [ 'package', 'hooks', 'contentTypes', 'siteIds' ]
valid: true
AFTER theme keys: [ 'name', 'regions' ]
AFTER plugin keys: [ 'package', 'siteIds' ]Themes lose their tokens the same way — see Themes and design tokens and Config as code vs. the database.