Options

Options for @kubb/plugin-axios, which generates a type-safe HTTP client pinned to axios.

output ​

Where the generated .ts files are written and how they are exported.

output.path ​

Folder where the plugin writes its files, defaulting to 'clients' and resolved against the global output.path on defineConfig. For a single file, set output.mode: 'file' and give path a name with its extension, such as 'clients.ts'.

output.mode ​

'file' writes everything into a single file whose output.path must include the extension. 'directory' writes one file per operation under output.path. Leave it unset and Kubb reads output.path: a name with an extension means one file, anything else a directory.

output.barrel ​

Toggle the export style and depth to see the generated barrels.

Controls how the generated index.ts (barrel) re-exports the output. Accepts { type: 'named' } or { type: 'all' }, optionally with nested: true (for example { type: 'named', nested: true }) to write an index.ts in every subdirectory, or false to skip the barrel entirely. Kubb reads the plugin's own output.barrel first, falls back to config.output.barrel on defineConfig, and finally to false. Every generator plugin ships a default output that sets barrel: { type: 'named' }, but passing your own output replaces that object wholesale, so repeat barrel whenever you set output yourself.

output.banner ​

Text added to the top of every generated file, such as a license header or @ts-nocheck directive. Pass a string, or a function (meta: BannerMeta) => string that receives the document info (title, description, version, baseURL) and per-file context (filePath, baseName, isBarrel, isAggregation), so a directive can skip barrel files.

output.footer ​

Text added to the bottom of every generated file (string or (meta: BannerMeta) => string), like banner but for closing comments. Pair banner: '/* eslint-disable */' with footer: '/* eslint-enable */' to scope a lint disable to the generated file.

group ​

Switch the mode to see where these operations land on disk.

Splits generated files into subfolders by the operation's tag or URL path, each under {output.path}/{groupName}/. Without group, every file lands directly in output.path. It applies only to output.mode: 'directory'.

group.type ​

Property used to assign each operation to a group ('tag' | 'path'), required whenever group is set. An operation with no tag goes in the default group.

• 'tag' uses the operation's first tag.
• 'path' uses the first URL segment, such as pet for /pet/{petId}.

group.name ​

Function (context: { group: string }) => string that turns a group key into a folder name and wins over the default, which camelCases the tag or uses the first path segment.

baseURL ​

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

throwOnErrorDefault ​

Set throwOnErrorDefault: false to return documented error responses as values by default. This sets the fallback on each generated request and the default ThrowOnError type parameter on standalone functions and SDK methods. A call with throwOnError: true still throws for a non-2xx response and narrows its return type to successful responses.

pluginAxios({ throwOnErrorDefault: false })

const result = await getPetById({ path: { petId: 1 } })
if (result.error) console.error(result.error)

This setting applies to the whole plugin and cannot be set in override. Generated operations use it even when the client config changes; pass throwOnError on a call to override it. Query hooks continue to set throwOnError: true explicitly.

validator ​

Validates request and response bodies with schemas from @kubb/plugin-zod, which you add to the plugins list when either direction is 'zod'. false (the default) skips validation and returns the response cast to the generated type. 'zod' validates the success response body, plus the error body when a non-2xx call does not throw. { request?: 'zod', response?: 'zod' } opts in per direction, and with validation on the generated function throws a ParseError on invalid data.

comments ​

How much of each OpenAPI description reaches the JSDoc above each generated operation. Defaults to 'full', which emits every description in full, however many paragraphs the spec carries. 'brief' keeps the opening sentence and leaves every other tag such as @summary and the {@link} in place, cutting a description that runs on for 150 characters without a sentence ending at the last word before 120. 'none' emits no JSDoc, leaving the generated-by banner untouched. Descriptions are a third of the output on a large spec, so pick 'brief' or 'none' when file size matters more than editor hovers.

sdk ​

Generates a class-based SDK instead of standalone functions, where each tag client is an instance class whose constructor takes a client config and builds its own client, so every environment is a separate instance. mode: 'tag' (the default) emits one class per tag such as PetClient and StoreClient. Add sdk.name to also emit a composed root that instantiates every tag client from one shared config, reached as new PetStore(config).pet.getPetById(...). mode: 'flat' emits a single class named by sdk.name with every operation as a direct method. Leave sdk unset to keep the per-operation functions the query plugins consume.

mode: 'tag' needs one file per tag, so pairing it with a single-file output (output.mode: 'file', or an output.path that already names a file such as 'clients.ts') throws KUBB_INVALID_PLUGIN_OPTIONS. Use mode: 'flat' for a single-file SDK, or give output.path a directory so mode: 'tag' can split per tag.

Construct a class with a ClientConfig (baseURL, headers, and so on), then call a method with the grouped options object ({ path, query, headers, body }) and read data off the result.

import { PetClient } from './src/gen/clients/petClient'

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

Each call resolves to { status, data, error, contentType, request, response }. With the default throwOnErrorDefault: true setting, a resolved call means the request succeeded and data is set. Pass throwOnError: false to get the discriminated union instead, keyed on the top-level status.

const { status, data, error } = await pet.getPetById({ path: { petId: 1 }, throwOnError: false })

if (status === 200) {
  console.log(data) // data is the success body, error is undefined
} else {
  console.error(status, error) // status is the documented error code, error is its parsed body
}

returnType ​

Shape of the value a generated call resolves to. 'full' (the default) keeps { status, data, error, contentType, request, response }. 'data' unwraps that down to the bare success body when throwOnError is true, and falls back to the full result when throwOnError is false, since that result still needs error to tell success from failure.

pluginAxios({ returnType: 'data' })

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

This applies to the standalone functions and the class-based SDK. @kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-swr, and @kubb/plugin-mcp read the same option, so their hooks and tool handlers give you the success body as data either way.

To read response headers such as ETag under 'data', pass throwOnError: false on the call. It then resolves to the full result, and a non-2xx comes back on error instead of throwing:

const result = await getPetById({ path: { petId: 1 }, throwOnError: false })

if (result.error === undefined) {
  const etag = result.response.headers.etag
}

Dependent plugins (@kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-swr, and @kubb/plugin-mcp) also honor per-operation returnType set through override, so their generated hooks and handlers match the shape of the resolved <op>.

include ​

Generates only the operations and schemas that match at least one entry, and skips the rest. Each entry filters by tag, operationId, path, method, contentType, or schemaName, with a pattern that can be a string or a RegExp, both matched as a regular expression against the value. A string pattern is compiled with new RegExp(pattern), so it is not an exact match: pattern: 'pet' also matches 'petType' or 'superpet'.

export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType' | 'schemaName'
  pattern: string | RegExp
}

exclude ​

Skips any operation or schema that matches at least one entry, the opposite of include. Entries use the same type and pattern fields as include, and when both options match an item, exclude wins.

When operations are excluded on a client plugin (@kubb/plugin-fetch or @kubb/plugin-axios), dependent plugins (@kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-swr, @kubb/plugin-mcp) skip generating hooks or handlers for those operations automatically, without requiring duplicate exclude configurations.

override ​

Applies different plugin options to operations that match a pattern. Each entry takes the same type and pattern as include, plus an options object that accepts any plugin option except override, so rules cannot nest. The first matching entry merges onto the plugin defaults, and later entries do not stack.

export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType' | 'schemaName'
  pattern: string | RegExp
  options: Omit<Partial<Options>, 'override'>
}

When options such as returnType, output, or group are overridden on a client plugin (@kubb/plugin-fetch or @kubb/plugin-axios), dependent plugins (@kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-swr, @kubb/plugin-mcp) resolve and follow those per-operation options automatically.

resolver ​

Changes how the plugin names generated files and symbols. Pass a partial patch. Override only the members you want, and anything you omit keeps resolverClient. See Override a resolver for the this context and how a patch layers over the default.

type ResolverClientPatch = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  className?(name: string): string
  groupName?(name: string): string     // → 'PetClient'
  propertyName?(name: string): string
}

macros ​

Rewrites AST nodes before they are printed, without forking the generator. Each macro callback (such as schema or operation) receives the node and a context object, and returns a replacement or undefined to leave it as is. Omitted callbacks keep their defaults, and macros run in order, so a later one sees the output of an earlier one.