Move from orval to Kubb
Start with the types, then replace one orval output at a time: the client, the query hooks, the Zod schemas, and the mocks. You can stop after any step.
The examples move an orval config with client: 'react-query', httpClient: 'fetch', mock: true, and a second client: 'zod' output, all written to src/api.
What maps to what
| orval | Kubb |
|---|---|
output.schemas, Pet from ./api/model | pluginTs, Pet from ./gen/types |
PetStatus | petStatusEnum and PetStatusEnumKey |
httpClient: 'fetch' | pluginFetch |
httpClient: 'axios' | pluginAxios |
output.baseUrl | baseURL on pluginFetch |
mode: 'tags-split' | group: { type: 'tag' } on each plugin. It needs directory output, so remove the output option from pluginTs first |
A custom mutator | client.setConfig() and client.interceptors |
getPetById(1) | getPetById({ path: { petId: 1 } }) |
client: 'react-query', useGetPetById(1) | pluginReactQuery({ hooks: true }), useGetPetById({ path: { petId: 1 } }) |
mutate({ data: pet }) | mutate({ body: pet }) |
client: 'zod', GetPetByIdResponse | pluginZod, petSchema |
mock: true, getGetPetByIdMockHandler(), getPetMock() | pluginMsw, getPetByIdHandler(), handlers |
getGetPetByIdResponseMock() | pluginFaker, createPet() |
Generate the types
Create this config. It writes every type into src/gen/types.ts. integerType: 'number' keeps int64 as number, as orval 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/api in place until the last step, because the rest of the app still imports it:
{
"scripts": {
"generate": "orval"
}
}{
"scripts": {
"generate": "kubb generate"
}
}Then replace the model imports. Kubb names an enum's values petStatusEnum and its type PetStatusEnumKey:
import type { Pet } from './api/model'
import { PetStatus } from './api/model'
const status: PetStatus = PetStatus.availableimport type { Pet, PetStatusEnumKey } from './gen/types'
import { petStatusEnum } from './gen/types'
const status: PetStatusEnumKey = petStatusEnum.availableRun your type check and fix the imports it reports.
Replace the 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 behavior of orval's fetch client: an error status resolves instead of throwing. orval puts the error body in data. Kubb puts it in error and leaves data undefined. Run kubb generate, then replace each call:
import { getPetById } from './api/pet/pet'
const { data, status } = await getPetById(1, {
headers: { Authorization: `Bearer ${token}` },
})import { client } from './gen/.kubb/client'
import { getPetById } from './gen/clients/getPetById'
client.interceptors.request.use((request) => {
request.headers['Authorization'] = `Bearer ${token}`
return request
})
const { data, error, status } = await getPetById({ path: { petId: 1 } })The interceptor sends the header on every request, like a custom mutator that sets it. To send a credential only to operations that declare a security scheme, set auth instead. It gets each scheme, and its return value goes where that scheme says, such as the api_key header:
client.setConfig({ auth: (scheme) => (scheme.type === 'apiKey' ? apiKey : token) })Configure requests covers both.
Replace the query hooks
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-querySet hooks: true to get useGetPetById and useAddPet, as orval writes them. Without it, the plugin writes only the query and mutation options:
pluginReactQuery({ hooks: true }),Run kubb generate, then replace each hook. Two things differ from hooks on orval's fetch client:
- A hook's
dataholds the response body, not{ data, status, headers }. - An error status goes to the hook's
errorand toonError, whateverthrowOnErrorDefaultsays. With orval it resolves asdata, so move anystatuscheck ondatathere.
import { useAddPet, useGetPetById } from './api/pet/pet'
const { data } = useGetPetById(1)
const pet = data?.data
const { mutate } = useAddPet()
mutate({ data: { name: 'Rex', photoUrls: [] } })import { useAddPet } from './gen/hooks/useAddPet'
import { useGetPetById } from './gen/hooks/useGetPetById'
const { data: pet } = useGetPetById({ path: { petId: 1 } })
const { mutate } = useAddPet()
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-zodorval writes one schema per operation and inlines the model in each. Kubb writes one schema per model, such as petSchema, and the operation schemas refer to it. Run kubb generate, then replace each import:
import { GetPetByIdParams, GetPetByIdResponse } from './api/pet/pet.zod'
const pet = GetPetByIdResponse.parse(json)
const path = GetPetByIdParams.parse(params)import { getPetByIdPathSchema } from './gen/zod/getPetByIdSchema'
import { petSchema } from './gen/zod/petSchema'
const pet = petSchema.parse(json)
const path = getPetByIdPathSchema.parse(params)Replace the mocks
Add @kubb/plugin-faker and @kubb/plugin-msw. The generated code needs MSW 3 and @faker-js/faker 10, so upgrade them first if the app is on older versions:
kubb add plugin-faker
kubb add plugin-mswpnpm add -D @kubb/plugin-faker @kubb/plugin-mswnpm install -D @kubb/plugin-faker @kubb/plugin-mswyarn add -D @kubb/plugin-faker @kubb/plugin-mswbun add -d @kubb/plugin-faker @kubb/plugin-mswSet the options on pluginMsw. parser: 'faker' makes a handler return generated data, like orval's mocks, and handlers: true exports every handler as one list:
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'
// ...
plugins: [
// ...
pluginFaker(),
pluginMsw({ baseURL: 'https://petstore3.swagger.io/api/v3', parser: 'faker', handlers: true }),
],Run kubb generate, then replace the handlers and the mock data:
import { setupServer } from 'msw/node'
import { getGetPetByIdResponseMock } from './api/pet/pet.faker'
import { getGetPetByIdMockHandler, getPetMock } from './api/pet/pet.msw'
export const server = setupServer(getGetPetByIdMockHandler({ name: 'Rex', photoUrls: [] }), ...getPetMock())
const pet = getGetPetByIdResponseMock({ name: 'Rex' })import { setupServer } from 'msw/node'
import { getPetByIdHandler } from './gen/handlers/getPetByIdHandler'
import { handlers } from './gen/handlers/handlers'
import { createPet } from './gen/mocks/createPet'
export const server = setupServer(getPetByIdHandler({ name: 'Rex', photoUrls: [] }), ...handlers)
const pet = createPet({ name: 'Rex' })handlers holds every operation, where orval has one list per tag. Mock API responses has more.
Remove orval
Once nothing imports from src/api, delete src/api and orval.config.ts, and uninstall orval.
