Extension manifest
kubb-extension.json describes your extension to the extension registry, kubb add, kubb init, kubb list, and the Studio agent. It sits at the package root and ships on npm. Generation reads the extension's meta instead.
Set $schema to https://kubb.dev/schemas/kubb-extension.json for editor validation and completion.
{
"$schema": "https://kubb.dev/schemas/kubb-extension.json",
"kind": "plugin",
"name": "plugin-example",
"export": "pluginExample",
"displayName": "Example",
"description": "Writes a comment with the HTTP method and path of every operation.",
"category": "documentation",
"icon": { "light": "https://example.com/icon.svg" },
"tags": ["comments", "operations"],
"docs": "https://github.com/acme/kubb-plugin-example#readme",
"maintainers": [{ "name": "Acme", "github": "acme" }],
"compatibility": { "kubb": ">=5.8.3", "node": ">=22" },
"options": [
{
"key": "prefix",
"path": ["prefix"],
"label": "Prefix",
"description": "Text written at the start of every comment.",
"type": "text"
}
]
}Fields
Readers ignore unknown top-level keys. Every URL must use HTTPS.
$schema
kind
kubb add adds a plugin or parser to the config, and prints the code for an adapter.name
meta.name, such as plugin-zod, oas, or typescript. Kubb skips a manifest whose name is not shaped like an npm package name.export
kubb.config.ts, such as pluginZod. It must be a JavaScript identifier.displayName
Zod.description
category
validation. The registry replaces it with the reviewer's pick.icon
media
tags
docs
maintainers
dependencies
["plugin-ts"]. kubb init checks that each one is chosen. At runtime, Kubb checks the plugin's own dependencies.optionalDependencies
["plugin-faker"]. List the runtime dependencies marked optional: true or picked from the options. kubb init does not require them.compatibility
@kubb/core) and Node.js. Any other key makes the manifest invalid. kubb add and kubb update check the ranges before they install. Kubb checks them at runtime through meta.compatibility, so import them from the manifest.role
client ships the HTTP client runtime, like @kubb/plugin-fetch. consumer calls a client but ships none, like @kubb/plugin-react-query. kubb init and Studio require a client next to a consumer.beta
true while the extension is in beta: it works, but its options and output can still change in a minor release. kubb.dev and Kubb Studio show a Beta badge next to its name. Remove the field, or set false, once it is stable.options
Option entries
Each options entry is one Studio form field that edits the value at path in the factory's options.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | A stable key, unique within the manifest, such as enumType. |
path | Array<string> | Yes | Where the value lives, such as ["enum", "type"]. No segment may be __proto__, constructor, or prototype. |
label | string | Yes | The field label. |
type | 'select' | 'boolean' | 'text' | 'number' | 'list' | Yes | The field type. |
description | string | No | Help text under the field. |
default | any JSON value | No | The plugin's runtime default, shown when unset. |
choices | Array<{ label?: string; value: JSONValue }> | For select | At least one. A null value leaves the option unset. A default must equal one of them. |
trueValue | any JSON value | No, for boolean | The value written for true. Defaults to true. |
falseValue | any JSON value | No, for boolean | The value written for false. Defaults to false. |
item | any JSON value | No, for list | A template for each entry, where every "$item" string becomes the entry. Without it, entries are strings. |
itemCase | 'upper' | No, for list | Uppercases each entry before writing it. |
Validation
Kubb skips an invalid manifest, and the registry review lists its problems. To run Kubb's checks in your own code, call isExtensionManifest(value) from kubb/kit. manifestProblems(manifest) lists the option problems of a well-formed manifest. Manifest validation lists what each reader checks.
Import compatibility into meta
Import only compatibility from the manifest into meta, so the ranges live in one file and a bundler leaves the rest, including options, out of your build:
import { defineExtension } from 'kubb/kit'
import { compatibility } from '../kubb-extension.json'
import { version } from '../package.json'
export const pluginExampleName = 'plugin-example'
export const pluginExample = defineExtension({
kind: 'plugin',
meta: { name: pluginExampleName, version, compatibility },
setup(options) {
return options
},
})Keep name as a typed constant, because a JSON import widens it to string.
tsc and "module": "NodeNext", write the ranges in meta.compatibility instead.Less common cases
Manifest validation
When Kubb skips your manifest or the registry review fails, see what each reader checks.
| Reader | Checks | On failure |
|---|---|---|
kubb add, kubb init, kubb update, kubb list, the Studio agent | The required fields and their shape, each maintainers and options entry, extension names in dependencies and optionalDependencies, role, beta, compatibility, unique option keys, and select choices and defaults. | The manifest is skipped. |
| The registry | The JSON Schema, unique option keys, choices on every select, and a select default that equals one of its choices. | The review pull request lists the problem, and the weekly bump keeps the previous pin. |
To run Kubb's checks in your own code, call isExtensionManifest(value) from kubb/kit. manifestProblems(manifest) lists the option problems of a well-formed manifest.
| Field | Rule |
|---|---|
name | Kubb skips a manifest whose name is not shaped like an npm package name: lowercase letters, digits, ., _, ~, and -, with an optional @scope/. |
compatibility | Any key other than kubb or node makes the manifest invalid, so a typo such as nodejs cannot skip a check. |
Option default | Studio does not write a value equal to it. |
Manifest readers
When you fill in a manifest field, this is what reads it.
| Field | Who reads it |
|---|---|
kind | Studio builds a form for every kind and lets users switch plugins on and off. |
export | kubb add imports it, and the Studio agent calls it. |
icon | Studio shows a generic icon when the manifest has none. |
maintainers | Each entry needs a name and can add a github username. |
dependencies | kubb.dev lists them. |
optionalDependencies | They match the runtime dependencies marked optional: true or picked from the options, such as ["plugin-faker"] for @kubb/plugin-msw with parser: 'faker'. |
