---
layout: doc
title: Move from HeyAPI to Kubb
description: 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.
outline: [2, 3]
order: 8
navigation:
  title: Move from HeyAPI
  icon: i-iconoir-git-fork
---

> Index of every page on this site: [llms.txt](https://kubb.dev/llms.txt)

# 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`](/extensions/kubb-labs/plugin-ts) |
| `@hey-api/client-fetch` with `@hey-api/sdk` | [`pluginFetch`](/extensions/kubb-labs/plugin-fetch) |
| `@hey-api/client-axios` with `@hey-api/sdk` | [`pluginAxios`](/extensions/kubb-labs/plugin-axios) |
| `validator: true` on `@hey-api/sdk` | [`validator`](/extensions/kubb-labs/plugin-fetch/options#validator) on `pluginFetch` |
| `@tanstack/react-query` | [`pluginReactQuery`](/extensions/kubb-labs/plugin-react-query) |
| `zod` | [`pluginZod`](/extensions/kubb-labs/plugin-zod) |
| `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` |

::steps{level="2"}

## 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`.

```typescript [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:

:::code-group{sync="package-manager"}

```shell [kubb]
npm install -D kubb
kubb add adapter-oas
kubb add plugin-ts
```

```shell [pnpm]
pnpm add -D kubb @kubb/adapter-oas @kubb/plugin-ts
```

```shell [npm]
npm install -D kubb @kubb/adapter-oas @kubb/plugin-ts
```

```shell [yarn]
yarn add -D kubb @kubb/adapter-oas @kubb/plugin-ts
```

```shell [bun]
bun add -d kubb @kubb/adapter-oas @kubb/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:

:::code-group

```json [Before]
{
  "scripts": {
    "generate": "openapi-ts"
  }
}
```

```json [After]
{
  "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:

:::code-group

```typescript [HeyAPI]
import type { GetPetByIdData, GetPetByIdResponse, Pet } from './client'

type Path = GetPetByIdData['path']
```

```typescript [Kubb]
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:

:::code-group{sync="package-manager"}

```shell [kubb]
kubb add plugin-fetch
```

```shell [pnpm]
pnpm add -D @kubb/plugin-fetch
```

```shell [npm]
npm install -D @kubb/plugin-fetch
```

```shell [yarn]
yarn add -D @kubb/plugin-fetch
```

```shell [bun]
bun add -d @kubb/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:

```typescript [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:

:::code-group

```typescript [HeyAPI]
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 } })
```

```typescript [Kubb]
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 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](/extensions/kubb-labs/plugin-fetch/guides/error-handling).
- 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:

```typescript
client.setConfig({ auth: (scheme) => (scheme.type === 'apiKey' ? apiKey : token) })
```

[Configure requests](/extensions/kubb-labs/plugin-fetch/guides/configure-requests) covers `auth` and interceptors.

## Replace TanStack Query

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

:::code-group{sync="package-manager"}

```shell [kubb]
kubb add plugin-react-query
```

```shell [pnpm]
pnpm add -D @kubb/plugin-react-query
```

```shell [npm]
npm install -D @kubb/plugin-react-query
```

```shell [yarn]
yarn add -D @kubb/plugin-react-query
```

```shell [bun]
bun add -d @kubb/plugin-react-query
```

:::

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

:::code-group

```typescript [HeyAPI]
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: [] } })
```

```typescript [Kubb]
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`](/extensions/kubb-labs/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:

:::code-group{sync="package-manager"}

```shell [kubb]
kubb add plugin-zod
```

```shell [pnpm]
pnpm add -D @kubb/plugin-zod
```

```shell [npm]
npm install -D @kubb/plugin-zod
```

```shell [yarn]
yarn add -D @kubb/plugin-zod
```

```shell [bun]
bun add -d @kubb/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:

:::code-group

```typescript [HeyAPI]
import { zGetPetByIdPath, zPet } from './client/zod.gen'

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

```typescript [Kubb]
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`](/extensions/kubb-labs/plugin-fetch/options#validator) on `pluginFetch` so the client checks requests and responses against these schemas:

```typescript [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`.

::

## Sitemap

See the full [sitemap](https://kubb.dev/sitemap.md) for all pages.
