Skip to content
Kit

Extensions

defineExtension in kubb/kit defines a plugin, adapter, or parser. Covers meta, compatibility checks, plugin dependencies, and factory statics.

defineExtension from kubb/kit defines an extension: a plugin, an adapter, or a parser. You pass it a definition object, and it returns a factory. The config calls that factory with the user's options.

defineExtension

kind picks what you define. The other fields follow from it:

PluginAdapterParser
kind'plugin''adapter''parser'
Config fieldpluginsadapterparsers
Definition fieldsmeta, setup, dependencies, enforce, hooksmeta, setup, buildmeta, build
ReceivesThe user's options and the setup contextsetup gets the user's options. build gets what setup returns.The user's options, or {}
ReturnsThe resolved options, from setupThe document and its methods, from buildThe parser methods, from build
RunsOnce per build, after the adapterFirstLast, as Kubb writes each file
DetailsPluginsAdaptersParsers
definePlugin, createAdapter, and defineParser are deprecated. Call defineExtension with the same object and add kind.

meta

meta holds the extension's identity. Kubb reads name and compatibility at runtime. Studio, the registry, and kubb.dev read the rest.

plugin-example.ts
import { defineExtension } from 'kubb/kit'

export const pluginExample = defineExtension({
  kind: 'plugin',
  meta: {
    name: 'plugin-example',
    version: '1.0.0',
    displayName: 'Example',
    description: 'Adds a comment to every generated schema.',
    compatibility: { kubb: '>=5.7.0', node: '>=22' },
  },
})
FieldTypeDescription
namestringRequired. Unique name, such as 'plugin-ts'.
versionstringPackage version. Dependents check their range against it.
displayNamestringHuman-readable name, such as 'TypeScript'.
descriptionstringOne sentence on what the extension generates or does.
categorystringRegistry category, such as 'types' or 'client'.
icon{ light: string; dark?: string }Icon URLs for light and dark backgrounds.
mediaArray<string>Screenshots or videos, as HTTPS URLs.
tagsArray<string>Search keywords for the registry.
compatibility{ kubb?: string; node?: string }Semver ranges for @kubb/core and Node.js. See Compatibility checks.
docsstringURL of the extension's docs page.
issuesstringIssue tracker URL. Kubb prints it as the report: link when the extension crashes.

Import version from package.json and compatibility from kubb-extension.json, so each lives in one file. Import compatibility into meta shows how. Named JSON imports need a bundler that inlines them, such as tsdown.

Compatibility checks

Before any plugin runs, Kubb checks each extension's meta.compatibility against the running @kubb/core and Node.js. A mismatch fails with KUBB_INCOMPATIBLE_EXTENSION. Compatibility ranges covers prereleases and canary builds.

dependencies

Only plugins take dependencies: the plugins yours builds on, keyed by meta.name. Kubb runs them first.

plugin-example.ts
import { defineExtension } from 'kubb/kit'

export const pluginExample = defineExtension({
  kind: 'plugin',
  meta: { name: 'plugin-example' },
  dependencies: {
    'plugin-ts': { version: '>=5.0.0' },
    'plugin-zod': { optional: true },
  },
})
Entry fieldTypeDescription
versionstringSemver range the dependency's meta.version must satisfy. Skipped when it has no meta.version.
optionalbooleanWhen true, a missing plugin is skipped. An installed one still gets its version checked.

Kubb checks the record before any plugin runs:

ProblemResult
A required entry is missing from the configFails with KUBB_MISSING_DEPENDENCY
An optional: true entry is missingSkipped
A meta.version is outside the entry's rangeFails with KUBB_INCOMPATIBLE_DEPENDENCY
The dependencies form a cycleFails with KUBB_INVALID_PLUGIN_OPTIONS

To pick dependencies from the user's options, pass a function. It receives the options and { config }:

plugin-example.ts
import { defineExtension, type PluginType } from 'kubb/kit'

type PluginExample = PluginType<'plugin-example', { parser?: 'data' | 'faker' }>

export const pluginExample = defineExtension<PluginExample>({
  kind: 'plugin',
  meta: { name: 'plugin-example' },
  dependencies: (options) => ({
    'plugin-ts': {},
    ...(options.parser === 'faker' ? { 'plugin-faker': {} } : {}),
  }),
})

Array dependencies covers the older array form.

Factory statics

Every factory carries kind and meta, so a tool can read them without calling the factory:

pluginExample.kind // 'plugin'
pluginExample.meta.name // 'plugin-example'

The extension the factory returns gets name (from meta.name), meta, and the user's raw options. See Hand-written extensions.

Less common cases

Compatibility ranges

When a run fails with KUBB_INCOMPATIBLE_EXTENSION, an extension's meta.compatibility does not match the running @kubb/core or Node.js.

  • kubb add checks it before it installs.
  • Prereleases compare like releases.
  • A canary build (0.0.0-canary-*) skips the kubb range.

Array dependencies

When a plugin declares dependencies as an array, such as dependencies: ['plugin-ts'], the array still works but only orders plugins.

FormA missing pluginVersions
An array of plugin namesSkipped. It never raises KUBB_MISSING_DEPENDENCY.Not checked
A record keyed by plugin nameA missing required plugin fails the run before any plugin runs.Out of range fails the run before any plugin runs. A dependency without meta.version is not checked.

Both forms set the order. Use the record form to fail early when a required plugin is missing or out of range.

Hand-written extensions

When you write a plugin or parser object by hand instead of calling a factory, Kubb fills in meta only from the deprecated name.

  • An object with only the deprecated name gets meta: { name }.
  • An object with neither name nor meta fails with KUBB_INVALID_PLUGIN_OPTIONS.