Configuration

kubb.config.ts drives a Kubb run. The file default-exports a defineConfig call. Pass it an object, a function that returns one, or an array of configs.

import { defineConfig } from 'kubb/config'

export default defineConfig({
  name: 'petStore',
  input: './petStore.yaml',
  output: { path: './src/gen' },
})

Config formats

Single config object

Export an object as in the example above. defineConfig also accepts a Promise of a config.

Config function

Pass a function when the config depends on the run context, such as watch or logLevel:

import { defineConfig } from 'kubb/config'

export default defineConfig(({ watch, logLevel }) => ({
  name: 'petStore',
  input: './petStore.yaml',
  output: { path: './src/gen', clean: !watch },
}))

The function receives this context:

Multiple configurations (array)

Pass an array to generate from several specs in one command:

import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig([
  {
    name: 'petStore',
    input: './petStore.yaml',
    output: { path: './src/gen/petStore' },
    plugins: [pluginTs()],
  },
  {
    name: 'stripe',
    input: './stripe.yaml',
    output: { path: './src/gen/stripe' },
    plugins: [pluginTs()],
  },
])

A config function can return an array to combine both forms.

Top-level options

name

A name for this config. The CLI prints it as Generating <name>....

input

Where Kubb reads your spec: a local file path, a URL, inline OpenAPI content as a JSON or YAML string, or an already-parsed object. Kubb detects which one you gave it. Required when an adapter is configured. Omit it in plugin-only mode, when there is no adapter.

A string that starts with { or [, spans multiple lines, or opens with a YAML openapi: or swagger: key is read as inline content. Anything else is a file path or a URL, and a relative path resolves against the config file.

import { defineConfig } from 'kubb/config'

export default defineConfig({
  // a path, a URL, an inline JSON/YAML string, or a parsed object
  input: './petStore.yaml',
  output: { path: './src/gen' },
})

output

Controls where and how files are written.

output.path

Directory for generated files, absolute or relative to root.

output.mode

How a plugin consolidates its code into files. Set it on a plugin's output, not on the root output.

'file' writes everything into a single file, so output.path must include the extension ('types.ts'). 'directory' writes one file per operation or schema under output.path. Pair 'directory' with group to split the output into per-tag or per-path subdirectories.

You rarely need to set this. Leave it out and Kubb reads output.path: a path with an extension means one file, a path without one means a directory. Every plugin ships an extensionless default such as 'types' or 'clients', so pluginTs() writes a directory without any configuration.

import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'

export default defineConfig({
  input: './petstore.yaml',
  output: { path: './src/gen' },
  plugins: [
    pluginTs({ output: { path: 'types.ts' } }),
    pluginAxios({ output: { path: 'clients', mode: 'directory' }, group: { type: 'tag' } }),
  ],
})

This writes every type into src/gen/types.ts and one client file per operation, grouped by tag (src/gen/clients/pet/, src/gen/clients/store/).

output.clean

Wipe output.path before regenerating.

output.format

Formatter to run on every generated file.

'auto' detects the first formatter it finds (oxfmt then Biome then Prettier). A named tool forces that one. false skips formatting. Kubb reads your local .prettierrc or biome.json.

output.lint

Linter to run after generation.

'auto' detects the first linter it finds (oxlint then Biome then ESLint). A named tool forces that one. false skips linting.

output.postGenerate

Shell commands to run after the generated files are formatted and linted, such as a type check or a custom script. Commands run from the root directory, in sequence. Pass a command string, or { name, command } to label a step in the CLI output.

import { defineConfig } from 'kubb/config'

export default defineConfig({
  input: './petStore.yaml',
  output: {
    path: './src/gen',
    postGenerate: [{ name: 'types', command: 'npm run typecheck' }, 'biome check --write ./src/gen'],
  },
})

output.barrel

Behavior of the root index.ts barrel file at output.path.

Provided by @kubb/plugin-barrel.

{ type: 'all' } writes export * from '...' for every file. { type: 'named' } writes export { … } from '...' using each file's named exports. false disables the root barrel.

// src/gen/index.ts
export { CreatePetRequest, Pet } from './pet'
export { User } from './user'
export type { GetPetQuery } from './operations/getPet'

// src/gen/index.ts
export * from './pet'
export * from './user'
export * from './operations/getPet'

// no index.ts generated

Each plugin keeps its own output.barrel for its sub-folder and can override the root setting. Setting barrel: false on a plugin disables that plugin's barrel and drops its files from the root barrel. The nested flag works at the plugin level only: { nested: true } writes a barrel in every subdirectory so callers can import from any depth. The root output.barrel ignores it.

output.defaultBanner

Auto-generated banner injected at the top of each file.

'simple' adds a short "Generated by Kubb" notice. 'full' adds the notice plus Source, Title, and OpenAPI spec version from the spec. false writes no banner.

/**
 * Generated by Kubb (https://kubb.dev/).
 * Do not edit manually.
 */

/**
 * Generated by Kubb (https://kubb.dev/).
 * Do not edit manually.
 * Source: petStore.yaml
 * Title: Pet Store
 * OpenAPI spec version: 1.0.0
 */

// no banner

output.banner

Text prepended to every file a plugin generates. Set it on an individual plugin. The root output exposes only output.defaultBanner. Use it for license headers, lint-disable comments, or framework directives like 'use server'.

A string applies to every file the plugin generates, including barrel (index.ts) and group aggregation ([dir]/[dir].ts) re-export files. A function runs once per file and receives a BannerMeta, so you can vary the banner per file or return an empty string to skip it.

BannerMeta extends the document InputMeta (title, description, version, …) with per-file context:

output.footer

Text appended to the end of every file a plugin generates. Mirror of output.banner, with the same string | ((meta: BannerMeta) => string) type.

plugins

Array of Kubb plugins. Dependencies run first. Missing dependencies fail when a generator requires them with ctx.requirePlugin.

adapter

Adapter that converts your input into the universal AST. With defineConfig from the kubb package this defaults to adapterOas() from @kubb/adapter-oas.

See the Adapter concept for the full picture.

Pass options to customize the adapter:

import { defineConfig } from 'kubb/config'
import { adapterOas } from '@kubb/adapter-oas'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  adapter: adapterOas({ validate: true }),
})

parsers

Array of parsers that turn the in-memory file representation into source code. Each parser declares which file extensions it handles through extNames.

See the Parser concept and @kubb/parser-ts for the built-in parsers.

Import parsers explicitly to override the default set:

import { defineConfig } from 'kubb/config'
import { parserTs, parserTsx } from '@kubb/parser-ts'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  parsers: [parserTs(), parserTsx()],
})

storage

Storage driver that persists generated files. Defaults to fsStorage() (filesystem).

See the Storage concept for the built-in drivers and how to write a custom backend.

import { defineConfig } from 'kubb/config'
import { memoryStorage } from 'kubb/kit'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  storage: memoryStorage(),
})

root

Project root, absolute or relative to the config file location.

reporters

Reporters available to the run, registered as instances. defineConfig registers the built-in cli, json, file, and html reporters by default. The HTML reporter remains opt-in: select it with --reporter html. The CLI --reporter flag selects reporters by name and defaults to cli. See that page for details about each reporter.