Basic Usage

1. Create the config

kubb.config.ts drives everything Kubb does. A minimal config points at your spec and an output directory.

kubb.config.ts

import {  } from 'kubb'

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

input.path accepts a local file path or a URL. output.clean: true wipes the output directory before each run.

2. Pick your plugins

Each output format is its own plugin. Add only the ones you need.

TypeScript types

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

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

Types + HTTP client

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

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

+ React Query hooks

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 },
  : [({ : { : 'models' } }), ({ : { : 'clients' } }), ({ : { : 'hooks' } })],
})

+ Zod + MSW

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

export default ({
  : { : './petStore.yaml' },
  : { : './src/gen', : true },
  : [
    ({ : { : 'models' } }),
    ({ : { : 'clients' } }),
    ({ : { : 'hooks' } }),
    ({ : { : 'schemas' } }),
    ({ : { : 'mocks' } }),
  ],
})

Plugin	Package	Generates
pluginTs	@kubb/plugin-ts	TypeScript types and interfaces
pluginAxios	@kubb/plugin-axios	Axios-based HTTP client functions
pluginReactQuery	@kubb/plugin-react-query	TanStack Query hooks
pluginZod	@kubb/plugin-zod	Zod validation schemas
pluginMsw	@kubb/plugin-msw	MSW request handlers

NOTE

pluginAxios, pluginReactQuery, and pluginMsw each require pluginTs in the same config. pluginReactQuery also calls a registered client plugin, so add pluginAxios or pluginFetch alongside it.

See the plugins catalogue for the full list.

3. Run generate

Terminal

command: kubb generate
output:
  - ◆  Generation started
  - ◇  @kubb/plugin-ts          completed in 98ms
  - ◇  @kubb/plugin-axios       completed in 77ms
  - ◇  @kubb/plugin-react-query completed in 201ms
  - ◇  @kubb/plugin-zod         completed in 134ms
  - ◇  @kubb/plugin-msw         completed in 63ms
  - ◇  Generation completed
  -
  -  Plugins  5 passed (5)
  -    Files  156 generated
  - Duration  1.2s
  -   Output  ./src/gen

Kubb creates one folder per plugin under output.path. Re-run it after every spec change. See kubb generate for flags like --watch and --reporter.

4. Use the generated code

Import paths follow the output.path values you set for each plugin.

Types

import type {  } from './gen/models/Pet'

const :  = { : 1, : 'Cat' }

HTTP client

import { getPetById } from './gen/clients/getPetById'

const { data: pet } = await getPetById({ path: { petId: 1 } })

React Query

import { useGetPetById } from './gen/hooks/useGetPetById'

function Pet({ id }: { id: number }) {
  const { data, isLoading } = useGetPetById({ path: { petId: id } })
  if (isLoading) return null
  return <span>{data?.name}</span>
}

Zod

import { petSchema } from './gen/schemas/petSchema'

const result = petSchema.safeParse(unknown)

MSW handlers

import { setupServer } from 'msw/node'
import { getPetByIdHandler } from './gen/mocks/getPetByIdHandler'

const server = setupServer(getPetByIdHandler())
server.listen()

5. Keep it in sync

Run npm run generate whenever the spec changes, then commit the output. To skip the manual step, unplugin-kubb generates during your build with Vite, Rollup, Webpack, and others.