Options

Options for @kubb/plugin-vue-query, which generates TanStack Vue Query composables from an OpenAPI spec.

output

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

output.path

Folder the plugin writes to, resolved against the global output.path and defaulting to 'hooks'. For a single file, set output.mode: 'file' and give path an extension such as 'hooks.ts'.

output.mode

How generated code is consolidated, 'file' or 'directory'. 'file' writes a single file, so output.path needs an extension. 'directory' writes one file per operation and pairs with group for 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.

export { Pet, User } from './models'
export { getPetById, getInventory } from './clients'

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 turning a group key into a folder or identifier name, typed (context: { group: string }) => string. Defaults to ({ group }) => camelCase(group) for tag groups, while path groups use the URL segment as-is.

client

Selects which registered client plugin the composables call: 'axios' for @kubb/plugin-axios or 'fetch' for @kubb/plugin-fetch. When omitted, the plugin auto-detects the single registered client plugin, so you only need this to disambiguate several. A client plugin must be registered.

infinite

Adds infinite-query output for cursor- or page-based pagination. Pass an object to configure how the cursor is read, or false (the default) to skip. Output is emitted for an operation only when it declares a query parameter matching infinite.queryParam (default 'id') and hooks is also true. Without hooks: true, infinite produces no file at all, not even the factory:

export function getPetsQueryOptions(/* ... */) {
  return queryOptions({ queryKey, queryFn })
}

export function getPetsInfiniteQueryOptions(/* ... */) {
  return infiniteQueryOptions({ queryKey, queryFn, initialPageParam, getNextPageParam })
}

export function useGetPetsInfiniteQuery(/* ... */) {
  return useInfiniteQuery(getPetsInfiniteQueryOptions(/* ... */))
}

infinite.queryParam

Name of the query parameter that holds the page cursor. Defaults to 'id'.

infinite.initialPageParam

Initial value for pageParam on the first fetch. Type unknown, default 0.

infinite.nextParam

Path to the next-page cursor on the response, as dot notation ('pagination.next.id') or array form. Type string | string[] | null, default null.

infinite.previousParam

Path to the previous-page cursor, same dot or array form. Type string | string[] | null, default null.

infinite.cursorParam

Deprecated path to the cursor field. Use nextParam and previousParam instead. Type string | null, default null.

query

Decides which operations are treated as queries. The plugin generates a queryOptions factory for each match by default. Pass false to skip, or set hooks to also emit useQuery.

query.methods

HTTP methods treated as queries, default ['GET']. Matching operations generate a queryOptions factory instead of a mutation. Type Array<string>.

query.importPath

Module specifier for the generated import { queryOptions } from '...'. Type string, default '@tanstack/vue-query'.

queryKey

Builds the queryKey for each query composable. The callback receives the operation node, the active casing and the variant ('query' or 'infiniteQuery', the hook the key is built for) and returns the key array. String values are inlined verbatim, so wrap literals in JSON.stringify(...). Defaults to the built-in queryKeyTransformer, which adds infinite: true to infinite keys so they never share a cache entry with the plain query.

queryKey: ({ node, variant }) => [JSON.stringify({ variant, operationId: node.operationId })]

export const getUserByNameQueryKey = () => [{ variant: 'query', operationId: 'getUserByName' }] as const

mutation

Decides which operations are treated as mutations. The plugin generates a mutationKey helper for each match by default. Pass false to skip, or set hooks to also emit useMutation.

mutation.methods

HTTP methods treated as mutations, default ['POST', 'PUT', 'PATCH', 'DELETE']. Matching operations generate mutation output instead of a query. Type Array<string>.

mutation.importPath

Module specifier for the generated import { useMutation } from '...', emitted when hooks is set. Type string, default '@tanstack/vue-query'.

mutationKey

Builds the mutationKey for each mutation composable, useful for batching invalidations. It takes the same { node, casing } props as queryKey (with variant: 'mutation'), inlines strings the same way (wrap literals in JSON.stringify(...)), and defaults to the built-in mutationKeyTransformer.

hooks

Controls whether use* composables are emitted. The default false writes only the queryOptions, queryKey, and mutationKey factory helpers for plain queries and mutations. Set true to also generate useQuery, useInfiniteQuery, and useMutation.

infinite is gated on hooks too, writing nothing while hooks is false.

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

Overrides generated file and symbol names. Omitted members keep the plugin's resolver defaults. See Override a resolver for the this context and how a patch layers over the default.

type ResolverVueQueryPatch = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  query?: {
    name?(node: OperationNode): string
    optionsName?(node: OperationNode): string
    keyName?(node: OperationNode): string
    keyTypeName?(node: OperationNode): string
    clientName?(node: OperationNode): string
  }
  infiniteQuery?: { /* same members as query */ }
  mutation?: {
    name?(node: OperationNode): string
    keyName?(node: OperationNode): string
    typeName?(node: OperationNode): 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.