Axios

Officialv5.5.11

@kubb/plugin-axios

Options

Pass these options to pluginAxios(). Shared options link to Shared plugin options.

Options overview

Option	Purpose	Default
`output`	Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`.	`{ path: 'clients', barrel: { type: 'named' } }`
`group`	Split output by tag or path: `type`, `name`.	None
`baseURL`	Base URL prepended to every request.	None
`throwOnErrorDefault`	Default error behavior and return type for generated operations.	`true`
`validator`	Validate request and response bodies with Zod.	`false`
`comments`	How much of each description reaches the JSDoc.	`'full'`
`sdk`	Emit a class-based SDK instead of standalone functions.	None
`returnType`	Shape of the value a generated call resolves to.	`'full'`
`include`	Keep only operations that match.	None
`exclude`	Skip operations that match.	`[]`
`override`	Apply different options per pattern.	`[]`
`resolver`	Customize generated names and file paths.	`resolverClient`
`macros`	Rewrite AST nodes before printing.	`[]`, run after the built-in client macros

Base URL prepended to every request. When omitted, each request uses the operation's relative path from the spec, with no server-URL fallback. A value with a ${...} interpolation is emitted as a template literal, so baseURL: '${process.env.API_URL}' reads the environment variable at runtime.


Type	`string`
Required	`false`

throwOnErrorDefault

Set throwOnErrorDefault: false to return documented error responses as values by default. It sets the fallback on each generated request and the default ThrowOnError type parameter on functions and SDK methods. It applies to the whole plugin, so override cannot set it. A call that passes throwOnError still wins. With throwOnError: true, a non-2xx response throws and the return type narrows to successful responses. Query hooks always pass throwOnError: true.


Type	`boolean`
Required	`false`
Default	`true`

// with pluginAxios({ throwOnErrorDefault: false })
const result = await getPetById({ path: { petId: 1 } })
if (result.status !== 200) console.error(result.status, result.error)

validator

Validates request and response bodies with schemas from @kubb/plugin-zod, so add pluginZod() too. An invalid body makes the generated function throw a ParseError.


Type	`false \| 'zod' \| { request?: 'zod'; response?: 'zod' }`
Required	`false`
Default	`false`

false

Default value. Skips validation and casts the response to the generated type.

'zod'

Validates the success response body and, when a non-2xx call does not throw, the error body.

{ request?: 'zod', response?: 'zod' }

Enables validation separately for requests and responses.

kubb.config.ts

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

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  plugins: [
    pluginTs(),
    pluginZod(),
    pluginAxios({ validator: { request: 'zod', response: 'zod' } }),
  ],
})

comments

Controls generated JSDoc.


Type	`'full' \| 'brief' \| 'none'`
Required	`false`
Default	`'full'`

'full'

Default value. Keeps complete descriptions and tags.

'brief'

Keeps the first sentence and other tags. Descriptions over 150 characters without a sentence ending are cut at the last word before 120.

'none'

Omits JSDoc but keeps the generated-by banner.

sdk

Generates a class-based SDK. Each instance takes its own client config, so environments can use separate clients. Leave sdk unset to keep the standalone functions that query plugins call.


Type	`{ mode?: 'tag' \| 'flat'; name?: string }`
Required	`false`

'tag'

Default value for sdk.mode. Generates one class per tag, such as PetClient. Set sdk.name to also get a root class that shares one config, used as new PetStore(config).pet.getPetById(...).

'flat'

Generates one class named by sdk.name, with every operation as a method. Supports single-file output.

mode: 'tag' needs one file per tag, so it throws KUBB_INVALID_PLUGIN_OPTIONS with single-file output. Use mode: 'flat' for a single file.

Methods take the same grouped options and return the same result as the standalone functions. See Call operations.

const pet = new PetClient({ baseURL: 'https://petstore.swagger.io/v2' })
const { data } = await pet.getPetById({ path: { petId: 1 } })

returnType

Shape of the value a generated call resolves to.


Type	`'full' \| 'data'`
Required	`false`
Default	`'full'`

'full'

Default value. Returns { status, data, error, contentType, request, response }.

'data'

Returns the success body when throwOnError is true. With throwOnError: false, returns the full result so callers can tell errors from successes.

pluginAxios({ returnType: 'data' })

const pet = await getPetById({ path: { petId: 1 } }) // Pet, not { status, data, ... }

It applies to the functions and the SDK. The query plugins and @kubb/plugin-mcp read it too, including a per-operation value set through override. To read headers such as ETag under 'data', pass throwOnError: false and read result.response.headers.

resolver

Overrides generated file and symbol names. Omitted members keep resolverClient. The shared members (name, file, imports) and the this context are described under resolver.


Type	`ResolverPatch<ResolverClient>`
Required	`false`

Partial override

type ResolverClientPatch = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  imports?(options: ResolveImportsOptions): Array<ImportNode>
  className?(name: string): string
  groupName?(name: string): string     // → 'PetClient'
  propertyName?(name: string): string
}