Reference

Configuration

Reference for kubb.config.ts with every option, default and example for the Kubb v5 UserConfig.

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.

kubb.config.ts

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:

kubb.config.ts

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:

	Type	Description
`input`	`string`	Positional input from `kubb generate <input>`. Overrides `config.input` when set.
`watch`	`boolean`	`true` in watch mode.
`logLevel`	`'silent' \| 'info' \| 'verbose'`	Current log level.
`config`	`string`	Path to the config file in use.
`reporters`	`Array<ReporterName>`	Reporters selected via `--reporter`, overriding `config.reporters`.

Multiple configurations (array)

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

kubb.config.ts

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.

Defaults

defineConfig from kubb/config and createKubb from kubb fill in these fields when you omit them. The bare @kubb/core engine applies none of them.

Field	Default
`root`	`process.cwd()`
`adapter`	`adapterOas()` from the bundled OpenAPI adapter
`parsers`	`[parserTs(), parserTsx(), parserMd()]`
`reporters`	`[cli, json, file, html]`
`plugins`	`pluginBarrel()` appended when not already present
`storage`	`fsStorage()`
`output.barrel`	`false`, so `pluginBarrel` generates nothing until you opt in
`output.format`	`false`
`output.lint`	`false`
`output.defaultBanner`	`'simple'`

Bundler integrations apply a smaller set: no parserMd and no reporters. See Build tools.

Top-level options

`name`

string

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

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.

kubb.config.ts

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`

string required

Directory for generated files, absolute or relative to root.

`output.mode`

'file' | 'directory'

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

Default: follows the shape of output.path.

'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.

kubb.config.ts

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/).

group works with the inferred directory mode, no mode needed. Set mode: 'directory' yourself only to override the inference, such as a directory name that carries a dot (path: 'clients.v2'). An explicit mode: 'file' still forbids group and stops the build with a KUBB_INVALID_PLUGIN_OPTIONS error, because a single file has nothing to group.

`output.clean`

boolean

Wipe output.path before regenerating.

Default: false.

Only use clean: true with a dedicated output folder. Kubb removes the entire directory.

`output.format`

'auto' | 'prettier' | 'biome' | 'oxfmt' | false

Formatter to run on every generated file.

Default: false.

'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`

'auto' | 'eslint' | 'biome' | 'oxlint' | false

Linter to run after generation.

Default: false.

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

`output.postGenerate`

Array<string | { name?: string; command: string }>

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.

kubb.config.ts

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`

{ type: 'all' | 'named' } | false

Behavior of the root index.ts barrel file at output.path, and the default every plugin inherits.

Default: false.

{ type: 'named' } re-exports each symbol by name, { type: 'all' } writes export *. See @kubb/plugin-barrel options for the export styles and the plugin-level nested flag, and Add barrel files for the setup steps.

`output.defaultBanner`

'simple' | 'full' | false

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

Default: 'simple'.

'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`

string | ((meta: BannerMeta) => string)

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:


`filePath`	`string`	Full output path of the file being generated.
`baseName`	`string`	File name only, for example `stocks.ts`.
`isBarrel`	`boolean`	`true` for `index.ts` re-export barrels.
`isAggregation`	`boolean`	`true` for group `[dir]/[dir].ts` aggregation files.

Barrel index.ts files stay banner-free by default. They get a banner only when the plugin sets output.banner, at which point the function runs with isBarrel: true.

`output.footer`

string | ((meta: BannerMeta) => string)

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<Plugin>

Array of Kubb plugins. Dependencies run first. A plugin that requires one missing from this array fails the run with KUBB_MISSING_DEPENDENCY.

`adapter`

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.

Default: adapterOas() (included with kubb).

Pass options to customize the adapter:

kubb.config.ts

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<Parser>

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.

Default: [parserTs(), parserTsx(), parserMd()] (included with kubb).

Import parsers explicitly to override the default set:

kubb.config.ts

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

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.

Default: fsStorage().

kubb.config.ts

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

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

`root`

string

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

Default: process.cwd().

`reporters`

Array<Reporter>

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.

Default: [cli, json, file, html].

From spec to production.

Generate typed clients, review every change, and automate your OpenAPI workflow from local development to CI. Your spec stays on your infrastructure.

Try Kubb Studio Connect a project Create snapshots

Your API in Claude Desktop

Shared plugin options