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. It generates TypeScript types and interfaces from your OpenAPI spec.

kubb.config.ts

import {  } from 'kubb'
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'
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'
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'
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'
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'
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'
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'
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'
import {  } from '@kubb/plugin-ts'

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

Run a hook after generation

Use hooks.done to run shell commands once generation finishes. Pass a single command or an array to run them in sequence. Commands run relative to the project root.

kubb.config.ts

import {  } from 'kubb'
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'
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'
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 @kubb/core. This fits monorepo orchestration and custom build pipelines.

Unlike defineConfig, createKubb adds no defaults. Pass adapter, parsers, and your plugins yourself.

generate.ts

import { ,  } from '@kubb/core'
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 Core API for the full Kubb instance API.

CI validation

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

kubb.config.ts

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

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