React Query
Officialv5.11.0@kubb/plugin-react-query
Options
Pass these options to pluginReactQuery(). Shared options link to Shared plugin options.
Options overview
| Option | Purpose | Default |
|---|---|---|
client | Client plugin the hooks call. | Auto-detected |
returnType | What the hooks resolve to. | 'data' |
hooks | Emit use* hooks on top of the factories. | false |
query | Which methods become queries, and the TanStack import. | { methods: ['GET', 'QUERY'], importPath: '@tanstack/react-query' } |
query.methods | Methods that become queries. | ['GET', 'QUERY'] |
query.importPath | Import path of the query helpers. | '@tanstack/react-query' |
queryKey | Build the queryKey of each query. | queryKeyTransformer |
mutation | Which methods become mutations, and the TanStack import. | { methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: '@tanstack/react-query' } |
mutation.methods | Methods that become mutations. | ['POST', 'PUT', 'PATCH', 'DELETE'] |
mutation.importPath | Import path of the mutation helpers. | '@tanstack/react-query' |
mutationKey | Build the mutationKey of each mutation. | mutationKeyTransformer |
infinite | Generate infinite queries for pagination. | false |
infinite.queryParam | Query parameter for the page cursor. | 'id' |
infinite.initialPageParam | First pageParam. | 0 |
infinite.nextParam | Path to the next cursor. | null |
infinite.previousParam | Path to the previous cursor. | null |
infinite.getNextPageParam | Compute the next page param. | null |
infinite.getPreviousPageParam | Compute the previous page param. | null |
infinite.cursorParam | Deprecated cursor field. | null |
suspense | Generate useSuspenseQuery hooks. | false |
customOptions | Route every hook through your own options function. | None |
customOptions.importPath | Module of your function. | None, required |
customOptions.name | Name of your function. | 'useCustomHookOptions' |
output | Where files are written. | { path: 'hooks', barrel: { type: 'named' } } |
group | Split output by tag or path. | None |
include | Keep only operations that match. | None |
exclude | Skip operations that match. | [] |
override | Apply different options per pattern. | [] |
resolver | Customize generated names and file paths. | resolverReactQuery |
macros | Rewrite AST nodes before printing. | [] |
Option details
client
The client plugin the hooks call. Kubb detects a lone client plugin, so set client only when several are registered. Generation fails when none is.
| Type | 'fetch' | 'axios' | 'ky' | 'client' |
| Required | false |
@kubb/plugin-fetch.@kubb/plugin-axios.@kubb/plugin-ky.@kubb/plugin-client. Your client module must also export RequestConfig and ResponseErrorConfig.returnType
What the hooks resolve to.
| Type | 'data' | 'full' |
| Required | false |
| Default | 'data' |
RequestResult, so a hook can read the status and headers. Needs a client plugin with returnType'full' or 'plain', or generation fails.pluginReactQuery({ returnType: 'full' })
// with integerType: 'number' on the adapter
const { data: result } = useGetPetById({ path: { petId: 1 } })
const etag = result?.response.headers.get('ETag')hooks
Set true to generate useQuery and useMutation hooks on top of the queryOptions, mutationOptions, and key helpers. Call operations lists every export.
| Type | boolean |
| Required | false |
| Default | false |
query
Which operations become queries and where TanStack Query is imported from. false skips query output.
| Type | Partial<Query> | false |
| Required | false |
| Default | { methods: ['GET', 'QUERY'], importPath: '@tanstack/react-query' } |
query.methods
HTTP methods treated as queries. A method in neither list gets no helper, so keep 'QUERY' when you replace it.
| Type | Array<string> |
| Required | false |
| Default | ['GET', 'QUERY'] |
query.importPath
Module for queryOptions, useQuery, and their variants, such as a wrapper that sets a default QueryClient.
| Type | string |
| Required | false |
| Default | '@tanstack/react-query' |
queryKey
Builds each query's queryKey from the operation node and the variant: 'query', 'suspenseQuery', 'infiniteQuery', or 'suspenseInfiniteQuery'. The default key is [{ url, params }, query, body].
| Type | (props: { node, casing, variant }) => Array<unknown> |
| Required | false |
| Default | queryKeyTransformer |
JSON.stringify(...).To extend the default, spread it. See TanStack Query keys.
import { queryKeyTransformer } from '@kubb/plugin-react-query'
queryKey: (props) => [JSON.stringify('v2'), ...queryKeyTransformer(props)]mutation
Which operations become mutations and where TanStack Query is imported from. false skips mutation output.
| Type | Partial<Mutation> | false |
| Required | false |
| Default | { methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: '@tanstack/react-query' } |
mutation.methods
HTTP methods treated as mutations. A method also in query.methods stays a query.
| Type | Array<string> |
| Required | false |
| Default | ['POST', 'PUT', 'PATCH', 'DELETE'] |
mutation.importPath
Module for mutationOptions and useMutation.
| Type | string |
| Required | false |
| Default | '@tanstack/react-query' |
mutationKey
Builds each mutation's mutationKey, for batched invalidations or useMutationState. It works like queryKey with variant: 'mutation'. The default key is [{ url }].
| Type | (props: { node, casing, variant }) => Array<unknown> |
| Required | false |
| Default | mutationKeyTransformer |
import { mutationKeyTransformer } from '@kubb/plugin-react-query'
mutationKey: (props) => [JSON.stringify('v2'), ...mutationKeyTransformer(props)]infinite
Adds infiniteQueryOptions and useInfiniteQuery to each query operation that takes the infinite.queryParam parameter. Needs hooks: true.
| Type | Partial<Infinite> | false |
| Required | false |
| Default | false |
nextParam or getNextPageParam. Otherwise hasNextPage never turns false for a non-array response. See Infinite queries.infinite.queryParam
Query parameter that carries the page cursor.
| Type | string |
| Required | false |
| Default | 'id' |
infinite.initialPageParam
pageParam of the first fetch. Give it the type of the query parameter.
| Type | unknown |
| Required | false |
| Default | 0 |
infinite.nextParam
Path to the next cursor on the response, in dot notation ('pagination.next.id') or array form (['pagination', 'next', 'id']).
| Type | string | Array<string> | null |
| Required | false |
| Default | null |
infinite.previousParam
Path to the previous cursor, in the same forms as nextParam.
| Type | string | Array<string> | null |
| Required | false |
| Default | null |
infinite.getNextPageParam
Source of TanStack Query's getNextPageParam, for a next page you must compute. Pass a string, a function, or definePageParam, which types the page and the page parameter.
| Type | string | PageParamFn | null |
| Required | false |
| Default | null |
import { definePageParam, pluginReactQuery } from '@kubb/plugin-react-query'
type PetsPage = { hasNext: boolean; number: number }
pluginReactQuery({
hooks: true,
infinite: {
queryParam: 'page',
getNextPageParam: definePageParam<PetsPage, number>((lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined)),
},
})infinite.getPreviousPageParam
Source of TanStack Query's getPreviousPageParam, in the same forms as getNextPageParam.
| Type | string | PageParamFn | null |
| Required | false |
| Default | null |
infinite.cursorParam
Deprecated. Use nextParam and previousParam. A top-level response field, not a dot path, that holds the cursor for both directions.
| Type | string | null |
| Required | false |
| Default | null |
suspense
Pass {} to add useSuspenseQuery hooks, plus useSuspenseInfiniteQuery when infinite is set. Needs hooks: true.
| Type | object | false |
| Required | false |
| Default | false |
customOptions
Calls one function of yours from every hook to share options such as staleTime. Kubb also writes a HookOptions type, keyed by hook name. Needs hooks: true.
| Type | { importPath: string; name?: string } |
| Required | false |
Each hook calls it with { hookName, operationId }, and per-call options win over its result:
import type { HookOptions } from './HookOptions'
export function useCustomHookOptions({ hookName }: { hookName: keyof HookOptions; operationId: string }) {
if (hookName === 'useGetPetById') {
return { staleTime: 60_000 } satisfies HookOptions['useGetPetById']
}
return {}
}customOptions.importPath
Module of the function, resolved from the generated hooks folder. If the path is inside the plugin's output folder and the file is missing, Kubb writes a starter file.
| Type | string |
| Required | true when customOptions is set |
customOptions.name
Exported name of the function.
| Type | string |
| Required | false |
| Default | 'useCustomHookOptions' |
resolver
Overrides generated names. Members you leave out keep resolverReactQuery. See resolver for the shared members.
| Type | ResolverPatch<ResolverReactQuery> |
| Required | false |
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'
}
// same members, with a Suspense, Infinite, or SuspenseInfinite suffix
suspenseQuery?: ResolverReactQueryPatch['query']
infiniteQuery?: ResolverReactQueryPatch['query']
suspenseInfiniteQuery?: ResolverReactQueryPatch['query']
mutation?: {
name?(node: OperationNode): string // 'useUpdatePet'
optionsName?(node: OperationNode): string // 'updatePetMutationOptions'
keyName?(node: OperationNode): string // 'updatePetMutationKey'
}
hook?: {
optionsName?(): string // 'HookOptions'
customOptionsName?(): string // 'getCustomHookOptions'
}
}