Configuration

Where Kubb reads your spec: a local file path, a URL, a file in a git repository, 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. A string that starts with git+ is a git input. Anything else is a file path or a URL, and a relative path resolves against the config file.

Write a git input as git+<repo>#<ref>:<path>. <ref> is a branch, a tag, or a full commit SHA when the host allows fetching by SHA (GitHub and GitLab do); leave out <ref>: to use the default branch. Kubb runs a shallow git fetch into a temporary folder, so it needs git on the PATH, works with any host, and uses your own git credentials (credential helper or SSH key) for a private repository. Relative $ref files in the repository resolve as usual.

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({
  // a path, a URL, a git input, an inline JSON/YAML string, or a parsed object
  input: './petStore.yaml',
  output: { path: './src/gen' },
})

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.

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

Wipe output.path before regenerating.

Default: 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.

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.

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

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.

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

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:

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:

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

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:

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

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

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

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

Default: process.cwd().

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