Options

Pass these options to pluginReactQuery(). Shared options link to Shared plugin options for details.

Options overview

Option details

client

Selects which registered client plugin the hooks call. A single registered client is auto-detected. Set client when several are registered.

infinite

Adds infiniteQueryOptions and useInfiniteQuery for operations that declare the query parameter named in infinite.queryParam. Needs hooks: true.

infinite.queryParam

Query parameter that carries the page cursor.

infinite.initialPageParam

Initial value for pageParam on the first fetch.

infinite.nextParam

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

infinite.previousParam

Path to the previous-page cursor on the response, in the same dot or array form.

infinite.cursorParam

Deprecated path to the cursor field, read for both getNextPageParam and getPreviousPageParam when set. Use nextParam and previousParam instead.

infinite.getNextPageParam

Source code for TanStack Query's getNextPageParam, copied into the generated code as written. Use it when the next page must be computed instead of read from a field. Takes precedence over nextParam and cursorParam.

infinite: {
  queryParam: 'page',
  getNextPageParam: '(lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined)',
  getPreviousPageParam: '(firstPage) => (firstPage.number > 0 ? firstPage.number - 1 : undefined)',
}

Without getNextPageParam, nextParam or cursorParam, the hook counts pages up from initialPageParam until a page is an empty array. This works only for array responses, so generation warns when the response is an object.

infinite.getPreviousPageParam

Source code for TanStack Query's getPreviousPageParam, copied into the generated code as written. Takes precedence over previousParam and cursorParam.

suspense

Adds useSuspenseQuery hooks next to the regular query hooks. Pass {} to turn it on. Needs TanStack Query v5 or higher and hooks: true.

query

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

query.methods

HTTP methods treated as queries.

Operations whose method is in neither query.methods nor mutation.methods get no hook. Keep 'QUERY' here when overriding the list, or QUERY operations are skipped.

query.importPath

Module for the queryOptions and useQuery imports.

queryKey

Builds the queryKey for each hook from the operation node, casing and variant. Strings are copied into the generated code as written, so wrap a string literal in JSON.stringify(...).

variant is 'query', 'suspenseQuery', 'infiniteQuery' or 'suspenseInfiniteQuery'. The default key adds infinite: true to infinite variants so they never share a cache entry with the plain query.

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

To extend the default key instead of replacing it, import queryKeyTransformer and spread its result. The default segments can change between releases, so spread them instead of reading single entries.

import { queryKeyTransformer } from '@kubb/plugin-react-query'

queryKey: (props) => [JSON.stringify(props.node.operationId), ...queryKeyTransformer(props)]

mutation

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

mutation.methods

HTTP methods treated as mutations.

mutation.importPath

Module for the mutationOptions and useMutation imports.

mutationKey

Builds the mutationKey for each mutation hook, for batched invalidations or useMutationState. Same props and string-inlining caveat as queryKey, with variant set to 'mutation'.

Extend the default the same way with mutationKeyTransformer:

import { mutationKeyTransformer } from '@kubb/plugin-react-query'

mutationKey: (props) => [JSON.stringify(props.node.operationId), ...mutationKeyTransformer(props)]

customOptions

Routes every hook through your own function that returns extra options such as onSuccess or select. Also emits a HookOptions type that maps each hook name to its options type. Needs hooks: true.

customOptions.importPath

Module of your custom-options hook, imported as a named import. It resolves from the generated hooks folder. When the module does not exist yet, Kubb writes a starter file there, but only when importPath stays inside the plugin's output folder. For a path outside it, create the module yourself.

customOptions.name

Exported name of your custom-options hook.

hooks

When false (the default), only the queryOptions, mutationOptions, queryKey and mutationKey helpers are written, using factory imports that work across TanStack Query adapters. Set true to also generate useQuery, useSuspenseQuery, useInfiniteQuery, useSuspenseInfiniteQuery, and useMutation.

resolver

Overrides generated file and symbol names. Omitted members keep resolverReactQuery. The shared members (name, file, imports) and the this context are described under resolver.

type ResolverReactQueryPatch = {
  // plus the shared name, file, and imports members
  query?: {
    name?(node: OperationNode): string         // → 'useGetPetById'
    optionsName?(node: OperationNode): string  // → 'getPetByIdQueryOptions'
    keyName?(node: OperationNode): string       // → 'getPetByIdQueryKey'
    keyTypeName?(node: OperationNode): string   // → 'GetPetByIdQueryKey'
  }
  // suspenseQuery, infiniteQuery, suspenseInfiniteQuery: same members as query
  mutation?: {
    name?(node: OperationNode): string          // → 'useUpdatePet'
    optionsName?(node: OperationNode): string
    keyName?(node: OperationNode): string
  }
  hook?: {
    optionsName?(): string
    customOptionsName?(): string
  }
}