Repository navigation
vue-query: queryOptions()'s real return type is unexported; the public name with the same identifier points at a different, legacy type #11042
Description
Describe the bug
Since the 5.98.0 rewrite ("fix(vue-query): fix type of queryOptions to allow plain properties or getters"), queryOptions() is typed against a new QueryOptions-based shape. In the published rollup declaration file (build/modern/_tsup-dts-rollup.d.ts) this shape exists as UndefinedInitialQueryOptions_alias_1 / DefinedInitialQueryOptions_alias_1 — but:
_alias_1is not exported from the package root (build/modern/index.d.ts).- The public names
UndefinedInitialQueryOptions/DefinedInitialQueryOptionsare re-exported from the root, but they still point at the old,UseQueryOptions-based,MaybeRef<...>-union type. Two genuinely different types share one exported name; only the wrong one is reachable. - Supporting types referenced by the new signature are unexported too: vue-query's
ShallowOption, its localMaybeRefOrGetteralias, and query-core'sQueryBehavior,RetryValue,RetryDelayValue, plus a non-exportedunique symbol(dataTagErrorSymbol).
Any library that exports a function returning queryOptions(...) with an inferred return type — the exact pattern @kubb/plugin-vue-query generates for every endpoint — hits one of two consequences when its declarations are emitted:
- Hard declaration-emit errors (
TS2527/TS2883) — reproduced here with bothtsdown/rolldown-plugin-dtsand plaintsc. - Silently WRONG declarations — the natural fix for (1) is to annotate the return type with the public
UndefinedInitialQueryOptions. That compiles with zero errors, but it is the wrong type: a consumer spreading the factory's result into anotherqueryOptions()call to addselectfails to type-check, and theDataTagonqueryKeyis lost.
Both are reproduced below, from the same root cause: the name collision.
Your minimal, reproducible example
https://github.com/DesselBane/repro-vue-query-query-options
Steps to reproduce
See repo README.md
Expected behavior
No TS2527 error and/or correct type exported so that downstream select works
How often does this bug happen?
Every time
Screenshots or Videos
No response
Platform
Tanstack Query adapter
vue-query
TanStack Query version
5.98.0 (and 5.101.2)
TypeScript version
6.0.3
Additional context
Diagnosis and reproduction were created with the help of CLAUDE. I checked the repo and as far as I can tell this is all correct.
Activity
DesselBane commentedon Jul 10, 2026
Might be related to #10904
hiSandog commentedon Jul 11, 2026
The same-name legacy export is especially risky because declaration generation can succeed while
DataTaginformation is lost. A package-level declaration fixture could export an inferred factory result, consume it from another fixture package, spread it intoqueryOptions()withselect, and assert the selected result type across bothtscand the rollup declaration path.zaewc commentedon Jul 12, 2026
It looks like
queryOptions()returns types based on theUndefinedInitialQueryOptions/DefinedInitialQueryOptionsdeclarations inqueryOptions.ts, while the package root exports same-named types fromuseQuery.ts. That seems to make the actualqueryOptions()return types hard to name from the published package surfaceI'd like to work on this
My plan is to add a consumer-style declaration emit regression test, make the
queryOptions()return types nameable from the package root, and verify thatDataTagstill survives when the emitted result is consumed and spread back intoqueryOptions()withselect