Configuration
kubb.config.ts tells Kubb which spec to read, where to write, and which plugins to run. Its default export is a defineConfig call:
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:
import { defineConfig } from 'kubb/config'
export default defineConfig(({ watch }) => ({
input: './petStore.yaml',
output: { path: './src/gen', clean: !watch },
}))The function gets the CLI context:
| Field | Type | Value |
|---|---|---|
input | string | undefined | The kubb generate <input> argument, which overrides config.input |
watch | boolean | undefined | true in watch mode |
logLevel | 'silent' | 'info' | 'verbose' | undefined | The current --log-level |
reporters | Array<ReporterName> | undefined | The --reporter names, such as ['json'] |
config | string | undefined | The --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.
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.
| Option | Default |
|---|---|
input | None. Required with an adapter. |
output.path | None. Required. |
output.clean | false |
output.format | false |
output.lint | false |
output.barrel | false, so no root index.ts |
output.defaultBanner | 'simple' |
plugins | pluginBarrel(), appended when missing |
adapter | adapterOas(), the bundled OpenAPI adapter |
parsers | [parserTs(), parserTsx(), parserMd()] |
storage | fsStorage() |
root | The 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
petStore ./petStore.yaml. Unnamed configs show as kubb.input
Where Kubb reads your spec. Required when an adapter is set, as defineConfig does by default. Kubb detects the kind:
| Value | Read as |
|---|---|
| An object | A 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 string | A remote spec |
| Any other string | A 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' },
})import { defineConfig } from 'kubb/config'
export default defineConfig({
input: 'https://petstore3.swagger.io/api/v3/openapi.json',
output: { path: './src/gen' },
})import { defineConfig } from 'kubb/config'
export default defineConfig({
input: 'git+https://github.com/org/api.git#v2:specs/openapi.yaml',
output: { path: './src/gen' },
})import { defineConfig } from 'kubb/config'
export default defineConfig({
input: `
openapi: 3.1.0
info:
title: Pet Store
version: 1.0.0
paths: {}
`,
output: { path: './src/gen' },
})import { defineConfig } from 'kubb/config'
import spec from './petStore.json' with { type: 'json' }
export default defineConfig({
input: spec,
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
root. Plugin output paths resolve inside it.output.clean
Remove every file in output.path before generating. Default: false.
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
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
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
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.
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
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
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.
*//**
* Generated by Kubb (https://kubb.dev/).
* Do not edit manually.
* Source: petStore.yaml
* Title: Pet Store
* OpenAPI spec version: 1.0.0
*/// no bannerplugins
[], with pluginBarrel() appended when missing. A missing required dependency fails with KUBB_MISSING_DEPENDENCY. See Shared plugin options.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
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.
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
fsStorage(), which writes to disk. memoryStorage() from kubb/kit keeps them in memory. See Storage for a custom backend.root
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
cli, json, file, and html reporters. The --reporter flag picks which ones run and defaults to cli.From spec to production.
Less common cases
Config loading
Without --config, kubb generate searches for a config file and turns its default export into one config per entry.
- In each folder,
.kubbrc.*comes beforekubb.config.*, and the folder before its.config/andconfigs/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
rootresolves from that folder. createKubbwithout a config file usesprocess.cwd().
Defaults outside the CLI
Without kubb generate, fewer defaults apply:
createKubbfrom@kubb/coreapplies only theroot,storage,output.format,output.lint, andoutput.defaultBannerdefaults.- Build tool integrations apply the
defineConfigdefaults, 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.
| Situation | Adapter |
|---|---|
| A config is found or passed | Each entry's adapter. A local path resolves from the entry's root, or the current folder. |
| A config entry has no adapter | None. 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:
| Run | Local $ref files it reads |
|---|---|
| A URL input | None, so a fetched spec cannot read your files |
| A Kubb Studio agent | Only files inside the project or the input's folder |
| A sandbox agent | None |
| A managed agent | Only 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 fetchinto a temporary folder. It needsgiton thePATH. For a private repository, it uses your git credentials.
See Read the spec from a git repository for a config.
