Move from openapi-typescript to Kubb
Start with the types, then replace openapi-fetch and openapi-react-query. You can stop after any step.
openapi-typescript gets no more updates, security fixes included, and openapi-fetch and openapi-react-query are in maintenance mode. openapi-typescript 7.13.0 also needs TypeScript 5 and fails on TypeScript 7, which Kubb supports.
What maps to what
| openapi-typescript | Kubb |
|---|---|
components['schemas']['Pet'] | Pet |
paths['/pet/{petId}']['get']['parameters']['path'] | GetPetByIdPath |
paths['/pet/{petId}']['get']['responses'][200]['content']['application/json'] | GetPetByIdStatus200Json |
--enum | enum: { type: 'enum' } on pluginTs |
client.GET('/pet/{petId}', { params: { path: { petId: 1 } } }) | getPetById({ path: { petId: 1 } }) |
createClient({ baseUrl }) | client.setConfig({ baseURL }) |
client.use({ onRequest }) | client.interceptors.request.use() |
$api.useQuery('get', '/pet/{petId}', ...) | useQuery(getPetByIdQueryOptions(...)) |
$api.useMutation('post', '/pet') | useMutation(addPetMutationOptions()) |
Generate the types
Create this config. It writes every type into src/gen/types.ts, like the single schema.d.ts from openapi-typescript. integerType: 'number' keeps int64 as number, as openapi-typescript 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 schema.d.ts in place until the last step, because openapi-fetch reads it. That file stops following the spec once openapi-typescript no longer runs. If you pause before the last step, run both commands in the script:
{
"scripts": {
"generate": "openapi-typescript ./openapi.yaml -o ./src/schema.d.ts"
}
}{
"scripts": {
"generate": "kubb generate"
}
}Replace the type lookups
Kubb exports each type by name, named after the schema or the operationId:
import type { components, paths } from './schema'
type Pet = components['schemas']['Pet']
type GetPetByIdParams = paths['/pet/{petId}']['get']['parameters']['path']import type { GetPetByIdPath, Pet } from './gen/types'Run your type check and fix the imports it reports.
Replace openapi-fetch
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:
import { pluginFetch } from '@kubb/plugin-fetch'
// ...
plugins: [
pluginTs({ output: { path: 'types.ts' } }),
pluginFetch({ baseURL: 'https://petstore.swagger.io/v2', throwOnErrorDefault: false }),
],throwOnErrorDefault: false keeps the openapi-fetch behavior: an error status resolves with error set instead of throwing. Run kubb generate, then replace each call:
import createClient from 'openapi-fetch'
import type { paths } from './schema'
const client = createClient<paths>({ baseUrl: 'https://petstore.swagger.io/v2' })
client.use({
onRequest({ request }) {
request.headers.set('Authorization', `Bearer ${token}`)
return request
},
})
const { data, error } = await client.GET('/pet/{petId}', { params: { path: { petId: 1 } } })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 } })Like the middleware, the interceptor sends the header on every request. To send it 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, so return the right credential per scheme:
client.setConfig({ auth: (scheme) => (scheme.type === 'apiKey' ? apiKey : token) })Configure requests covers both.
Replace openapi-react-query
Add @kubb/plugin-react-query. With a package manager, also 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. Run kubb generate, then replace each $api.useQuery and $api.useMutation call:
import createFetchClient from 'openapi-fetch'
import createClient from 'openapi-react-query'
import type { paths } from './schema'
const $api = createClient(createFetchClient<paths>({ baseUrl: 'https://petstore.swagger.io/v2' }))
const { data } = $api.useQuery('get', '/pet/{petId}', { params: { path: { petId: 1 } } })
const { mutate } = $api.useMutation('post', '/pet')
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: [] } })Remove openapi-typescript
Once nothing imports schema.d.ts, openapi-fetch, or openapi-react-query, delete schema.d.ts and uninstall openapi-typescript, openapi-fetch, and openapi-react-query.
