Migrate to v6

Upgrade @kubb/plugin-axios from v5 to v6, which runs on the shared client core from @kubb/plugin-client with axios as the transport.

Code that only calls the generated functions, SDK classes, or hooks needs a regenerate. Most other edits land in the file that configures client.

Upgrade steps

npm install --save-dev kubb@latest @kubb/plugin-axios@6

npx kubb generate

npx tsc --noEmit

What to change

Runtime values such as client still come from the generated .kubb/client.ts. The common rewrites:

 import type { RequestConfig } from '@kubb/plugin-axios/templates/axios.ts'
 import type { ResolvedRequest } from '@kubb/plugin-axios/templates/core.ts'
 import type { RequestConfig } from '@kubb/plugin-axios/templates/client.ts'
 import type { ResolvedRequest } from '@kubb/plugin-client/templates/core.ts'

 import { client, defaultTransport } from './gen/.kubb/client'
 import { client, createAxiosTransport, getAxiosInstance } from './gen/.kubb/client'

 defaultTransport.defaults.timeout = 10_000
 client.setConfig({ transport: axios.create({ baseURL }) })
 getAxiosInstance().defaults.timeout = 10_000
 client.setConfig({ transport: createAxiosTransport(axios.create({ baseURL })) })

 transport: async () => ({ data: { id: 1 }, status: 200, statusText: 'OK', headers: new Headers(), request, response })
 transport: async () => Response.json({ id: 1 })

client.interceptors.error.use((error) => {
  if (ResponseError.is(error) && error.status === 401) refreshToken()
  return error
})

 import type { ListPetsStatus4XX } from './gen/types/ListPets'
 import type { ListPetsStatus4xx } from './gen/types/ListPets'

 import { pet } from './gen/sdk/pet/pet'
 const api = new pet({ baseURL })
 import { PetClient } from './gen/sdk/pet/pet'
 const api = new PetClient({ baseURL })

Interceptors

client.interceptors handlers now get the core objects: ResolvedRequest, DecodedResponse, and the error. The quickest fix moves each handler, unchanged, to getAxiosInstance(), the instance v5 called defaultTransport:

client.interceptors.request.use((config) => {
  config.headers.set('X-Request-ID', crypto.randomUUID())
  return config
})

getAxiosInstance().interceptors.request.use((config) => {
  config.headers.set('X-Request-ID', crypto.randomUUID())
  return config
})

client.interceptors.request.use((request) => {
  request.headers['X-Request-ID'] = crypto.randomUUID()
  return request
})

Native response interceptors see the raw bytes, not the decoded body. The core form also works with @kubb/plugin-fetch.

Media types

serialize(body, contentType) becomes encode(body, context), with the type in context.contentType. decode(response, context) gets the Response, not a parsed body, so read the body yourself:

 client.setConfig({ codecs: { 'application/xml': { deserialize: (raw) => parseXml(raw as string) } } })
 client.setConfig({ mediaTypes: { 'application/xml': { decode: async (response) => parseXml(await response.text()) } } })

A key can be a pattern, such as text/*. See Built-in media types.

Streams

client.stream returns the stream directly:

 const { stream } = await toEventStream(client({ method: 'GET', url: '/events', responseType: 'stream' }), { shape: 'data' })
 const { stream } = await client.stream({ method: 'GET', url: '/events', eventShape: 'data' })

StreamResult and UnwrappedStreamResult take the responses record and the full event type, so wrap a payload in ServerSentEvent. A TypedEvent<…> stays as is:

 let result: EventStreamResult<PetEvent>
 let result: StreamResult<StreamPetsResponses, true, ServerSentEvent<PetEvent>>

An operation whose only success type is JSON Lines returns a StreamResult with one parsed item per line, not a string. For stream responses with headers, see Stream result types.

Behavior changes

These compile without errors, so check them by hand:

Also new in v6:

• Requests: body: null is sent as JSON null. A stream call sends Accept: text/event-stream, or its JSON Lines media type. An auth requirement with several schemes sends all of them.
• Responses: an empty body is undefined for every media type, text included. A failed call without a body has { status, statusText } as error. Every result and thrown ResponseError has the response Headers as headers.
• Validation: ResponseError.data holds the validated body.
• Types: a 2xx key is a success, a range key such as 4xx types status as the codes it covers, and an exact code such as 200 wins over a range. XML, YAML, and CSV responses are string, so JSON and XML together give data: Pet | string. Image, audio, video, PDF, and application/octet-stream responses are Blob, even with type: string. result.contentType is the bare media type, such as 'text/html'.
• Serializers: each has its own file in .kubb/serializers/, and setConfig({ serializer }) merges per key. A createClientCore client gets no serializers, so pass them in its serializer config.
• Servers: server.index no longer counts a server without a url.

If you upgrade from 5.12 or earlier, also check these changes.

Query plugins

@kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-swr, and @kubb/plugin-mcp work with v5 and v6, so you can upgrade them separately. They skip hooks for JSON Lines and event stream operations.

Less common cases

New in v6

These v6 features need no code change:

• Validation: validator.error takes a map by status, such as { 404: getPetStatus404Schema }, to check an error body against the schema of its status.
• Serializers: serializer.header and serializer.cookie are new. See Override parameter serialization.
• Servers: named servers are exported as servers from .kubb/client.ts. See Named servers.

From 5.12 or earlier

These changed in 5.13 and compile without errors:

• A stream call keeps the adapter set on the call or instance, such as a test mock. Only a browser call with the default adapters switches to the fetch adapter.
• A successful stream call with a non-stream body, such as JSON, throws a TypeError with the body as its cause. A successful answer with no body still ends as an empty stream.
• An event that does not end with a blank line is dropped, as in browser EventSource, so end every event with one.

SDK root class

With an SDK root class, add interceptors on api.client, because the root class shares one client with every tag. See sdk.