feat: add skipToken support and queryOptions override to TanStack Query useQuery hooks

[nmokkenstorm]

Summary

Adds skipToken support and queryOptions override to generated useQuery hooks for TanStack Query plugins (React, Preact).

• useQuery hooks are now generated by default (no config flag needed)
• skipToken is always supported — pass it instead of options to conditionally disable a query
• queryOptions override parameter allows customizing the underlying query options
• Use useQuery: false to opt out of generating useQuery hooks

Closes #2766

Breaking changes

• useQuery hooks are now generated by default for React Query and Preact Query plugins (previously disabled). Existing users will see new useQuery hook exports, skipToken + useQuery imports, and an unwrapSkipToken utility in their generated output. To opt out, set useQuery: false in your plugin config.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@nmokkenstorm is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2071133

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 40.39%. Comparing base (b8519b0) to head (2071133).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3528      +/-   ##
==========================================
+ Coverage   40.24%   40.39%   +0.14%     
==========================================
  Files         520      521       +1     
  Lines       19302    19337      +35     
  Branches     5726     5727       +1     
==========================================
+ Hits         7769     7811      +42     
+ Misses       9337     9332       -5     
+ Partials     2196     2194       -2     

Flag	Coverage Δ
unittests	40.39% <ø> (+0.14%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3528

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3528

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3528

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3528

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3528

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3528

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3528

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3528

commit: 2071133

[mrlubos]

@nmokkenstorm Why is it an optional configuration flag? Why not add it for everyone?

[mrlubos]

@nandorojo will like this

[mrlubos]

@nmokkenstorm I updated your description with linked issue

[nmokkenstorm]

@nmokkenstorm Why is it an optional configuration flag? Why not add it for everyone?

habit to make it opt-in tbh. I think the skipToken is a breaking change too on type level and it also slightly increases the generated bundle size but I will check.

[mrlubos]

@nmokkenstorm I didn't look at the code yet, stopped after seeing the configuration haha. If it's going to be breaking either way, I'd much rather deprecate the old approach because we wouldn't want new users to start with the flag disabled, realize one day they need to enable it, and face a lot of breaking changes. We can talk through it when you feel the pull request is more ready. I'm pretty sure there was another thread where we talked about skip tokens but can't find it, I'd like to ideally avoid another breaking change when that thread gets addressed

[nmokkenstorm]

@nmokkenstorm I didn't look at the code yet, stopped after seeing the configuration haha. If it's going to be breaking either way, I'd much rather deprecate the old approach because we wouldn't want new users to start with the flag disabled, realize one day they need to enable it, and face a lot of breaking changes. We can talk through it when you feel the pull request is more ready. I'm pretty sure there was another thread where we talked about skip tokens but can't find it, I'd like to ideally avoid another breaking change when that thread gets addressed

I'll double check, I think it's definately doable to have it be backwards compatible without a breaking change. The useQuery/Mutation stuff was opt in so I stuck to the pattern but I think this can be done without losing ergonomics.

I'll update the pr description and ping you if it's reviewable, I needed a remote public ref to do some internal testing with first anyways.

Thanks for the feedback!

[mrlubos]

@nmokkenstorm Can you clarify what do you mean by "add useQuery hooks" in the title? React/Preact Query already support generating useQuery hooks so I'm confused what it's referencing

[nmokkenstorm]

@nmokkenstorm Can you clarify what do you mean by "add useQuery hooks" in the title? React/Preact Query already support generating useQuery hooks so I'm confused what it's referencing

its about having the generated useQuery hooks exist per entity, with queryoptions and skiptoken enabled. the reason it's named like that is because the original code/branch orginates from a fork that pre-dates the support we had in our project.

still tinkering on this, nothing to see/review here yet!

[mrlubos]

Just making sure we're aligned on the scope! I shall retreat once more

[nmokkenstorm]

@mrlubos I think it does what it needs to do now, below a redacted diff of how we're currently using it in the fork.

I ran into an issue where the auto paginated version of useQuery has ts-ignore inserted and I needed it somewhere else to stay compliant, so I added support for a new case to the DSL for that. Probably worthwhile to check a) if that's correct and b) if maybe we can improve the related code to no longer need the ts-ignore, but that seemed a bit out of scope for this PR.

lmk what you think? I'll see if I can get the merge checks to behave a bit more but I'm not sure what I actually can and can not influence there, you mentioned they are a bit flaky before.

---

Before (query)

import { getSomeResourceOptions } from '@org/api';
import { useQuery } from '@tanstack/react-query';

const { data, isLoading } = useQuery({
  ...getSomeResourceOptions({ path: { id: id ?? '' } }),
  enabled: !!id,
});

After (query)

import { useGetSomeResource } from '@org/api';
import { skipToken } from '@tanstack/react-query';

const { data, isLoading } = useGetSomeResource(
  id ? { path: { id } } : skipToken
);

Before (query with extra options)

import { getStatusOptions } from '@org/api';
import { useQuery } from '@tanstack/react-query';

const { data, isLoading } = useQuery({
  ...getStatusOptions(),
  enabled: shouldPoll,
  refetchInterval: shouldPoll ? 5000 : false,
});

After (query with extra options)

import { useGetStatus } from '@org/api';

const { data, isLoading } = useGetStatus({
  queryOptions: {
    enabled: shouldPoll,
    refetchInterval: shouldPoll ? 5000 : false,
  },
});

Before (mutation)

import { updateResourceMutation, getResourceQueryKey } from '@org/api';
import { useMutation, useQueryClient } from '@tanstack/react-query';

const queryClient = useQueryClient();
const { mutate, isPending } = useMutation({
  ...updateResourceMutation(),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: getResourceQueryKey() });
  },
});

After (mutation)

import { useUpdateResource, getResourceQueryKey } from '@org/api';
import { useQueryClient } from '@tanstack/react-query';

const queryClient = useQueryClient();
const { mutate, isPending } = useUpdateResource({
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: getResourceQueryKey() });
  },
});

[pullfrog]

Reviewed PR #3528. The skipToken support and queryOptions override implementation is well-structured and type-safe. Flagged the useQuery default change from false to true as a breaking change that needs explicit acknowledgment, and noted a dead symbol registration (UseQueryOptions/CreateQueryOptions) in plugin.ts.

Task list (5/5 completed)

• Read diff to understand the scope of changes
• Review core implementation files (plugin, useQuery, queryOptions, config, types)
• Review test changes
• Check snapshot changes for correctness
• Self-critique and submit review

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ 𝕏}

[pullfrog]

TL;DR — Adds skipToken support to all TanStack Query queryOptions and infiniteQueryOptions functions, enables useQuery hook generation by default for React and Preact, and lets useQuery hooks accept a queryOptions override to customize query behavior without losing type safety.

Key changes

• Add skipToken support to queryOptions and infiniteQueryOptions — Generated option functions now accept skipToken as an alternative to SDK options, conditionally passing it through to queryFn and unwrapping it for queryKey via a new unwrapSkipToken utility.
• Enable useQuery hooks by default for React and Preact — The useQuery config default flips from false to true for @tanstack/react-query and @tanstack/preact-query.
• Add queryOptions override parameter to useQuery hooks — Generated useQuery hooks now accept an optional queryOptions property (typed as Partial<Omit<ReturnType<typeof ...Options>, 'queryKey' | 'queryFn'>>) that is spread over the computed query options, allowing overrides like staleTime or gcTime.
• Add unwrapSkipToken shared utility — New shared/unwrapSkipToken.ts generates a runtime helper that safely narrows options | skipToken to T | undefined.
• Register skipToken and query options types in plugin bootstrap — plugin.ts registers skipToken, UseQueryOptions/CreateQueryOptions, and extracts mutation/query option type names via helper functions.
• Add HintMixin to CallTsDsl — The TS DSL CallTsDsl class now supports @ts-ignore hints on call expressions, used to suppress type errors in the generated infiniteQueryOptions calls.
• Add useQuery-disabled test scenario — New test case exercises the useQuery: false config to verify useQuery hooks can be opted out of.

_{Summary ｜ 147 files ｜ 1 commit ｜ base: main ← feat/use-query-options}

skipToken support in query options

Before: queryOptions and infiniteQueryOptions functions only accepted SDK option types; there was no way to disable a query without removing the hook call.
After: Both functions accept Options<T> | typeof skipToken. When skipToken is passed, queryFn receives skipToken directly (disabling the query), and queryKey receives the unwrapped value via unwrapSkipToken.

This follows TanStack Query's idiomatic pattern for conditionally disabling queries. The generated code checks options === skipToken at runtime and branches accordingly:

queryFn: options === skipToken ? skipToken : async ({ queryKey, signal }) => { ... }

A shared unwrapSkipToken helper is emitted once per plugin output and reused across all query option functions.

shared/unwrapSkipToken.ts · v5/queryOptions.ts · v5/infiniteQueryOptions.ts

useQuery hooks enabled by default with queryOptions override

Before: useQuery hook generation was disabled by default (enabled: false). The generated hooks accepted only SDK options and delegated directly to the queryOptions function with no override surface.
After: useQuery is enabled by default for React and Preact. Hooks accept (Options<T> | typeof skipToken) & { queryOptions?: Partial<Omit<..., 'queryKey' | 'queryFn'>> }, destructure the queryOptions property, and spread it over the computed options.

The generated hook body handles skipToken as an early return, then destructures queryOptions from the remaining options and merges them:

if (options === skipToken) return useQuery(getFooOptions(options));
const { queryOptions, ...sdkOptions } = options ?? {};
return useQuery({ ...getFooOptions(sdkOptions), ...queryOptions });

Why are queryKey and queryFn excluded from the override type?

These two properties are computed from the SDK options and operation metadata. Allowing overrides would break the query key stability contract and the type-safe fetch function, so they are omitted from the partial override type.

v5/useQuery.ts · react-query/config.ts · preact-query/config.ts

Plugin bootstrap and TS DSL changes

Before: The v5 plugin handler registered mutation option types inline and did not register skipToken or query observer option types. CallTsDsl did not support @ts-ignore hints.
After: plugin.ts registers skipToken, UseQueryOptions/CreateQueryOptions, and uses helper functions (getMutationOptionsType, getQueryOptionsType) keyed by plugin name. CallTsDsl gains HintMixin support so @ts-ignore can be applied to call expressions.

v5/plugin.ts · ts-dsl/expr/call.ts

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ 𝕏}

[pullfrog]

TL;DR — Adds skipToken support and queryOptions override to the generated TanStack Query useQuery hooks, and enables useQuery generation by default for React and Preact. This lets consumers conditionally disable queries (e.g. dependent queries) and override individual query options without losing type safety.

Key changes

• Enable useQuery generation by default — React Query and Preact Query plugins now default useQuery to enabled: true instead of false, so hooks are generated out of the box.
• Add skipToken support to queryOptions and infiniteQueryOptions — Generated options functions accept skipToken as an alternative to the options object; the queryFn becomes a ternary that passes skipToken through when the caller disables the query.
• Add shared unwrapSkipToken utility — A new helper safely narrows options | skipToken back to the concrete type (or undefined) so the SDK call and query key builder receive the correct shape.
• Generate useQuery hooks with queryOptions override — Each generated useQuery hook now accepts a queryOptions property (typed as Partial<Omit<..., 'queryKey' | 'queryFn'>>) that is spread over the computed query options, giving consumers a first-class way to override staleTime, gcTime, enabled, etc.
• Register skipToken and refactor createQueryStyleNames — The v5 plugin handler registers the skipToken external symbol and extracts the "create-query-style" name mapping into a shared Set for cleaner mutation options type resolution.
• Add HintMixin to CallTsDsl — The TS DSL's call expression can now emit @ts-ignore hints, used to suppress the unavoidable type widening in infiniteQueryOptions generics.
• Add useQuery: false test scenario — A new snapshot test verifies that useQuery can still be explicitly disabled while the remaining query/mutation codegen stays correct.

_{Summary ｜ 153 files ｜ 2 commits ｜ base: main ← feat/use-query-options}

skipToken support in generated query options

Before: Generated queryOptions/infiniteQueryOptions functions only accepted the SDK options type; disabling a query required manually passing enabled: false.
After: These functions accept Options<T> | typeof skipToken; when skipToken is passed, the queryFn short-circuits to skipToken and the query key is built from unwrapSkipToken(options).

This follows TanStack Query's recommended pattern for dependent queries. An unwrapSkipToken helper is emitted once per plugin output to safely narrow the union before spreading into the SDK call.

How does unwrapSkipToken work?

It is a generic function that checks options !== skipToken. If true, it returns the value as T; otherwise it returns undefined. This avoids spreading skipToken (a symbol) into the SDK call object. Both queryOptions and infiniteQueryOptions lazily create this function via plugin.querySymbol to ensure it is emitted exactly once.

unwrapSkipToken.ts · queryOptions.ts · infiniteQueryOptions.ts

Inline useQuery hooks with queryOptions override

Before: Generated useQuery hooks simply forwarded all options to the corresponding queryOptions function — no way to override individual TanStack Query options like staleTime or gcTime.
After: Each useQuery hook accepts an intersection type with an optional queryOptions property (typed as Partial<Omit<ReturnType<typeof fooOptions>, 'queryKey' | 'queryFn'>>). The hook destructures queryOptions from the rest, calls the options factory with the SDK params, then spreads the overrides on top.

The hook also handles skipToken directly: when passed, it short-circuits to useQuery(fooOptions(skipToken)) without destructuring. When the caller provides normal options, the hook destructures { queryOptions, ...sdkOptions } and returns useQuery({ ...fooOptions(sdkOptions), ...queryOptions }).

useQuery.ts · plugin.ts

useQuery enabled by default for React and Preact

Before: useQuery defaulted to false — hooks were not generated unless explicitly opted in.
After: useQuery defaults to true for both @tanstack/react-query and @tanstack/preact-query. Setting useQuery: false still works and is covered by a new snapshot test.

react-query/config.ts · preact-query/config.ts · plugins.test.ts

HintMixin on CallTsDsl for @ts-ignore on call expressions

Before: @ts-ignore hints could only be applied to object literals, not call expressions — the hint had to live inside the infiniteQueryOptions(...) object argument.
After: CallTsDsl mixes in HintMixin, allowing @ts-ignore to be emitted directly on the call expression. This moves the hint to the correct position for the generic type mismatch in infiniteQueryOptions.

call.ts · call.test.ts · ternary.test.ts

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ 𝕏}

[pullfrog]

Important

Changing useQuery default from false to true is a breaking change that should be called out more explicitly.

The implementation is solid — skipToken support is cleanly wired through a shared unwrapSkipToken utility, the useQuery hooks handle both skipToken early-return and queryOptions override merging correctly, and the intersection type (Options<T> | typeof skipToken) & { queryOptions?: ... } is valid since queryOptions is optional. The @ts-ignore placement refactor on infiniteQueryOptions (moving from object literal to call expression via HintMixin) is a nice structural improvement.

Three things to address before merge:

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ 𝕏}

[pullfrog]

Changing this default from false to true means existing users who run codegen will suddenly get new useQuery hook exports, new skipToken + useQuery imports, and a new unwrapSkipToken utility in their generated output — without changing their config. The PR description says "None" under breaking changes, but this is a behavioral change that affects all @tanstack/react-query users who haven't explicitly set useQuery.

Consider keeping the default as false and letting users opt in, or at minimum flagging this as a breaking change that requires a changeset with a major/minor bump and migration note.

[nmokkenstorm]

@mrlubos I think this matches exactly our conversation re: not opting in, but maybe you see that differently

[pullfrog]

Makes sense — if that's the agreed-upon direction with @mrlubos, I'd just suggest updating the PR description's "Breaking changes" section to mention that useQuery hooks are now generated by default (previously off), so downstream users are aware when upgrading.

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ 𝕏}

[pullfrog]

Same concern as react-query — changing this default from false to true is a breaking change for preact-query users.

[pullfrog]

This UseQueryOptions/CreateQueryOptions symbol is registered but never referenced by any generated AST node. The useQuery.ts hook builds its override type inline via Partial<Omit<ReturnType<typeof queryOptionsFn>, 'queryKey' | 'queryFn'>> rather than using this external type. The symbol system will tree-shake it from the output (confirmed by snapshots), but the registration is dead code.

Either remove it or use it — e.g., the queryOptionsType in useQuery.ts could reference this external type instead of building Partial<Omit<...>> inline.

[pullfrog]

Replied to the PR author's comment acknowledging that the useQuery default change was intentional per maintainer discussion, and suggested updating the PR description's "Breaking changes" section accordingly. No code changes needed.

Task list (2/2 completed)

• Read review thread and understand context
• Respond to reviewer's reply about the default value change

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ 𝕏}

[mrlubos]

@nmokkenstorm thanks! CI should be fixed now so if it's failing, it's likely a code issue (like in this instance with needing to re-generate examples)

[nmokkenstorm]

@nmokkenstorm thanks! CI should be fixed now so if it's failing, it's likely a code issue (like in this instance with needing to re-generate examples)

I that case I will actually give it a proper look hah, will keep you posted