React Query Code Generation#

Overview#

The plugin-react-query package generates TanStack Query hooks and helpers from OpenAPI operations. For every matching HTTP operation it can emit up to four generator variants: standard query, suspense query, infinite query, and suspense-infinite query — each producing a QueryKey type + factory, a queryOptions helper, and optionally a use* hook.

Entry points:

• types.ts — Options, ResolvedOptions, and ResolverReactQuery types
• queryGenerator.tsx — Standard useQuery generator
• suspenseQueryGenerator.tsx — Suspense variant generator
• QueryOptions.tsx — queryOptions JSX component
• internals/tanstack-query/src/components/QueryKey.tsx 1 — QueryKey JSX component (re-exported via components/QueryKey.tsx)

Generator Variants#

The plugin ships five generators in packages/plugin-react-query/src/generators/:

Each generator's match() function gates which operations it handles. queryGenerator matches operations where isQuery && !isMutation 2; suspenseQueryGenerator additionally requires !!suspense && hooks in match() 3.

Per-File Output Structure#

For each matched operation, a generator resolves four names from the resolver namespace and writes a single file:

fooQueryKey() ← key factory (always emitted)
FooQueryKey ← key type (always emitted)
fooQueryOptions() ← queryOptions helper (always emitted)
useFooQuery() ← hook (only when hooks: true)

The resolver for each variant has its own namespace — resolver.query, resolver.suspenseQuery, resolver.infiniteQuery, resolver.suspenseInfiniteQuery, resolver.mutation — each providing .name(), .optionsName(), .keyName(), .keyTypeName(), .clientName() 4.

Example resolved names per GET /pet/{petId} 5:

• resolver.query.name(node) → useGetPetById
• resolver.query.optionsName(node) → getPetByIdQueryOptions
• resolver.query.keyName(node) → getPetByIdQueryKey
• resolver.query.keyTypeName(node) → GetPetByIdQueryKey

QueryKey Component#

QueryKey emits two exports per operation:

1. Arrow function (getPetByIdQueryKey) — returns an as const array.
2. Type alias (GetPetByIdQueryKey) — ReturnType<typeof getPetByIdQueryKey>.

The key array is built by queryKeyTransformer 6, which inspects the operation for path params, query params, and a request body, then produces elements like { url: '/pet/:petId', params: path }, ...(query ? [query] : []). A custom transformer can be wired in via the queryKey option 7, overriding the default shape entirely.

QueryOptions Component#

QueryOptions renders a named export function that:

1. Calls queryKeyName(…) to get the key.
2. Returns queryOptions<TData, TError, TData, typeof queryKey>({ queryKey, queryFn }).
3. The queryFn calls the contract client (await getPetById(…)) and returns data 8.

This helper is always emitted regardless of the hooks setting, making it usable in server components, loaders, or any non-React context.

hooks Option and File Emission Control#

The hooks: boolean option (default false) is the primary switch controlling what gets emitted 9:

• hooks: false — Only queryOptions, mutationOptions, queryKey, and mutationKey are emitted. The imports come exclusively from @tanstack/react-query factory functions that are also available in the Vue, Solid, and Svelte adapters, making the output framework-portable 10.
• hooks: true — Adds the use* hook body to each file. The queryGenerator checks query && hooks before rendering the <Query> component 11.

For the suspense and infinite variants, the hooks flag is checked at the outer match() guard level, meaning if hooks is false those generators skip the operation entirely and emit no file at all 12. This was changed in PR #697 to prevent near-empty queryOptions/queryKey-only files from being written for every GET operation when suspense/infinite was enabled without hooks.

suspense and infinite Options#

Both options default to false and must be explicitly enabled 13:

• suspense: {} — Activates suspenseQueryGenerator and suspenseInfiniteQueryGenerator. Requires TanStack Query v5+. The suspense generator unconditionally imports useSuspenseQuery (no conditional hooks guard in the file body) because match() already excludes it when hooks is false 14.
• infinite: Partial<Infinite> — Activates infiniteQueryGenerator. Configure cursor/page parameters via the Infinite type.

Key Configuration Options#

All in Options (types.ts):