# Plugins: what one can contribute, and when

URL: https://kywi-docs-production.up.railway.app/developing/plugins-what-one-can-contribute-and-when
Type: docPage

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.

## 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.

## Any inline field means the package is never imported

The loader decides inline-versus-dynamic by looking for the presence of `hooks`, `contentTypes`, `modules`, `scopeExtensions`, `adminExtensions` or `init`. An entry carrying even one of them is treated as the whole plugin, and the module named by `package` is never loaded. So adding one inline hook to an installed plugin's entry does not extend it — it silently replaces it with a plugin that has one hook and nothing else.

## 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](/developing/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](/developing/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](/developing/hooks-content-type-hooks-and-the-event-bus/) for which events carry a site.

## A plugin that fails to load does not fail the boot

Resolution errors and a throwing `init` are both caught per plugin: the loader logs `[KywiPlugin] Failed to load plugin "<package>":` and moves on, deliberately, so one bad plugin cannot take down a deployment. The site comes up looking healthy with that plugin's hooks unregistered and its scope extensions missing.

## 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' ]

## defineKywiConfig output vs. validateConfig output, same object

Themes lose their tokens the same way — see [Themes and design tokens](/developing/themes-and-design-tokens/) and [Config as code vs. the database](/developing/config-as-code-vs-the-database/).
