Skip to content
How-to guides

Move from HeyAPI to Kubb

Replace HeyAPI (@hey-api/openapi-ts) with Kubb. Generate the same types, then swap the SDK, TanStack Query options, and Zod schemas one step at a time.

Start with the types, then replace one HeyAPI plugin at a time: the SDK and client, TanStack Query, and Zod. You can stop after any step.

@hey-api/openapi-ts 0.99.0 fails on TypeScript 7, which Kubb supports.

The examples move a HeyAPI config that writes to src/client with the @hey-api/client-fetch, @hey-api/typescript, @hey-api/sdk, @tanstack/react-query, and zod plugins.

What maps to what

HeyAPIKubb
input, outputinput, output.path
@hey-api/typescriptpluginTs
@hey-api/client-fetch with @hey-api/sdkpluginFetch
@hey-api/client-axios with @hey-api/sdkpluginAxios
validator: true on @hey-api/sdkvalidator on pluginFetch
@tanstack/react-querypluginReactQuery
zodpluginZod
GetPetByIdDataGetPetByIdOptions
GetPetByIdData['path']GetPetByIdPath
GetPetByIdResponseGetPetByIdStatus200Json
getPetById({ path: { petId: 1 } })getPetById({ path: { petId: 1 } })
client.setConfig({ baseUrl, auth })client.setConfig({ baseURL, auth })
client.interceptors.request.use()client.interceptors.request.use()
getPetByIdOptions(...)getPetByIdQueryOptions(...)
addPetMutation()addPetMutationOptions()
zPet, zGetPetByIdPathpetSchema, getPetByIdPathSchema

Generate the types

Create this config. It writes every type into src/gen/types.ts, like the single types.gen.ts from HeyAPI. integerType: 'number' keeps int64 as number, as HeyAPI does. Kubb's default is bigint.

kubb.config.ts
import { defineConfig } from 'kubb/config'
import { adapterOas } from '@kubb/adapter-oas'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig({
  input: './openapi.yaml',
  output: { path: './src/gen' },
  adapter: adapterOas({ integerType: 'number' }),
  plugins: [pluginTs({ output: { path: 'types.ts' } })],
})

Install the packages it imports. kubb add needs the config to exist, and leaves a plugin that is already in it unchanged:

npm install -D kubb
kubb add adapter-oas
kubb add plugin-ts

Change your generate script to kubb generate and run it. Leave src/client in place until the last step, because the rest of the app still imports it:

{
  "scripts": {
    "generate": "openapi-ts"
  }
}

Then replace the type imports. Schema types keep their names. Kubb exports each part of a request by name, and names a response after its status and media type:

import type { GetPetByIdData, GetPetByIdResponse, Pet } from './client'

type Path = GetPetByIdData['path']

Run your type check and fix the imports it reports.

Replace the SDK and client

Add @kubb/plugin-fetch. It writes one function per operation, and the app needs no client package:

kubb add plugin-fetch

kubb add adds pluginFetch() to plugins. With a package manager, add the import and the plugin yourself. Then set its options, with your API's URL as baseURL. The Petstore URL is an example:

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

// ...
plugins: [
  pluginTs({ output: { path: 'types.ts' } }),
  pluginFetch({ baseURL: 'https://petstore3.swagger.io/api/v3', throwOnErrorDefault: false }),
],

throwOnErrorDefault: false keeps the HeyAPI behavior: an error status resolves with error set instead of throwing. HeyAPI reads the base URL from the spec's servers. Kubb does not, so set baseURL. Run kubb generate, then replace each import. The calls keep their shape:

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

client.setConfig({ auth: () => token })
client.interceptors.request.use((request) => {
  request.headers.set('X-Client', 'web')
  return request
})

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

Three things differ:

  • The result also has status, and a check on it narrows data and error.
  • With throwOnError: true on a call, HeyAPI throws the error body. Kubb throws a ResponseError with the body in error.data. See Handle errors.
  • When an operation lists several security schemes, HeyAPI sends the token to each of them. Kubb sends the first one that auth returns a token for, so return the right credential per scheme:
client.setConfig({ auth: (scheme) => (scheme.type === 'apiKey' ? apiKey : token) })

Configure requests covers auth and interceptors.

Replace TanStack Query

Add @kubb/plugin-react-query. With a package manager, also import pluginReactQuery from @kubb/plugin-react-query and add pluginReactQuery() after pluginFetch in plugins:

kubb add plugin-react-query

The plugin writes query and mutation options per operation, as HeyAPI does. Run kubb generate, then replace each import:

import { useMutation, useQuery } from '@tanstack/react-query'
import { addPetMutation, getPetByIdOptions } from './client/@tanstack/react-query.gen'

const { data } = useQuery(getPetByIdOptions({ path: { petId: 1 } }))
const { mutate } = useMutation(addPetMutation())
mutate({ body: { name: 'Rex', photoUrls: [] } })

Replace the Zod schemas

Add @kubb/plugin-zod. With a package manager, also import pluginZod from @kubb/plugin-zod and add pluginZod() to plugins. The schemas need Zod 4, so upgrade zod first if the app is on Zod 3:

kubb add plugin-zod

Kubb writes one file per schema and ends each name in Schema, where HeyAPI starts it with z. Run kubb generate, then replace each import:

import { zGetPetByIdPath, zPet } from './client/zod.gen'

const pet = zPet.parse(json)
const path = zGetPetByIdPath.parse(params)

If @hey-api/sdk has validator: true, set validator on pluginFetch so the client checks requests and responses against these schemas:

kubb.config.ts
pluginFetch({ validator: { request: 'zod', params: 'zod', response: 'zod' } }),

Remove HeyAPI

Once nothing imports from src/client, delete src/client and openapi-ts.config.ts, and uninstall @hey-api/openapi-ts.