Configure generation
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.
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-querynpm install -D kubb typescript @kubb/plugin-ts @kubb/plugin-axios @kubb/plugin-react-query
npm install axios react @tanstack/react-queryimport { 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 })],
})Types, an Axios client, and TanStack Query composables for Vue.
npx kubb add plugin-ts
npx kubb add plugin-axios
npx kubb add plugin-vue-query
npm install axios vue @tanstack/vue-querynpm install -D kubb typescript @kubb/plugin-ts @kubb/plugin-axios @kubb/plugin-vue-query
npm install axios vue @tanstack/vue-queryimport { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'
import { pluginVueQuery } from '@kubb/plugin-vue-query'
export default defineConfig({
input: './petStore.yaml',
output: { path: './src/gen', clean: true },
plugins: [pluginTs(), pluginAxios(), pluginVueQuery({ hooks: true })],
})Runtime validation with Zod, plus MSW request handlers backed by Faker.js mock data.
npx kubb add plugin-ts
npx kubb add plugin-zod
npx kubb add plugin-faker
npx kubb add plugin-msw
npm install zod msw @faker-js/fakernpm install -D kubb typescript @kubb/plugin-ts @kubb/plugin-zod @kubb/plugin-faker @kubb/plugin-msw
npm install zod msw @faker-js/fakerimport { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'
export default defineConfig({
input: './petStore.yaml',
output: { path: './src/gen', clean: true },
plugins: [pluginTs(), pluginZod(), pluginFaker(), pluginMsw({ parser: 'faker', handlers: true })],
})To use the global fetch instead of Axios, replace pluginAxios with pluginFetch from @kubb/plugin-fetch.
Format, lint, and run commands after generation
formatandlinttake a tool name, or'auto'for the first one installed. Install the tools first, such asnpm install -D @biomejs/biome oxlint.output.postGenerateruns shell commands after formatting and linting. The example runs atypecheckscript, such as"typecheck": "tsc --noEmit"inpackage.json.
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:
| Barrel | Default | Change it with |
|---|---|---|
Root, such as src/gen/index.ts | Off | output.barrel on defineConfig |
Plugin folder, such as src/gen/types/index.ts | { type: 'named' } from the plugin's default output | barrel 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:
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 } }),
],
})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:
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
| To | Do this |
|---|---|
| Generate again when the local spec changes | Run kubb generate --watch. A URL or git input generates once. See Watch mode details. |
| Generate from several specs in one run | Pass 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 script | Call createKubb to run builds or read diagnostics. |
| Fail CI on an invalid spec | Run kubb validate before kubb generate. |
