Basic Usage

1. Create the config

kubb.config.ts drives everything Kubb does. The minimum 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-client'

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

+ React Query hooks

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

pluginClient, pluginReactQuery, and pluginMsw each require pluginTs in the same config.

See the plugins catalogue for the full list.

3. Run generate

kubb generate

$ kubb generate◆  Generation started
◇  @kubb/plugin-ts          completed in 98ms
◇  @kubb/plugin-client      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 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 pet = await getPetById({ pathParams: { petId: 1 } })

React Query

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

function Pet({ id }: { id: number }) {
  const { data, isLoading } = useGetPetById({ pathParams: { 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

• Manual: run npm run generate whenever the spec changes and commit the output.
• Bundler integration: use unplugin-kubb to run generation as part of Vite, Rollup, Webpack, and others.