Use a custom transport#

The client Kubb generates splits into two layers: a shared core that builds the URL, serializes the query and body, resolves auth, and runs the interceptors, and a transport that takes the finished request and sends it last. Swap the transport and you change how a request leaves your app without touching anything the core already handled.

You set the transport at runtime on the client, not in kubb.config.ts. Plugin options control what gets generated, while the transport controls how those generated functions reach the network.

• @kubb/plugin-fetch takes a transport function.
• @kubb/plugin-axios takes an axios instance.

When to reach for it#

Most apps never need a custom transport. The defaults send through globalThis.fetch and axios.create(), and the auth, baseURL, and headers options cover the common cases. Replace the transport when the send itself needs to change:

• Add retries, timeouts, or circuit breaking around every request.
• Route through a runtime-specific HTTP client, such as undici on Node or a service-worker proxy in the browser.
• Capture metrics or structured logs for each call.
• Return canned responses in tests without hitting the network.

Fetch: a transport function#

@kubb/plugin-fetch types the transport as a function that receives a fully resolved request and returns a result:

type Transport = (request: ResolvedRequest) => Promise<TransportResult>

type ResolvedRequest = {
  url: string
  method: string
  headers: Record<string, string>
  body?: RequestBody
  signal?: AbortSignal
  credentials?: RequestCredentials
  options?: FetchOptions
  responseType?: ResponseType
}

type TransportResult<TData = unknown> = {
  data: TData
  status: number
  statusText: string
  headers: Headers
  contentType?: string
  request: Request
  response: Response
}

The core hands you a ResolvedRequest with the URL built, the query and body serialized, and auth headers set. Return the parsed data along with the native request and response, so status, headers, and the raw body stay reachable on the result.

Wrap the default send#

A custom transport can delegate to fetch and add behavior around it. This one retries a failed GET with exponential backoff:

import { client, type Transport } from './gen/.kubb/client'

const withRetry: Transport = async (request) => {
  const maxAttempts = 3

  for (let attempt = 1; ; attempt++) {
    const response = await globalThis.fetch(request.url, {
      method: request.method,
      headers: request.headers,
      body: request.body,
      signal: request.signal,
      credentials: request.credentials,
    })

    if (response.ok || request.method !== 'GET' || attempt === maxAttempts) {
      return {
        data: response.status === 204 ? undefined : await response.clone().json().catch(() => undefined),
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
        request: new Request(request.url),
        response,
      }
    }

    await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 100))
  }
}

client.setConfig({ transport: withRetry })

setConfig updates the shared client every generated function imports, so every call now retries. The core still parses data off the TransportResult you return and turns a non-2xx status into a thrown ResponseError when throwOnError is on, exactly as the default transport does.

Mock the network in tests#

Because the transport is the only piece that touches the network, a test can replace it with a function that returns a fixed result:

import { createClient } from './gen/.kubb/client'
import { getPetById } from './gen/clients/getPetById'

const testClient = createClient({
  transport: async (request) => ({
    data: { id: 1, name: 'Fluffy' },
    status: 200,
    statusText: 'OK',
    headers: new Headers(),
    request: new Request(request.url),
    response: new Response(),
  }),
})

const { data } = await getPetById({ path: { petId: 1 }, client: testClient })
// ^ { id: 1, name: 'Fluffy' }

createClient returns an isolated instance bound to your transport, so the test never mutates the shared client. Pass it per call with the client option, or hand it to a query plugin.

Axios: a custom instance#

@kubb/plugin-axios types the transport as an AxiosInstance. The default is axios.create(), and you replace it with your own pre-configured instance:

type ClientConfig = {
  // ...
  transport?: AxiosInstance
}

This keeps you on axios's own API for the send, so an instance you already configure elsewhere drops straight in. Kubb still owns the URL, query, body, and auth, then forwards them to the instance as an AxiosRequestConfig.

Pass a pre-configured instance#

Give the client an instance with a timeout, default headers, and a logging interceptor:

import axios from 'axios'
import { client } from './gen/.kubb/client'

const instance = axios.create({
  timeout: 10_000,
  headers: { 'X-Client': 'kubb' },
})

instance.interceptors.response.use((response) => {
  console.info(`${response.config.method?.toUpperCase()} ${response.config.url} -> ${response.status}`)
  return response
})

client.setConfig({ transport: instance })

Every generated function now sends through your instance, so its timeout, headers, and interceptors apply to each call.

Add retries with a plugin#

Because the transport is a real axios instance, axios plugins work on it. Wire up axios-retry on the instance you pass as the transport:

import axios from 'axios'
import axiosRetry from 'axios-retry'
import { createClient } from './gen/.kubb/client'

const instance = axios.create({ baseURL: 'https://petstore.swagger.io/v2' })
axiosRetry(instance, { retries: 3, retryDelay: axiosRetry.exponentialDelay })

export const apiClient = createClient({ transport: instance })

Where to set it#

A transport rides the same ClientConfig as baseURL and auth, so you set it the same three ways.

Call client.setConfig({ transport }) to cover the whole app at once, since every generated function imports the shared client. Call createClient({ transport }) for an isolated client you pass on the client option or hand to a query plugin, which suits tests and talking to more than one backend. Pass the transport option on a single request to override both for that one call.

See also#

• @kubb/plugin-fetch
• @kubb/plugin-axios
• Interceptors
• Authentication guide
• Set your own baseURL