Kubb Configuration Guide

Configure Kubb using kubb.config.ts to control code generation behavior. This comprehensive guide covers all configuration options for customizing how Kubb generates TypeScript code from your OpenAPI specifications.

What is a Configuration File?

The Kubb configuration file (kubb.config.ts) defines:

Input source - Path to your OpenAPI/Swagger specification
Output settings - Where generated files are saved and how they're formatted
Plugins - Which code generators to use (TypeScript, React Query, Zod, etc.)
Generation options - Custom transformers, formatters, and advanced settings

Kubb uses Cosmiconfig to automatically discover configuration files in your project root.

Configuration File Discovery

Kubb automatically searches for config files in this order:

kubb.config.ts (recommended - TypeScript with type safety)
kubb.config.js (JavaScript ES modules)
kubb.config.mjs (JavaScript ES modules explicit)
kubb.config.cjs (CommonJS format)
.kubbrc (JavaScript format)

Alternative locations:

configs/kubb.config.ts (in a configs directory)
.config/kubb.config.ts (in a .config directory)

Why use TypeScript configuration?

Full type checking catches errors before runtime
IntelliSense autocomplete in VS Code and other editors
Inline documentation for all options
Easier refactoring and maintenance

TIP

Use TypeScript (kubb.config.ts) for the best developer experience with type safety and autocomplete.

defineConfig

The defineConfig helper provides TypeScript type checking and IntelliSense for your configuration:

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  // Type-safe configuration
  input
: { path
: './petStore.yaml' },
  output
: { path
: './src/gen' },
  plugins
: [],
})

Function form - Access CLI arguments:

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
(({ config
, watch
, logLevel
 }) => {
  return {
    input
: { path
: './petStore.yaml' },
    output
: {
      path
: './src/gen',
      clean
: !watch
, // Don't clean in watch mode
    },
    plugins
: [],
  }
})

Configuration Options

Configure Kubb's behavior with these options. All are optional unless marked as required.

name

Display name for this configuration in CLI output. Useful when running multiple configs.

Type:	`string`
Required:	`false`

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

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

root

Project root directory - can be absolute or relative to the config file location.

Type:	`string`
Required:	`false`
Default:	`process.cwd()`

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  root
: '.', // Relative to kubb.config.ts location
  input
: { path
: './petStore.yaml' },
  output
: { path
: './src/gen' },
})

input

OpenAPI specification source. Use either input.path or input.data (not both).

input.path

Path to your OpenAPI file - absolute or relative to root.

Type:	`string`
Required:	`true`*

NOTE

Required if input.data is not provided.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

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

input.data

OpenAPI specification as a string or object. Useful for programmatic generation.

Type:	`string \| unknown`
Required:	`true`*

NOTE

Required if input.path is not provided.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

// You can import a JSON file and pass it as data
export default defineConfig
({
  input
: {
    data
: { /* your OpenAPI spec object */ },
  },
  output
: { path
: './src/gen' },
})

output

Controls where and how files are generated.

output.path

Directory for generated files - absolute or relative to root.

Type:	`string`
Required:	`true`

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen', // All generated files go here
  },
})

output.clean

Remove the output directory before generating new files.

Type:	`boolean`
Required:	`false`
Default:	`false`

WARNING

This deletes the entire output.path directory. Only use with dedicated output folders.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    clean
: true, // Deletes ./src/gen before generating
  },
})

output.format

Code formatter to use on generated files.

Type:	`'auto' \| 'prettier' \| 'biome' \| false`
Required:	`false`
Default:	`'prettier'`

'auto' - Automatically detect and use available formatter (checks for biome, oxfmt then prettier)
'prettier' - Format with Prettier (default, included since v3.17.1)
'biome' - Format with Biome
'oxfmt' - Format with Oxfmt
false - Skip formatting

NOTE

Kubb respects your local .prettierrc or biome.json configuration files.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    format
: 'auto', // Automatically detect and use available formatter
  },
})

output.lint

Linter to run on generated files.

Type:	`'auto' \| 'eslint' \| 'biome' \| 'oxlint' \| false`
Required:	`false`
Default:	`false`

'auto' - Automatically detect and use available linter (checks for biome, oxlint, then eslint)
'eslint' - Lint with ESLint
'biome' - Lint with Biome
'oxlint' - Lint with Oxlint
false - Skip linting (default)

WARNING

Linting large outputs can slow down generation. Consider running linters separately in CI.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    format
: 'biome',
    lint
: 'auto', // Automatically detect and use available linter
  },
})

output.write

Set to false for a dry-run — files are generated in memory but nothing is persisted.

WARNING

Deprecated. Use output.storage instead. To disable writing, pass write: false — this remains supported for backwards compatibility.

Type:	`boolean`
Required:	`false`
Default:	`true`

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    write
: false, // dry-run — nothing written to disk
  },
})

output.storage

Where generated files are persisted. Defaults to fsStorage() — the built-in filesystem driver — which preserves the existing on-disk behavior.

Use defineStorage to create a custom driver for any backend (S3, Redis, in-memory, etc.).

Type:	`Storage`
Required:	`false`
Default:	`fsStorage()`

kubb.config.ts

typescript

import { defineConfig
, fsStorage
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    storage
: fsStorage
(), // explicit — same as the default
  },
})

Custom storage — use defineStorage to implement DefineStorage for any backend:

kubb.config.ts

typescript

import { defineConfig
, defineStorage
 } from '@kubb/core'

export const memoryStorage
 = defineStorage
(() => {
  const store
 = new Map
<string, string>()

  return {
    name
: 'memory',
    async hasItem
(key
) { return store
.has
(key
) },
    async getItem
(key
) { return store
.get
(key
) ?? null },
    async setItem
(key
, value
) { store
.set
(key
, value
) },
    async removeItem
(key
) { store
.delete
(key
) },
    async getKeys
(base
) {
      const keys
 = [...store
.keys
()]
      return base
 ? keys
.filter
(k
 => k
.startsWith
(base
)) : keys

    },
    async clear
(base
) {
      if (base
) {
        for (const k
 of store
.keys
()) {
          if (k
.startsWith
(base
)) store
.delete
(k
)
        }
      } else {
        store
.clear
()
      }
    },
  }
})

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

output.extension

Override file extensions in generated imports/exports. Useful for ESM compatibility.

Type:	`Record<KubbFile.Extname, KubbFile.Extname>`
Required:	`false`
Default:	`{ '.ts': '.ts' }`

TIP

Use { '.ts': '.js' } for ESM compatibility when converting TypeScript to JavaScript.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    extension
: {
      '.ts': '.js', // Import as .js instead of .ts
    },
  },
})

output.barrelType

Controls generation of barrel files (index.ts). This sets the root barrel file behavior.

Type:	`'all' \| 'named' \| false`
Required:	`false`
Default:	`'named'`

'all' - Export everything with export *
'named' - Export named exports only
false - Don't create barrel files

NOTE

Individual plugins have their own barrelType option. This controls the root src/gen/index.ts file.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

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

output.defaultBanner

Banner comment added to generated files. Indicates the file was auto-generated.

Type:	`'simple' \| 'full' \| false`
Required:	`false`
Default:	`'simple'`

'simple' - Basic banner with link and source file

typescript

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

'full' - Detailed banner with API title, description, and OpenAPI version
false - No banner

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    defaultBanner
: 'full', // Include full API details
  },
})

output.override

Overrides existing external files that Kubb can generate if they already exist. All plugins inherit this behavior from the global configuration by default. Individual plugins can override this behavior using their own output.override option.

Type:	`boolean`
Required:	`false`
Default:	`false`

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

export default defineConfig
({
  input
: { path
: './petStore.yaml' },
  output
: {
    path
: './src/gen',
    override
: true,
    // If external files that can be generated by Kubb are referenced in the config,
    // they will be overridden
  },
})

plugins

Type:	`Array<KubbUserPlugin>`
Required:	`false`

An array of Kubb plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to “pre” for more details. How to use and set up plugins, see plugins.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'
import { pluginOas
 } from '@kubb/plugin-oas'

export default defineConfig
({
  input
: {
    path
: './petStore.yaml',
  },
  output
: {
    path
: './src/gen',
  },
  plugins
: [
    pluginOas
({
      output
: {
        path
: 'schemas',
      },
      validate
: true,
    }),
  ],
})

Examples

Basic

TIP

When using an import statement you need to set "type": "module" in your package.json. You can also rename your file to kubb.config.mjs to use ESM or kubb.config.cjs for CJS.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

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

Conditional

Export the config as a function when it needs to be conditionally determined based on CLI flags. The function can return config options synchronously or asynchronously.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'

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

Multiple plugins

TIP

With version 2.x.x or higher we also support using multiple versions of the same plugin.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'
import { pluginOas
 } from '@kubb/plugin-oas'

export default defineConfig
(() => {
  return {
    root
: '.',
    input
: {
      path
: './petStore.yaml',
    },
    output
: {
      path
: './src/gen',
    },
    plugins
: [
      pluginOas
(
        {
          output
: {
            path
: 'schemas',
          },
        },
      ),
      pluginOas
(
        {
          output
: {
            path
: 'schemas2',
          },
        },
      ),
    ],
  }
})

Multiple configs

TIP

Since version 2.x.x or higher we also support using multiple configs.

kubb.config.ts

typescript

import { defineConfig
 } from '@kubb/core'
import { pluginOas
 } from '@kubb/plugin-oas'

export default defineConfig
([
  {
    name
: 'petStore',
    root
: '.',
    input
: {
      path
: './petStore.yaml',
    },
    output
: {
      path
: './src/gen',
    },
    plugins
: [
      pluginOas
(
        {
           output
: {
            path
: 'schemas',
          },
        },
      ),
    ],
  },
  {
    name
: 'petStoreV2',
    root
: '.',
    input
: {
      path
: './petStoreV2.yaml',
    },
    output
: {
      path
: './src/gen-v2',
    },
    plugins
: [
      pluginOas
(
        {
          output
: {
            path
: 'schemas',
          },
        },
      ),
    ],
  },
])

Kubb Configuration Guide ​

What is a Configuration File? ​

Configuration File Discovery ​

defineConfig ​

Configuration Options ​

name ​

root ​

input ​

input.path ​

input.data ​

output ​

output.path ​

output.clean ​

output.format ​

output.lint ​

output.write ​

output.storage ​

output.extension ​

output.barrelType ​

output.defaultBanner ​

output.override ​

plugins ​

Examples ​

Basic ​

Conditional ​

Multiple plugins ​

Multiple configs ​

Kubb Configuration Guide

What is a Configuration File?

Configuration File Discovery

defineConfig

Configuration Options

name

root

input

input.path

input.data

output

output.path

output.clean

output.format

output.lint

output.write

output.storage

output.extension

output.barrelType

output.defaultBanner

output.override

plugins

Examples

Basic

Conditional

Multiple plugins

Multiple configs