Options

Configuration options for @kubb/plugin-swr, passed to pluginSwr({ ... }). Every field is optional.

output ​

Where the generated .ts files are written and how they are exported. Defaults to { path: 'hooks', barrel: { type: 'named' } }.

output.path ​

Folder where the plugin writes its files (string, default 'hooks'), resolved against the global output.path on defineConfig. To write everything to one file instead, set output.mode: 'file' and give path a file name with its extension, such as 'hooks.ts'.

output.mode ​

How the plugin consolidates generated code ('file' | 'directory'). 'file' writes everything into a single file whose path must include the extension. 'directory' writes one file per operation under output.path and can be grouped into subdirectories. 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 that turns a group key into a folder or identifier name, used as the subdirectory name and as a suffix when naming aggregate files. Defaults to ({ group }) => camelCase(group), except type: 'path' groups use the first URL segment as-is.

client ​

Selects which registered client plugin the generated hooks call ('fetch' | 'axios'). 'fetch' calls the @kubb/plugin-fetch functions and 'axios' the @kubb/plugin-axios functions, both through one grouped options object. A client plugin must be registered. When only one is registered it is auto-detected, so client is only needed to disambiguate several.

query ​

Configures the generated useSWR hooks. Pass an object to change the HTTP methods or import path, or false to skip query hook generation. Defaults to { methods: ['GET'], importPath: 'swr' }.

query.methods ​

HTTP methods treated as queries (Array<string>, default ['GET']). An operation whose method is in this list generates a useSWR hook instead of a mutation.

query.importPath ​

Module that useSWR is imported from (string, default 'swr'). The plugin emits import useSWR from '${importPath}'. Relative and absolute paths are used as written, with relative paths resolved against the generated file.

queryKey ​

Builds the SWR key for each query hook. The callback receives the operation node and the active casing and returns the key array, and the built-in transformer is used when unset. String values are inlined into generated code verbatim, so wrap any literal string in JSON.stringify(...).

mutation ​

Configures the generated useSWRMutation hooks. Pass an object to change the HTTP methods or import path, or false to skip mutation hook generation. Defaults to { methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: 'swr/mutation' }.

mutation.methods ​

HTTP methods treated as mutations (Array<string>, default ['POST', 'PUT', 'PATCH', 'DELETE']). An operation whose method is in this list generates a useSWRMutation hook instead of a query.

mutation.importPath ​

Module that useSWRMutation is imported from (string, default 'swr/mutation'). The plugin emits import useSWRMutation from '${importPath}'. Relative and absolute paths are used as written, with relative paths resolved against the generated file.

mutationKey ​

Builds the SWR key for each mutation hook. Like queryKey, the callback receives the operation node and the active casing and returns the key array, and the built-in transformer is used when unset. String values are inlined verbatim, so wrap any literal string in JSON.stringify(...).

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 resolverSwr. See Override a resolver for the this context and how a patch layers over the default.

type ResolverSwrPatch = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  query?: {
    name?(node: OperationNode): string         // → 'useGetPetById'
    optionsName?(node: OperationNode): string  // → 'getPetByIdQueryOptions'
    keyName?(node: OperationNode): string       // → 'getPetByIdQueryKey'
    keyTypeName?(node: OperationNode): string   // → 'GetPetByIdQueryKey'
    clientName?(node: OperationNode): string    // → 'getPetById'
  }
  mutation?: {
    name?(node: OperationNode): string          // → 'useUpdatePet'
    keyName?(node: OperationNode): string        // → 'updatePetMutationKey'
    keyTypeName?(node: OperationNode): string    // → 'UpdatePetMutationKey'
    argTypeName?(node: OperationNode): string    // → 'UpdatePetMutationArg'
  }
}

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.