Skip to content
Kit

Extensions

The parts definePlugin and defineParser share in kubb/kit. Covers ExtensionMeta, compatibility ranges, plugin dependencies with version ranges, and the kind and meta that every extension factory carries.

Plugins and parsers are both extensions. definePlugin and defineParser take a definition object with meta. They also accept a factory function that returns the plugin or parser. Either way they return a factory that the config calls with the user's options, and the fields on this page work the same for both.

meta

meta holds the extension's identity and the Kubb and Node.js versions it supports. Kubb reads name and compatibility at runtime. Studio, the kubb.dev registry, and the docs read the rest.

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

export const pluginExample = definePlugin({
  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' },
  },
})
PropertyTypeDescription
namestringUnique name. The plugin's or parser's own name is deprecated in favor of it, and optional when meta.name is set. Required.
versionstringPackage version. Plugins that depend on this one check their version range against it.
displayNamestringHuman-readable name, such as 'TypeScript'.
descriptionstringOne-sentence summary of what the extension generates or does.
categorystringRegistry category, such as 'types' or 'client'.
icon{ light: string; dark?: string }Icon URLs, with an optional variant for dark backgrounds.
tagsArray<string>Search keywords for the registry.
compatibility{ kubb?: string; node?: string }Semver ranges for @kubb/core and Node.js.
docsstringURL of the extension's docs page.

Read version from your package.json so it stays in sync with what you publish:

import { version } from '../package.json'

Compatibility checks

Before any plugin runs, Kubb checks each plugin's and parser's meta.compatibility against the running @kubb/core and Node.js versions. A mismatch fails the run with KUBB_INCOMPATIBLE_EXTENSION, which names the extension and the version that is running. Kubb compares prerelease versions like regular ones.

dependencies

A plugin's dependencies lists the plugins it builds on, keyed by name. They run first when the config has them. Each entry decides what happens when a plugin is missing or has the wrong version:

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

export const pluginExample = definePlugin({
  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. Kubb skips the check when the dependency has no meta.version.
optionalbooleanWhen true, a missing plugin is skipped. An installed one still has its version checked.

Kubb checks the record before any plugin runs:

When a dependency depends on the user's options, pass a function. It receives the options and returns the record:

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

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

export const pluginExample = definePlugin<PluginExample>({
  meta: { name: 'plugin-example' },
  dependencies: (options) => ({
    'plugin-ts': {},
    ...(options.parser === 'faker' ? { 'plugin-faker': {} } : {}),
  }),
})
An array, such as dependencies: ['plugin-ts'], still works. It only orders plugins, so a missing one is skipped and versions are not checked.

Factory statics

Every factory definePlugin and defineParser return carries kind ('plugin' or 'parser'). A factory from the object form also carries meta, so tools can read an extension's metadata without calling the factory or knowing its options:

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

A factory built from a factory function has no meta on it, because Kubb only learns it by calling the factory. The plugin or parser it returns still has meta, which falls back to { name }.

See also

Testing

JSX