Skip to content
Migrate

Move from orval to Kubb

Replace orval with Kubb. Generate the same types, then swap the client, query hooks, Zod schemas, and MSW mocks one step at a time.

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.

The config, before and after

The Kubb config is the result of every step below. Each step adds one plugin to it.

import { defineConfig } from 'orval'

export default defineConfig({
  petstore: {
    input: './openapi.yaml',
    output: {
      mode: 'tags-split',
      target: './src/api',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true,
    },
  },
  petstoreZod: {
    input: './openapi.yaml',
    output: {
      mode: 'tags-split',
      target: './src/api',
      client: 'zod',
      fileExtension: '.zod.ts',
    },
  },
})

What maps to what

Config options

orvalKubb
output.schemaspluginTs
httpClient: 'fetch'pluginFetch
httpClient: 'axios'pluginAxios
output.baseUrlbaseURL 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 mutatorclient.setConfig() and client.interceptors
client: 'react-query'pluginReactQuery({ hooks: true })
client: 'zod'pluginZod
mock: truepluginMsw and pluginFaker

Generated code

orvalKubb
Pet from ./api/modelPet from ./gen/types
PetStatuspetStatusEnum and PetStatusEnumKey
getPetById(1)getPetById({ path: { petId: 1 } })
useGetPetById(1)useGetPetById({ path: { petId: 1 } })
mutate({ data: pet })mutate({ body: pet })
GetPetByIdResponse (Zod)petSchema
getGetPetByIdMockHandler()getPetByIdHandler()
getPetMock()handlers
getGetPetByIdResponseMock()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.

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/api in place until the last step, because the rest of the app still imports it. Those files stop following the spec once orval no longer runs. If you pause before the last step, use orval && kubb generate as the script:

{
  "scripts": {
    "generate": "orval"
  }
}

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.available

Run 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-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 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}` },
})

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-query

Set hooks: true to get useGetPetById and useAddPet, as orval writes them. Without it, the plugin writes only the query and mutation options:

kubb.config.ts
pluginReactQuery({ hooks: true }),

Run kubb generate, then replace each hook. Two things differ from hooks on orval's fetch client:

  • A hook's data holds the response body, not { data, status, headers }.
  • An error status goes to the hook's error and to onError, whatever throwOnErrorDefault says. With orval it resolves as data, so move any status check on data there.
import { useAddPet, useGetPetById } from './api/pet/pet'

const { data } = useGetPetById(1)
const pet = data?.data

const { mutate } = useAddPet()
mutate({ data: { 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

orval 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)

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-msw

Set 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:

kubb.config.ts
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' })

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.