config

name: config description: How to author a kubb.config.ts and pick the right @kubb/plugin-* packages when generating TypeScript from an OpenAPI/Swagger spec. Use whenever setting up Kubb, adding a generator, or debugging codegen output.

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. The client plugins (pluginAxios, pluginFetch) need it, the framework plugins (pluginReactQuery, pluginVueQuery, pluginSwr) need pluginTs and a client plugin, and pluginMsw needs pluginTs and pluginFaker. Check the plugin's docs page on kubb.dev (https://kubb.dev/plugins/plugin-<name>) for the full dependency list.
• 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/plugins/plugin-<name>), 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(), or a framework plugin (pluginReactQuery, pluginVueQuery or pluginSwr) which pulls in client generation.
• 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 --input <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.
3. Generate with kubb generate. Pass --verbose when diagnosing why a file is missing or malformed, and --watch to regenerate on spec changes.
4. Typecheck the generated output and wire it into the app.

Related Skills