Upgrade from v4 to v5
Update the packages and the config, run Kubb, then fix the imports and call sites in your app.
Before you start
Use Node.js 22.22 or later, also in CI and Docker. Update kubb and your plugins to v5. Package names stay the same, except these:
| v4 package | v5 |
|---|---|
@kubb/plugin-oas | Remove it. kubb includes the OpenAPI adapter. |
@kubb/plugin-client with client: 'axios' or 'fetch' | @kubb/plugin-axios or @kubb/plugin-fetch. |
@kubb/plugin-client with your own client module | Keep it. |
@kubb/plugin-solid-query, @kubb/plugin-svelte-query | Remove them, with no replacement. |
Defaults that changed
| Behavior | v4 | v5 | Keep v4 behavior with |
|---|---|---|---|
output.format | 'prettier' | false | format: 'prettier' |
output.lint | 'auto' | false | lint: 'auto' |
| Root barrel | 'named' | false | output.barrel: { type: 'named' } |
| Tag folder | <tag>Controller | <tag> | group.name |
| React and Vue Query hooks | Generated | hooks: false, which still writes query keys and option factories | hooks: true |
| Client errors | Returned | Thrown, throwOnErrorDefault: true | throwOnErrorDefault: false |
OpenAPI int64 | number | bigint | integerType: 'number' on the adapter |
| SWR mutation arguments | Trigger shape opt-in | Always passed through trigger() | No option |
Migrate the config
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen', barrelType: 'named' },
hooks: { done: ['npm run typecheck'] },
plugins: [pluginOas({ serverIndex: 0 }), pluginTs({ enumType: 'asConst' }), pluginClient({ client: 'axios' })],
})import { defineConfig } from 'kubb/config'
import { adapterOas } from '@kubb/adapter-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'
export default defineConfig({
input: './petStore.yaml',
output: { path: './src/gen', barrel: { type: 'named' }, postGenerate: ['npm run typecheck'] },
adapter: adapterOas({ server: { index: 0 } }),
plugins: [pluginTs({ enum: { type: 'asConst' } }), pluginAxios()],
})| v4 | v5 |
|---|---|
defineConfig from @kubb/core | From kubb/config. |
input: { path } or input: { data } | The path, URL, spec string, or parsed object itself. The wrapper fails with KUBB_LEGACY_INPUT. |
output.storage | Top-level storage, with helpers from kubb/kit. |
hooks.done | output.postGenerate: strings or { name, command } objects. |
KUBB_HOOK_FAILED | KUBB_POST_GENERATE_FAILED. |
output.override | Removed. Use a storage driver to control writes. |
kubb:debug hooks, createDebugger | Removed. |
--debug | --reporter file. |
--log-level debug | --log-level verbose, or a reporter. |
OpenAPI adapter
defineConfig adds adapterOas(), the TypeScript, TSX, and Markdown parsers, and the barrel plugin. To pass adapter options, install @kubb/adapter-oas and set adapter.
| v4 | v5 on adapterOas |
|---|---|
dateType, integerType, unknownType, emptySchemaType, enumSuffix, contentType on plugins | The same names, set once. |
serverIndex, serverVariables | server: { index, variables }. |
discriminator: 'strict' | 'preserve', the default. |
discriminator: 'inherit' | 'propagate'. |
validate | Unchanged, true by default. |
Output layout
v4 output.barrelType | v5 output.barrel |
|---|---|
'named' | { type: 'named' } |
'all' | { type: 'all' } |
'propagate' (plugin only) | { type: 'named', nested: true } |
false | false |
- An
outputyou pass to a plugin replaces its default named barrel, so repeatbarrelin it. output.modefollowsoutput.path: a file extension means one file, otherwise a directory.groupwith file mode fails withKUBB_INVALID_PLUGIN_OPTIONS.- Tag folders drop the
Controllersuffix, orRequestsfor Cypress and MCP. To keep it, setgroup: { type: 'tag', name: ({ group }) => `${group}Controller` }.
Shared plugin options
| v4 | v5 |
|---|---|
transformers.name | resolver.name. Its input casing can differ from v4. Check the names, or call the exported resolver for the default casing. |
transformers.schema | macros. |
mapper | A schema macro or a printer.nodes override. |
generators | A custom plugin. |
paramsType, pathParamsType, paramsCasing | One { body, path, query, headers } object with the spec's names. For camelCase path params, set pathParamsCasing: 'camelcase' on the adapter. |
A group with a required parameter is required, and an unused group is typed never. Update positional call sites:
useGetPet(petId)
useFindPets({ status: 'available' })
useUpdatePet().mutate({ petId, data: pet })useGetPet({ path: { petId } })
useFindPets({ query: { status: 'available' } })
useUpdatePet().mutate({ path: { petId }, body: pet })HTTP clients
| v4 | v5 |
|---|---|
pluginClient({ client: 'axios' }) | pluginAxios() |
pluginClient({ client: 'fetch' }) | pluginFetch() |
clientType, wrapper | sdk, a class per tag by default. Leave it unset for the standalone functions query plugins use. |
dataReturnType | returnType, default 'full' |
parser: 'zod' | validator: 'zod' |
parser: 'client' | validator: false, the default. |
operations, clientType: 'staticClass', bundle, urlType | Removed. The client goes to .kubb/client.ts. URL-only helpers need a custom plugin. |
importPath to your own client module | pluginClient({ importPath }), without sdk or baseURL. |
- Calls return the full result object. Read
data, call.unwrap(), or setreturnType: 'data'for the body alone. - To inspect an error without throwing, pass
throwOnError: falseon the call.
const pet = await getPet(1)const { data: pet } = await getPet({ path: { petId: 1 } })TypeScript
| v4 | v5 |
|---|---|
enumType | enum.type |
enumTypeSuffix | enum.typeSuffix |
enumKeyCasing | enum.keyCasing |
enumType: 'asPascalConst' | enum: { type: 'asConst', constCasing: 'pascalCase' } |
- Request input types are named
*Optionsand keep spec names such aspet_id. - Enums default to a const-asserted object plus a
*Keytype union. Inline enum names are scoped to their operation.
See TypeScript options.
Zod
Upgrade zod to v4.
| v4 | v5 |
|---|---|
version | Removed. v5 prints Zod 4. |
typed: true | Removed. Set inferred: true to export z.infer type aliases. |
Inferred alias PetSchema | PetSchemaType |
wrapOutput | A printer.nodes override that decorates this.base(node). |
operations | Removed. Its operation and path maps need a custom plugin. |
listPets200Schema | listPetsStatus200Schema |
See Zod options.
React Query
- Register a client plugin: Axios, Fetch, or
@kubb/plugin-client. - Move
baseURLand validation to the client plugin, and removeparser. - Set
hooks: trueto keep theuse*hooks. - Replace
*MutationKeytype imports with the runtime key helper. TDataholds only 2xx responses, and errors useTError.- To defer a request, set TanStack Query's
enabledorskipToken. The generatedenabledguard is gone.
See React Query options.
Vue Query
Apply the React Query changes. See Vue Query options.
SWR
Apply the client and validation changes from React Query, and remove mutation.paramsToTrigger:
useUpdatePet().trigger({ path: { petId }, body: pet })To skip a request, set shouldFetch: false. The parameter-presence guard is gone. See SWR options.
Faker
Remove paramsCasing and mapper. Use macros or printers instead. See Faker options.
MSW
parser, handlers, and baseURL keep their v4 behavior. See MSW options.
Cypress
- Request helpers take grouped
*Options, then the unchangedPartial<Cypress.RequestOptions>. - Remove
dataReturnType. Helpers yield the body asCypress.Chainable<T>. - Imports use
*Optionsand*Responsenames.
See Cypress options.
MCP
- Register TypeScript, Zod, and an Axios or Fetch client, which
clientselects. - Move
baseURLto that client and removeparamsCasing.
See MCP options.
Verify the upgrade
Run kubb generate, review the changed files, and type-check your app. Most errors come from renamed imports, such as Status<code> response names and SchemaType Zod types.
Less common changes
Check the rows for your plugins.
| Area | Change |
|---|---|
| Output | format: 'auto' and lint: 'auto' try the oxc tools first. |
| HTTP clients | The client's auth resolver follows the spec's security schemes. |
| TypeScript | Open string unions keep suggestions with (string & {}). Shared fields of a discriminated union move into a common intersection. JSDoc drops the format suffix from @type, adds the spec's examples, and adds @type object for objects. |
| Zod | Output uses chained Zod 4 calls, functional wrappers with mini: true, and getters only for circular references. |
| React Query | client is 'axios' | 'fetch' | 'client', detected when exactly one is registered. The trailing client config excludes path, query, body, headers, and url. Suspense hooks always run. |
| Vue Query | Parameter groups accept MaybeRefOrGetter, unwrapped with toValue(). |
| Faker | Factories such as createPet keep their names and take a generic TData, so overrides keep their types. |
| MSW | A handler for an operation with a body accepts an HttpResponseResolver typed against that body. |
| Cypress | HTTP methods are uppercase. baseURL, exclude, include, and override keep their shape. There is no validator option. |
| MCP | Handlers receive grouped *Options plus the MCP ServerContext, call the generated client operations, and read res.data. |
