Axios Plugin#

@kubb/plugin-axios generates a type-safe, per-operation async function for every OpenAPI operation, using Axios as the HTTP transport. It lives in the kubb-labs/plugins monorepo under packages/plugin-axios.

The plugin shares its option surface, resolver, and code-generation components with @kubb/plugin-fetch via a shared @internals/client package — only the template runtime differs. Consumer plugins (react-query, vue-query, swr, MCP) declare a dependency on plugin-axios by name and import the generated <op> functions rather than embedding their own HTTP client.

Entry Points#

Template-Driven Code Generation#

During the kubb:plugin:setup hook the plugin injects three static files into the project's .kubb/ directory 1:

• .kubb/client.ts — the full Axios runtime, copied verbatim from templates/axios.ts. If baseURL is set, the plugin appends client.setConfig({ baseURL: ... }) as a footer 2.
• .kubb/serializers.ts — query/body/path serializers from templates/serializers.ts.
• .kubb/standardSchema.ts — Standard Schema validation helper from templates/standardSchema.ts.

Generated operation files import client and RequestConfig / ResponseErrorConfig from .kubb/client.ts. The only runtime dependency in generated code is axios itself.

The per-operation clientGenerator calls createClientGenerator<PluginAxios>('axios') from @internals/client, which emits one async function per OpenAPI operation wrapping a single grouped options object.

Request Resolution Logic#

The central function is resolveRequest inside templates/axios.ts. It runs before every Axios call and handles:

1. Serialization — merges per-call and client-level serializers for query, body, and path; falls back to defaults 3.
2. Auth — calls resolveAuth which walks the per-operation security array and places the first resolved token in headers or query params.
3. Body — runs validator.request (if set), then serializes via codec or body serializer; strips Content-Type for FormData so Axios appends the multipart boundary 4.
4. throwOnError / validateStatus — resolved at line 485–486 (see next section).
5. Final AxiosRequestConfig — assembled at lines 490–503 and handed to activeInstance.request(...).

After the call, settleResponse decodes the body through the matching codec and runs validator.response or validator.error.

Consumer plugins resolve which client plugin to call via resolveClient (in @internals/client), which auto-detects plugin-axios when it is the only registered contract client, or accepts an explicit client: 'axios' selector. resolveClientOperation then caches the resolved function name and file path per operation node.

validateStatus and throwOnError#

Both are first-class fields on RequestConfig and ClientConfig.

Resolution order 5:

throwOnError = requestConfig.throwOnError ?? config.throwOnError ?? true
validateStatus = requestConfig.validateStatus ?? config.validateStatus ?? (throwOnError ? undefined : () => true)

• throwOnError: true (default) — validateStatus is left as undefined, so Axios uses its own default (throw on any non-2xx). When Axios throws, createClientCore catches the AxiosError and re-throws it as a ResponseError, a typed error class carrying data, status, statusText, contentType, request, and response.
• throwOnError: false — validateStatus is forced to () => true, telling Axios to resolve for every status. The response is then handed to settleResponse, which populates error instead of data for non-2xx responses. No ResponseError is thrown; callers switch on result.status or result.error.
• A custom validateStatus overrides both: you control exactly which statuses Axios throws for, independently of throwOnError.

The RequestResult type reflects this at the TypeScript level: with ThrowOnError extends true, the return type narrows to only the 2xx SuccessResultUnion; with false, it expands to the full ResultUnion including error variants 6.

Client-level defaults are set via client.setConfig({ throwOnError, validateStatus }) 7; per-call overrides go in the options argument of each generated function.

Plugin Options Reference#

Options are defined in @internals/client types and documented at docs.kubb.dev/kubb/plugins/plugin-client.