Skip to content
How-to guides

Configure generation

Configure common Kubb stacks, formatting, linting, post-generate commands, barrel files, git inputs, watch mode, and several specs in one run.

Each recipe is a complete kubb.config.ts. After Installation, replace ./petStore.yaml with your spec, install the listed packages, and run npx kubb generate. The kubb tab installs each plugin with kubb add at the version the extension registry pins. kubb add needs an existing kubb.config.ts, so run npx kubb init first if you have none.

With clean: true, Kubb removes ./src/gen before it generates, so keep your own files elsewhere.

Pick a stack

Types, an Axios client, and TanStack Query hooks for React.

npx kubb add plugin-ts
npx kubb add plugin-axios
npx kubb add plugin-react-query
npm install axios react @tanstack/react-query
kubb.config.ts
import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'
import { pluginReactQuery } from '@kubb/plugin-react-query'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen', clean: true },
  plugins: [pluginTs(), pluginAxios(), pluginReactQuery({ hooks: true })],
})

To use the global fetch instead of Axios, replace pluginAxios with pluginFetch from @kubb/plugin-fetch.

Format, lint, and run commands after generation

  • format and lint take a tool name, or 'auto' for the first one installed. Install the tools first, such as npm install -D @biomejs/biome oxlint.
  • output.postGenerate runs shell commands after formatting and linting. The example runs a typecheck script, such as "typecheck": "tsc --noEmit" in package.json.
kubb.config.ts
import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig({
  input: './petStore.yaml',
  output: {
    path: './src/gen',
    clean: true,
    format: 'biome',
    lint: 'oxlint',
    postGenerate: ['npm run typecheck'],
  },
  plugins: [pluginTs()],
})

Add barrel files

A barrel is an index.ts that re-exports a folder. defineConfig registers @kubb/plugin-barrel for you, with these defaults:

BarrelDefaultChange it with
Root, such as src/gen/index.tsOffoutput.barrel on defineConfig
Plugin folder, such as src/gen/types/index.ts{ type: 'named' } from the plugin's default outputbarrel inside the plugin's output, or false to drop it

This config turns on the root barrel, writes export * barrels in every TypeScript subfolder, and leaves the Zod files out of all barrels:

kubb.config.ts
import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen', barrel: { type: 'named' } },
  plugins: [
    pluginTs({ output: { path: 'types', barrel: { type: 'all', nested: true } } }),
    pluginZod({ output: { path: 'zod', barrel: false } }),
  ],
})
Your own output on a plugin replaces its default, barrel included. Set barrel in it, or the plugin falls back to the root output.barrel. A plugin writes a barrel only in directory mode, when its output.path has no file extension.

output.barrel shows each export style and the nested and namespace fields.

Read the spec from a git repository

When the spec lives in another repository, set input to git+<repo>#<ref>:<path>. Pin <ref> to a tag or commit so every run uses the same spec:

kubb.config.ts
import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig({
  input: 'git+https://github.com/org/api.git#v2.1.0:specs/openapi.yaml',
  output: { path: './src/gen' },
  plugins: [pluginTs()],
})

Kubb runs git from the PATH with your credentials, so a private repository works with your credential helper or SSH key. In CI, give the job read access to that repository. input has the full format.

Watch mode, several specifications, and scripts

ToDo this
Generate again when the local spec changesRun kubb generate --watch. A URL or git input generates once. See Watch mode details.
Generate from several specs in one runPass an array to defineConfig, each entry with its own plugins and output directory. Set a name per entry to tell them apart in the CLI output.
Drive Kubb from a scriptCall createKubb to run builds or read diagnostics.
Fail CI on an invalid specRun kubb validate before kubb generate.