Options

Options for pluginReactQuery.

Option	Type	Default	Description
output	Output	{ path: 'hooks', barrel: { type: 'named' } }	Where the generated hooks are written and exported
group	Group	—	Split output into per-tag or per-path folders
client	'axios' | 'fetch'	—	Which registered client plugin the hooks call
infinite	Partial<Infinite> | false	false	Generate useInfiniteQuery hooks for pagination
suspense	Partial<object> | false	false	Generate useSuspenseQuery hooks
query	Partial<Query> | false	{ methods: ['GET'], … }	Configure the query hooks
queryKey	(props) => unknown[]	built-in	Build the queryKey for each query hook
mutation	Partial<Mutation> | false	{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], … }	Configure the mutation hooks
mutationKey	(props) => unknown[]	built-in	Build the mutationKey for each mutation hook
customOptions	CustomOptions	—	Route every hook through your own options function
hooks	boolean	false	Emit use* hook functions on top of the factories
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<ResolverReactQuery>	—	Customize generated names and file paths
macros	Array<Macro>	—	Rewrite AST nodes before printing

output

Where the generated hooks are written and exported.

output.path

Folder for the plugin's files, resolved against the global output.path and defaulting to 'hooks'. With output.mode: 'file', use a filename like 'hooks.ts'.

output.mode

'file' (the default) writes a single file whose output.path includes the extension, and cannot be combined with group. 'directory' writes one file per operation.

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. Each generator plugin defaults output.barrel to { type: 'named' }; the root output.barrel on defineConfig defaults to false.

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

Turns a group key into a folder name, defaulting to the camelCased tag, or the first URL segment for path groups.

client

Which registered client plugin the hooks call, 'axios' or 'fetch'. When omitted, a single registered client plugin is auto-detected, so it is only needed to disambiguate several.

NOTE

The hooks call a client plugin's functions, so register @kubb/plugin-axios or @kubb/plugin-fetch alongside this one.

infinite

Adds infinite-query output for pagination. Pass an object to configure the cursor, or false (the default) to skip. Emitted only for operations with a query parameter matching infinite.queryParam.

With hooks at its default of false, setting infinite produces no file at all, not even the infiniteQueryOptions factory. Set hooks: true alongside infinite to generate the file and its useInfiniteQuery hook.

infinite.queryParam

Query parameter that carries the page cursor, defaulting to 'id'.

infinite.initialPageParam

Initial value for pageParam on the first fetch, defaulting to 0.

infinite.nextParam

Path to the next-page cursor, as dot notation ('pagination.next.id') or array form. Defaults to null.

infinite.previousParam

Path to the previous-page cursor, in the same forms. Defaults to null.

suspense

Adds a suspense variant alongside the regular query output. Pass an empty object ({}) to enable, or leave it as false (the default) to skip it. TanStack Query v5+ only.

With hooks at its default of false, enabling suspense produces no file at all, not even the suspenseQueryOptions factory. Set hooks: true alongside suspense to generate the file and its useSuspenseQuery hook.

query

Which operations become queries, emitting a queryOptions factory by default. Pass false to skip, or hooks to also emit useQuery.

query.methods

HTTP methods treated as queries, defaulting to ['GET'].

query.importPath

Module for the queryOptions import, defaulting to '@tanstack/react-query'.

queryKey

Builds the queryKey for each hook from the operation node and casing, defaulting to the built-in queryKeyTransformer. String values are inlined verbatim, so wrap literals in JSON.stringify(...).

mutation

Which operations become mutations, emitting a mutationOptions factory by default. Set false to skip, or hooks to also emit useMutation.

mutation.methods

HTTP methods treated as mutations, defaulting to ['POST', 'PUT', 'PATCH', 'DELETE'].

mutation.importPath

Module for the mutationOptions import, defaulting to '@tanstack/react-query'.

mutationKey

Builds the mutationKey for each mutation hook, for batched invalidations or useMutationState. Same props and string-inlining caveat as queryKey, defaulting to the built-in mutationKeyTransformer.

customOptions

Routes every hook through your own function that returns extra options such as onSuccess or select. Also emits a HookOptions type so your wrapper stays in sync.

customOptions.importPath

Module of your custom-options hook, imported as a named import. Required when customOptions is set.

customOptions.name

Exported name of your custom-options hook, defaulting to 'useCustomHookOptions'.

hooks

When false (the default), only the query and mutation factory helpers are written. Set true to also generate useQuery, useSuspenseQuery, useInfiniteQuery, useSuspenseInfiniteQuery, and useMutation.

suspense and infinite are gated on hooks too: with hooks: false, enabling either one writes nothing at all, not even the suspenseQueryOptions or infiniteQueryOptions factories.

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.

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

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

Partial override

type ResolverReactQueryPatch = {
  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'
  }
  suspenseQuery?: { /* same members as query */ }
  infiniteQuery?: { /* same members as query */ }
  suspenseInfiniteQuery?: { /* same members as query */ }
  mutation?: {
    name?(node: OperationNode): string          // → 'useUpdatePet'
    optionsName?(node: OperationNode): string
    keyName?(node: OperationNode): string
    typeName?(node: OperationNode): string      // → 'UpdatePet'
  }
  hook?: {
    optionsName?(): string
    customOptionsName?(): 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.