Recipes

Ready-made kubb.config.ts snippets for common setups. Copy one in, install the matching packages, and run kubb generate.

TypeScript only

The smallest setup, generating TypeScript types and interfaces from your OpenAPI spec.

kubb.config.ts

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

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true },
  : [()],
})

TypeScript + React Query

Generates types and TanStack Query hooks for React.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-axios'
import {  } from '@kubb/plugin-react-query'

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true },
  : [(), (), ()],
})

TypeScript + Vue Query

Generates types and TanStack Query hooks for Vue.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-vue-query'

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true },
  : [(), ()],
})

Zod schemas + MSW handlers

Runtime validation with Zod, plus MSW request handlers backed by Faker.js mock data.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-zod'
import {  } from '@kubb/plugin-faker'
import {  } from '@kubb/plugin-msw'

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true },
  : [(), (), (), ()],
})

Faker + Zod for testing

Generates Faker.js data factories next to Zod schemas. Use them in unit and integration tests.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-zod'
import {  } from '@kubb/plugin-faker'

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true },
  : [(), (), ()],
})

Pick the HTTP client

Choose Fetch or Axios by registering the matching plugin. Swap pluginFetch for pluginAxios to use the global fetch instead.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-axios'

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true },
  : [(), ()],
})

Multiple specifications

Generate from several specs in one run. Pass an array to defineConfig. Each entry runs on its own, with its own plugins and output directory.

Set a name per entry so each one shows up in the CLI output.

kubb.config.ts

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

export default ([
  {
    : 'petStore',
    : './petStore.yaml',
    : { : './src/gen/petStore', : true },
    : [()],
  },
  {
    : 'userApi',
    : './userApi.yaml',
    : { : './src/gen/userApi', : true },
    : [()],
  },
])

Conditional config (watch-aware)

Pass a function to defineConfig to read CLI context. Here it turns off clean in watch mode so incremental runs stay fast.

kubb.config.ts

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

export default (({  }) => ({
  : './petStore.yaml',
  : {
    : './src/gen',
    : !,
  },
  : [()],
}))

Run kubb generate --watch to regenerate on spec changes.

Format with Biome, lint with Oxlint

Format generated files with Biome and lint them with Oxlint on every build. Set format and lint to 'auto' to pick whichever tool is installed.

kubb.config.ts

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

export default ({
  : './petStore.yaml',
  : {
    : './src/gen',
    : true,
    : 'biome',
    : 'oxlint',
  },
  : [()],
})

Run a command after generation

Use output.postGenerate to run shell commands, such as a formatter pass or a type check, once the generated files are formatted and linted.

kubb.config.ts

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

export default ({
  : './petStore.yaml',
  : {
    : './src/gen',
    : ['biome check --write ./src/gen'],
  },
  : [()],
})

Monorepo with multiple outputs

Generate a different client library per package or team from one config file.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-axios'
import {  } from '@kubb/plugin-react-query'

export default ([
  {
    : 'public-api',
    : './specs/public.yaml',
    : { : './packages/public-api/src/gen' },
    : [(), (), ()],
  },
  {
    : 'admin-api',
    : './specs/admin.yaml',
    : { : './packages/admin-api/src/gen' },
    : [(), ()],
  },
])

Environment-aware configuration

Pick input and output from NODE_ENV so one config covers development, staging, and production.

kubb.config.ts

import {  } from 'kubb/config'
import {  } from '@kubb/plugin-ts'
import {  } from '@kubb/plugin-axios'

const  = .['NODE_ENV'] ?? 'development'

const  = {
  : {
    : 'http://localhost:3000/openapi.json',
    : { : './src/gen', : true },
  },
  : {
    : 'https://staging-api.example.com/openapi.json',
    : { : './src/gen', : true },
  },
  : {
    : './specs/production.json',
    : { : './src/gen', : true },
  },
} as 

export default ({
  ...[ as keyof typeof ],
  : [(), ()],
})

Programmatic build

Drive Kubb from a script with createKubb from the kubb package, paired with Diagnostics from kubb/kit. This fits monorepo orchestration and custom build pipelines. Unlike defineConfig, createKubb takes no defaults, so the script below passes adapter, parsers, and plugins explicitly.

generate.ts

import {  } from 'kubb'
import {  } from 'kubb/kit'
import {  } from '@kubb/adapter-oas'
import { ,  } from '@kubb/parser-ts'
import {  } from '@kubb/plugin-ts'

const  = ({
  : (),
  : [(), ()],
  : './petStore.yaml',
  : { : './gen' },
  : [()],
})

..('kubb:plugin:end', ({ ,  }) => {
  .(`${.} completed in ${}ms`)
})

const { ,  } = await .()

if (.()) {
  .('Generation failed')
  .(1)
}

.(`Generated ${.} files`)

Use .build() instead of .safeBuild() if you want it to throw on errors rather than return diagnostics. See the Kit API for the full Kubb instance API.

CI validation

Validate the OpenAPI spec and fail the build on errors. Use output.postGenerate to run kubb validate after generation.

kubb.config.ts

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

export default ({
  : './petStore.yaml',
  : { : './src/gen', : true, : ['kubb validate ./petStore.yaml'] },
  : [()],
})