@kubb/plugin-axios

@kubb/plugin-axios turns each OpenAPI operation into a typed async function that calls your API with axios. The path, query parameters, request body, response, and error shape all come from the spec, so a call stays in sync with the API it targets.

From your spec, the generated client gives you:

• Typed functions per operation with grouped path, query, headers, and body.
• A status-keyed result on every call, or a thrown ResponseError.
• Auth resolved from your OpenAPI security schemes.
• Serialization of parameters and bodies across content types, including multipart/form-data uploads and binary downloads.
• Runtime validation against @kubb/plugin-zod schemas.
• Typed server-sent events you read with for await.
• Interceptors and a custom transport for the send.
• Standalone functions or a class-based SDK.

It builds on @kubb/plugin-ts for the types, so add that to your config, and axios is a runtime dependency to install next to your app.

Each function takes one grouped options object ({ path, query, headers, body }) and returns a RequestResult of { status, data, error, contentType, request, response }, bundled into .kubb/client.ts. See error handling for throwOnError and the status-keyed result union.

The bundled client also exposes getUrl, which builds an operation's final URL without sending the request, useful for cache keys, prefetch, and links:

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

const url = client.getUrl({ url: '/pet/{petId}', path: { petId: 1 }, query: { status: ['available'] } })
// '/pet/1?status=available'

For a native axios field the runtime does not set (timeout, proxy, maxRedirects, decompress, onUploadProgress), pass options, on the client or per call, where a per-call value wins:

import { client } from './.kubb/client'
import { uploadFile } from './uploadFile'

client.setConfig({ options: { timeout: 10_000 } })

await uploadFile({ path: { petId: 1 }, body, options: { timeout: 2_000, onUploadProgress: (e) => console.log(e.loaded) } })

For cross-cutting concerns like retries and interceptors, reach for a custom transport instead.

Installation

bun

bun add -d @kubb/plugin-axios@beta

pnpm

pnpm add -D @kubb/plugin-axios@beta

npm

npm install --save-dev @kubb/plugin-axios@beta

yarn

yarn add -D @kubb/plugin-axios@beta

Dependencies

This plugin needs @kubb/plugin-ts in your config. Kubb runs it before plugin-axios so the functions can import the generated types. When validator is set to 'zod', also add @kubb/plugin-zod.

• @kubb/plugin-ts
• @kubb/plugin-zod

Example

kubb.config.ts

import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  plugins: [
    pluginTs(),
    pluginAxios({
      output: { path: 'clients', mode: 'directory', barrel: { type: 'named' } },
      baseURL: 'https://petstore.swagger.io/v2',
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Service`,
      },
    }),
  ],
})

See also

• axios
• @kubb/plugin-ts
• Changelog