Skip to content
Migrate

Upgrade from v4 to v5

Upgrade a Kubb v4 project to v5 with before and after tables for the config, the OpenAPI adapter, shared options, and each official plugin.

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 packagev5
@kubb/plugin-oasRemove 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 moduleKeep it.
@kubb/plugin-solid-query, @kubb/plugin-svelte-queryRemove them, with no replacement.

Defaults that changed

Behaviorv4v5Keep v4 behavior with
output.format'prettier'falseformat: 'prettier'
output.lint'auto'falselint: 'auto'
Root barrel'named'falseoutput.barrel: { type: 'named' }
Tag folder<tag>Controller<tag>group.name
React and Vue Query hooksGeneratedhooks: false, which still writes query keys and option factorieshooks: true
Client errorsReturnedThrown, throwOnErrorDefault: truethrowOnErrorDefault: false
OpenAPI int64numberbigintintegerType: 'number' on the adapter
SWR mutation argumentsTrigger shape opt-inAlways 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' })],
})
v4v5
defineConfig from @kubb/coreFrom kubb/config.
input: { path } or input: { data }The path, URL, spec string, or parsed object itself. The wrapper fails with KUBB_LEGACY_INPUT.
output.storageTop-level storage, with helpers from kubb/kit.
hooks.doneoutput.postGenerate: strings or { name, command } objects.
KUBB_HOOK_FAILEDKUBB_POST_GENERATE_FAILED.
output.overrideRemoved. Use a storage driver to control writes.
kubb:debug hooks, createDebuggerRemoved.
--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.

v4v5 on adapterOas
dateType, integerType, unknownType, emptySchemaType, enumSuffix, contentType on pluginsThe same names, set once.
serverIndex, serverVariablesserver: { index, variables }.
discriminator: 'strict''preserve', the default.
discriminator: 'inherit''propagate'.
validateUnchanged, true by default.

Output layout

v4 output.barrelTypev5 output.barrel
'named'{ type: 'named' }
'all'{ type: 'all' }
'propagate' (plugin only){ type: 'named', nested: true }
falsefalse
  • An output you pass to a plugin replaces its default named barrel, so repeat barrel in it.
  • output.mode follows output.path: a file extension means one file, otherwise a directory. group with file mode fails with KUBB_INVALID_PLUGIN_OPTIONS.
  • Tag folders drop the Controller suffix, or Requests for Cypress and MCP. To keep it, set group: { type: 'tag', name: ({ group }) => `${group}Controller` }.

Shared plugin options

v4v5
transformers.nameresolver.name. Its input casing can differ from v4. Check the names, or call the exported resolver for the default casing.
transformers.schemamacros.
mapperA schema macro or a printer.nodes override.
generatorsA custom plugin.
paramsType, pathParamsType, paramsCasingOne { 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 })

HTTP clients

v4v5
pluginClient({ client: 'axios' })pluginAxios()
pluginClient({ client: 'fetch' })pluginFetch()
clientType, wrappersdk, a class per tag by default. Leave it unset for the standalone functions query plugins use.
dataReturnTypereturnType, default 'full'
parser: 'zod'validator: 'zod'
parser: 'client'validator: false, the default.
operations, clientType: 'staticClass', bundle, urlTypeRemoved. The client goes to .kubb/client.ts. URL-only helpers need a custom plugin.
importPath to your own client modulepluginClient({ importPath }), without sdk or baseURL.
  • Calls return the full result object. Read data, call .unwrap(), or set returnType: 'data' for the body alone.
  • To inspect an error without throwing, pass throwOnError: false on the call.
const pet = await getPet(1)

TypeScript

v4v5
enumTypeenum.type
enumTypeSuffixenum.typeSuffix
enumKeyCasingenum.keyCasing
enumType: 'asPascalConst'enum: { type: 'asConst', constCasing: 'pascalCase' }
  • Request input types are named *Options and keep spec names such as pet_id.
  • Enums default to a const-asserted object plus a *Key type union. Inline enum names are scoped to their operation.

See TypeScript options.

Zod

Upgrade zod to v4.

v4v5
versionRemoved. v5 prints Zod 4.
typed: trueRemoved. Set inferred: true to export z.infer type aliases.
Inferred alias PetSchemaPetSchemaType
wrapOutputA printer.nodes override that decorates this.base(node).
operationsRemoved. Its operation and path maps need a custom plugin.
listPets200SchemalistPetsStatus200Schema

See Zod options.

React Query

  • Register a client plugin: Axios, Fetch, or @kubb/plugin-client.
  • Move baseURL and validation to the client plugin, and remove parser.
  • Set hooks: true to keep the use* hooks.
  • Replace *MutationKey type imports with the runtime key helper.
  • TData holds only 2xx responses, and errors use TError.
  • To defer a request, set TanStack Query's enabled or skipToken. The generated enabled guard 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:

src/app.ts
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 unchanged Partial<Cypress.RequestOptions>.
  • Remove dataReturnType. Helpers yield the body as Cypress.Chainable<T>.
  • Imports use *Options and *Response names.

See Cypress options.

MCP

  • Register TypeScript, Zod, and an Axios or Fetch client, which client selects.
  • Move baseURL to that client and remove paramsCasing.

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.

AreaChange
Outputformat: 'auto' and lint: 'auto' try the oxc tools first.
HTTP clientsThe client's auth resolver follows the spec's security schemes.
TypeScriptOpen 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.
ZodOutput uses chained Zod 4 calls, functional wrappers with mini: true, and getters only for circular references.
React Queryclient 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 QueryParameter groups accept MaybeRefOrGetter, unwrapped with toValue().
FakerFactories such as createPet keep their names and take a generic TData, so overrides keep their types.
MSWA handler for an operation with a body accepts an HttpResponseResolver typed against that body.
CypressHTTP methods are uppercase. baseURL, exclude, include, and override keep their shape. There is no validator option.
MCPHandlers receive grouped *Options plus the MCP ServerContext, call the generated client operations, and read res.data.