Options

Pass these options to pluginClient() to control what it generates and where the files go.

Option	Type	Default	Description
importPath	string	required	Import specifier of your client module
output	Output	{ path: 'clients', barrel: { type: 'named' } }	Where the generated files are written and exported
group	Group	—	Split output into per-tag or per-path folders
throwOnErrorDefault	boolean	true	Default throwOnError value passed to your client
validator	false | 'zod' | { request?: 'zod'; response?: 'zod' }	false	Pass Zod schemas to your client
include	Array<Include>	—	Keep only operations that match
exclude	Array<Exclude>	[]	Skip operations that match
override	Array<Override>	[]	Apply different options per pattern
resolver	ResolverPatch<ResolverClient>	—	Customize generated names and file paths
macros	Array<Macro>	—	Rewrite AST nodes before printing

NOTE

sdk, returnType, and baseURL from @kubb/plugin-fetch are not options here. This plugin generates standalone functions that return your client's promise, and your client owns the base URL.

importPath

Import specifier of your client module. The plugin writes it into every generated import exactly as given, so it must resolve from the generated file. Use a relative path, a package name, or an alias.

pluginClient({ importPath: '../../../client' }) // relative to src/gen/clients/<tag>/
pluginClient({ importPath: '@my-org/api-client' }) // a package

With group: { type: 'tag' } and output.path: 'clients', a generated file sits in src/gen/clients/<tag>/, so ../../../client points at src/client.ts. Without group it is ../../client.

The module must export client, plus the Options and RequestResult types. See write your client.

output

Where the plugin writes its generated .ts files and how it exports them.

output.path

Folder for the plugin's files, resolved against the global output.path on defineConfig and defaulting to 'clients'. To write everything to one file, set output.mode: 'file' and give path a file name with its extension, such as 'clients.ts'.

output.mode

How the plugin consolidates its code into files, either 'file' or 'directory'.

• 'file' writes everything into a single file, so output.path must include the extension (see above).
• '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.

• src/gen/
• models/
• Pet.ts
• User.ts
• clients/
• pet/
• getPetById.ts
• store/
• getInventory.ts

src/gen/index.ts

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.

clients/pet/

• getPetById
• addPet

clients/store/

• getInventory

clients/order/

• placeOrder
• getOrderById

clients/user/

• loginUser

group: { type: "tag" } splits the output by the operation tag, so placeOrder follows its order tag.

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'.

IMPORTANT

Combining group with output.mode: 'file' stops the build with a KUBB_INVALID_PLUGIN_OPTIONS error.

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. It defaults to the camelCased tag for a 'tag' group or the first path segment for a 'path' group, and a group.name you pass always wins.

throwOnErrorDefault

Default for the throwOnError field that every generated function passes to your client. It defaults to true. A call that sets throwOnError itself wins. Your client decides what the flag does: the example client throws on a non-2xx status when it is true and returns the error as a value when it is false.

The setting applies to the whole plugin, so you cannot set it in override.

validator

Passes Zod schemas from @kubb/plugin-zod to your client on config.validator, defaulting to false.

• false passes nothing.
• 'zod' passes the response and error schemas.
• { request?: 'zod', response?: 'zod' } opts in per direction.

The plugin does not run the schemas. Your client reads config.validator and validates. Add pluginZod() to the plugins list when validator is set. Generation stops with an error if it is missing. See validate requests and responses.

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'.

Type definition

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.

Type definition

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 by accepting 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.

TIP

Inside a method this is the full resolver, so this.default.name(name) reuses the built-in casing.

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.