Move from HeyAPI to Kubb
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
| HeyAPI | Kubb |
|---|---|
input, output | input, output.path |
@hey-api/typescript | pluginTs |
@hey-api/client-fetch with @hey-api/sdk | pluginFetch |
@hey-api/client-axios with @hey-api/sdk | pluginAxios |
validator: true on @hey-api/sdk | validator on pluginFetch |
@tanstack/react-query | pluginReactQuery |
zod | pluginZod |
GetPetByIdData | GetPetByIdOptions |
GetPetByIdData['path'] | GetPetByIdPath |
GetPetByIdResponse | GetPetByIdStatus200Json |
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, zGetPetByIdPath | petSchema, 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.
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-tspnpm add -D kubb @kubb/adapter-oas @kubb/plugin-tsnpm install -D kubb @kubb/adapter-oas @kubb/plugin-tsyarn add -D kubb @kubb/adapter-oas @kubb/plugin-tsbun add -d kubb @kubb/adapter-oas @kubb/plugin-tsChange 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"
}
}{
"scripts": {
"generate": "kubb generate"
}
}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']import type { GetPetByIdPath, GetPetByIdStatus200Json, Pet } from './gen/types'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-fetchpnpm add -D @kubb/plugin-fetchnpm install -D @kubb/plugin-fetchyarn add -D @kubb/plugin-fetchbun add -d @kubb/plugin-fetchkubb 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:
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 } })import { client } from './gen/.kubb/client'
import { getPetById } from './gen/clients/getPetById'
client.setConfig({ auth: () => token })
client.interceptors.request.use((request) => {
request.headers['X-Client'] = 'web'
return request
})
const { data, error, status } = await getPetById({ path: { petId: 1 } })Three things differ:
- The result also has
status, and a check on it narrowsdataanderror. - With
throwOnError: trueon a call, HeyAPI throws the error body. Kubb throws aResponseErrorwith the body inerror.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
authreturns 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-querypnpm add -D @kubb/plugin-react-querynpm install -D @kubb/plugin-react-queryyarn add -D @kubb/plugin-react-querybun add -d @kubb/plugin-react-queryThe 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: [] } })import { useMutation, useQuery } from '@tanstack/react-query'
import { addPetMutationOptions } from './gen/hooks/useAddPet'
import { getPetByIdQueryOptions } from './gen/hooks/useGetPetById'
const { data } = useQuery(getPetByIdQueryOptions({ path: { petId: 1 } }))
const { mutate } = useMutation(addPetMutationOptions())
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-zodpnpm add -D @kubb/plugin-zodnpm install -D @kubb/plugin-zodyarn add -D @kubb/plugin-zodbun add -d @kubb/plugin-zodKubb 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)import { getPetByIdPathSchema } from './gen/zod/getPetByIdSchema'
import { petSchema } from './gen/zod/petSchema'
const pet = petSchema.parse(json)
const path = getPetByIdPathSchema.parse(params)If @hey-api/sdk has validator: true, set validator on pluginFetch so the client checks requests and responses against these schemas:
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.
