Skip to content
Reference

Configuration

Reference for kubb.config.ts in Kubb v5. How Kubb finds and loads the config, the defaults defineConfig applies, and every top-level and output option.

kubb.config.ts tells Kubb which spec to read, where to write, and which plugins to run. Its default export is a defineConfig call:

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' },
  plugins: [pluginTs()],
})

How Kubb loads a config

Kubb loads the --config file. Without one, it loads the first kubb.config.ts or variant, such as .kubbrc.ts, in the working folder or a parent. See Config loading.

Config formats

defineConfig takes an object, a Promise of one, an array, or a function that returns any of these.

Config function

Pass a function when the config depends on how Kubb runs, such as watch mode:

kubb.config.ts
import { defineConfig } from 'kubb/config'

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

The function gets the CLI context:

FieldTypeValue
inputstring | undefinedThe kubb generate <input> argument, which overrides config.input
watchboolean | undefinedtrue in watch mode
logLevel'silent' | 'info' | 'verbose' | undefinedThe current --log-level
reportersArray<ReporterName> | undefinedThe --reporter names, such as ['json']
configstring | undefinedThe --config value, or undefined

Multiple configurations (array)

Pass an array to generate from several specs in one run. A config function can return an array too.

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()] },
])

Defaults

defineConfig from kubb/config and createKubb from kubb fill in these defaults for every option you leave out.

OptionDefault
inputNone. Required with an adapter.
output.pathNone. Required.
output.cleanfalse
output.formatfalse
output.lintfalse
output.barrelfalse, so no root index.ts
output.defaultBanner'simple'
pluginspluginBarrel(), appended when missing
adapteradapterOas(), the bundled OpenAPI adapter
parsers[parserTs(), parserTsx(), parserMd()]
storagefsStorage()
rootThe config file's folder, or the folder above .config/ or configs/
reporters[cli, json, file, html]

When you call createKubb yourself, root defaults to process.cwd(). createKubb from @kubb/core applies fewer defaults. The build tool integrations run fewer reporters. See Config loading.

Top-level options

name

string
The run heading the CLI prints before the input, such as petStore ./petStore.yaml. Unnamed configs show as kubb.

input

string | Record<string, unknown>

Where Kubb reads your spec. Required when an adapter is set, as defineConfig does by default. Kubb detects the kind:

ValueRead as
An objectA parsed spec
A string starting with { or [, spanning lines, or opening with openapi: or swagger:Inline JSON or YAML
A string starting with git+A file in a git repository
A URL stringA remote spec
Any other stringA file path, relative to root

A git input is git+<repo>#<ref>:<path> and needs git on the PATH.

import { defineConfig } from 'kubb/config'

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

See Git input for refs and credentials, and External $ref files.

output

Where and how Kubb writes files. output.mode, output.banner, and output.footer are plugin options only.

output.path

string required
The folder for generated files, absolute or relative to root. Plugin output paths resolve inside it.

output.clean

boolean

Remove every file in output.path before generating. Default: false.

Use clean: true only on a generated-code folder. Kubb stops with KUBB_CLEAN_ROOT when output.path is the project root or a parent of it.

output.format

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

The formatter for the generated files. Default: false.

'auto' runs the first installed of oxfmt, Biome, and Prettier. A tool name forces that tool, which reads its own config.

output.lint

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

The linter for the generated files. Default: false.

'auto' runs the first installed of oxlint, Biome, and ESLint. A tool name forces that tool.

output.postGenerate

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

Commands to run in order from root after formatting and linting, such as a type check. { name, command } labels 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'],
  },
})

Format, lint, and postGenerate run only after a build without errors. A failing step reports KUBB_FORMAT_FAILED, KUBB_LINT_FAILED, or KUBB_POST_GENERATE_FAILED.

output.barrel

{ type: 'all' | 'named' } | false
The root index.ts at output.path: { type: 'named' } or { type: 'all' }, as on the plugin-level output.barrel. Default: false. A plugin without its own output.barrel inherits it. See Add barrel files.

output.defaultBanner

'simple' | 'full' | false

The notice Kubb writes at the top of each generated file. Default: 'simple'. A plugin's output.banner replaces it.

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

plugins

Array<Plugin>
The plugins to run, in dependency order. Default: [], with pluginBarrel() appended when missing. A missing required dependency fails with KUBB_MISSING_DEPENDENCY. See Shared plugin options.

adapter

Adapter

Turns your input into Kubb's AST. Default: adapterOas(), bundled with kubb.

To pass options, such as adapterOas({ validate: false }), install and import @kubb/adapter-oas. kubb does not re-export it. See the adapter options.

parsers

Array<Parser>

Turn file nodes into source text, each for the extensions in its extNames. Default: [parserTs(), parserTsx(), parserMd()], bundled with kubb. A list you pass replaces the default. See @kubb/parser-ts.

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
Where generated files go. Default: fsStorage(), which writes to disk. memoryStorage() from kubb/kit keeps them in memory. See Storage for a custom backend.

root

string
The project root that input and output.path resolve against. Default: the config file's folder, or the folder above .config/ or configs/. A relative root resolves from that folder. See Config loading for createKubb.

reporters

Array<Reporter>
The reporters a run can use. Default: the built-in cli, json, file, and html reporters. The --reporter flag picks which ones run and defaults to cli.

From spec to production.

Generate typed clients from your API spec, review every change before it reaches your repository, and create snapshots in CI. Your spec stays on your infrastructure unless you allow Studio to read it.

Less common cases

Config loading

Without --config, kubb generate searches for a config file and turns its default export into one config per entry.

yesnofunctionobject or arraykubb generate--config set?Load that fileSearch the working folder,then each parentDefault exportCall it with the CLI contextOne config per entrydefineConfig fills defaultsResolve rootGenerate each config
  • In each folder, .kubbrc.* comes before kubb.config.*, and the folder before its .config/ and configs/ subfolders.
  • Extensions are tried in the order .ts, .mts, .cts, .js, .mjs, .cjs.
  • When nothing matches, the CLI stops and suggests kubb init.

Root folder

Without root, the root is the config file's folder, or its parent for a config in .config/ or configs/.

  • A relative root resolves from that folder.
  • createKubb without a config file uses process.cwd().

Defaults outside the CLI

Without kubb generate, fewer defaults apply:

  • createKubb from @kubb/core applies only the root, storage, output.format, output.lint, and output.defaultBanner defaults.
  • Build tool integrations apply the defineConfig defaults, but run only the summary reporter.

Extension commands

kubb add, kubb update, kubb list, and kubb remove read --config, or search for a config as kubb generate does. With several config entries, add and remove edit the first one. See Project files.

kubb validate

The adapter kubb validate runs depends on the config it finds. See Which adapter runs.

SituationAdapter
A config is found or passedEach entry's adapter. A local path resolves from the entry's root, or the current folder.
A config entry has no adapterNone. The command fails.
No config, or a found config that fails to load@kubb/adapter-oas. A --config file that fails to load fails the command.
  • An array config that repeats one adapter and input validates that pair once.
  • A URL or git input is passed unchanged. A git input is fetched into a temporary folder, validated, and deleted.

External $ref files

When your spec points at another file with a relative $ref, Kubb resolves it from the input file's folder. An object or inline input has no file, so its refs resolve from root. An OpenAPI 3.2 $self changes the base.

Some runs refuse local files:

RunLocal $ref files it reads
A URL inputNone, so a fetched spec cannot read your files
A Kubb Studio agentOnly files inside the project or the input's folder
A sandbox agentNone
A managed agentOnly files in the repository of a git input

To fix a refused file, move it into the project, start your agent with --allow-file-refs, or inline the schema.

Git input

For a spec in a git repository, write input as git+<repo>#<ref>:<path>.

  • <ref> is a branch, a tag, or a full commit SHA on hosts that fetch by SHA, such as GitHub and GitLab.
  • Leave out <ref>: to use the default branch.
  • Kubb runs a shallow git fetch into a temporary folder. It needs git on the PATH. For a private repository, it uses your git credentials.

See Read the spec from a git repository for a config.