Skip to content
Kit

Extension manifest

Reference for kubb-extension.json, the manifest a Kubb plugin, adapter, or parser ships on npm: its fields, Studio option entries, and validation.

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.

kubb-extension.json
{
  "$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

string
The JSON Schema URL. Only editors read it.

kind

'plugin' | 'adapter' | 'parser' required
What the package extends. kubb add adds a plugin or parser to the config, and prints the code for an adapter.

name

string required
The extension's meta.name, such as plugin-zod, oas, or typescript. Kubb skips a manifest whose name is not shaped like an npm package name.

export

string required
The factory users call in kubb.config.ts, such as pluginZod. It must be a JavaScript identifier.

displayName

string required
The human-readable name, such as Zod.

description

string required
One sentence on what the extension does.

category

string
A category for filtering, such as validation. The registry replaces it with the reviewer's pick.

icon

{ light: string; dark?: string }
Icon URLs for light and dark backgrounds.

media

Array<string>
Screenshots or videos.

tags

Array<string>
Search keywords.

docs

string
The documentation URL.

maintainers

Array<{ name: string; github?: string }>
The people who maintain the extension, shown on its kubb.dev page.

dependencies

Array<string>
The extensions that must be in the same config, such as ["plugin-ts"]. kubb init checks that each one is chosen. At runtime, Kubb checks the plugin's own dependencies.

optionalDependencies

Array<string>
The extensions the plugin uses when present, or needs only for some option values, such as ["plugin-faker"]. List the runtime dependencies marked optional: true or picked from the options. kubb init does not require them.

compatibility

{ kubb?: string; node?: string }
Semver ranges for Kubb (@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' | 'consumer'
Plugins only. 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

boolean
Set 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

Array<ExtensionManifestOption>
The form fields Kubb Studio shows for the extension. See Option entries.

Option entries

Each options entry is one Studio form field that edits the value at path in the factory's options.

FieldTypeRequiredDescription
keystringYesA stable key, unique within the manifest, such as enumType.
pathArray<string>YesWhere the value lives, such as ["enum", "type"]. No segment may be __proto__, constructor, or prototype.
labelstringYesThe field label.
type'select' | 'boolean' | 'text' | 'number' | 'list'YesThe field type.
descriptionstringNoHelp text under the field.
defaultany JSON valueNoThe plugin's runtime default, shown when unset.
choicesArray<{ label?: string; value: JSONValue }>For selectAt least one. A null value leaves the option unset. A default must equal one of them.
trueValueany JSON valueNo, for booleanThe value written for true. Defaults to true.
falseValueany JSON valueNo, for booleanThe value written for false. Defaults to false.
itemany JSON valueNo, for listA template for each entry, where every "$item" string becomes the entry. Without it, entries are strings.
itemCase'upper'No, for listUppercases 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:

src/plugin.ts
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.

Named JSON imports need a bundler that inlines them, such as tsdown. With plain 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.

ReaderChecksOn failure
kubb add, kubb init, kubb update, kubb list, the Studio agentThe 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 registryThe 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.

FieldRule
nameKubb skips a manifest whose name is not shaped like an npm package name: lowercase letters, digits, ., _, ~, and -, with an optional @scope/.
compatibilityAny key other than kubb or node makes the manifest invalid, so a typo such as nodejs cannot skip a check.
Option defaultStudio does not write a value equal to it.

Manifest readers

When you fill in a manifest field, this is what reads it.

FieldWho reads it
kindStudio builds a form for every kind and lets users switch plugins on and off.
exportkubb add imports it, and the Studio agent calls it.
iconStudio shows a generic icon when the manifest has none.
maintainersEach entry needs a name and can add a github username.
dependencieskubb.dev lists them.
optionalDependenciesThey match the runtime dependencies marked optional: true or picked from the options, such as ["plugin-faker"] for @kubb/plugin-msw with parser: 'faker'.