kubb-labs/kubb/config

Config Skill

This skill instructs agents on authoring a kubb.config.ts and picking the right @kubb/plugin-* packages. Generation runs through the kubb CLI (kubb generate), and the same build powers the bundled MCP server.

When to Use

• Setting up Kubb in a project
• Adding or swapping a generator plugin
• Debugging why generated output is missing or wrong

What It Does

• Shows the shape of a kubb.config.ts
• Lists the generator plugins and how to combine them
• Points at each plugin's Options type and kubb.dev docs page for authoritative options
• Describes the validate, init and generate workflow

Shape of a config

import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'
export default defineConfig({
  root: '.',
  input: {
    path: './petstore.yaml', // local file path or a remote URL
  },
  output: {
    path: './src/gen',
    clean: true, // wipe the output dir before each run
    barrel: { type: 'named' }, // generate index.ts barrels with named exports
  },
  plugins: [
    pluginTs({ output: { path: 'models' } }),
    pluginAxios({ output: { path: 'clients' } }),
  ],
})

Rules that matter:

• Set adapter options only when you need them, through a top-level

adapter: adapterOas({ ... }) from @kubb/adapter-oas (for validate, serverIndex, serverVariables, discriminator or contentType).

• pluginTs is the base. Each installed plugin's

node_modules/@kubb/plugin-<name>/kubb-extension.json says what else it needs:

• Add every name in dependencies.
• A plugin with "role": "consumer" (the framework plugins and pluginMcp) also needs a plugin

with "role": "client": pluginAxios or pluginFetch.

• Names in optionalDependencies are needed only for some option values, such as pluginFaker

for pluginMsw({ parser: 'faker' }). The plugin's docs page names the option.

Before install, read the same lists on the plugin's docs page (https://kubb.dev/extensions/kubb-labs/plugin-<name>).

• Each generator plugin takes its own output.path, resolved relative to the top-level

output.path. Keep generated kinds in separate folders (models, clients, hooks, ...).

• input accepts { path } for a file or URL. Validate untrusted specs with kubb validate

before generating.

• Generation is destructive when output.clean is true. Never point output.path at

hand-written source.

• Set output.format or output.lint to 'auto' to format and lint generated files with

whatever tool the project already has (oxfmt, Biome, Prettier, oxlint or ESLint).

Available generator plugins

Pick plugins by what the consumer needs, then install kubb plus each package.

For an installed plugin's exact options, read its Options type from the installed package (node_modules/@kubb/plugin-<name>/src/types.ts or the published type declarations) and the plugin's docs page (https://kubb.dev/extensions/kubb-labs/plugin-<name>/options), which lists every option with defaults, the plugin dependencies, and the default output.path. Use those as the source of truth instead of guessing an option name.

Common combinations:

• Types only: pluginTs().
• Typed data fetching: add pluginAxios() or pluginFetch(). For hooks, add a framework plugin

(pluginReactQuery, pluginVueQuery or pluginSwr) next to that client plugin.

• Runtime validation: add pluginZod() and point the client at it for typed, validated responses.
• Testing and mocks: add pluginFaker() and pluginMsw().

Workflow

The commands wrap the kubb CLI, so the same steps work from a terminal.

1. Validate the spec with kubb validate <spec> before anything else.
2. Scaffold and install with kubb init. Pass --input, --output and --plugins to skip the

prompts, or write kubb.config.ts by hand using the shape above.

1. Generate with kubb generate. Pass --verbose when diagnosing why a file is missing or

malformed, and --watch to regenerate on spec changes.

1. Typecheck the generated output and wire it into the app.

Related Skills