vue-query: `queryOptions()`'s real return type is unexported; the public name with the same identifier points at a different, legacy type
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 50.3k
- Forks
- 4.2k
- Avg merge
- 18h 25m
- Merged PRs (30d)
- 200
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
| Package | Version |
|---|---|
@tanstack/vue-query |
5.101.2 (also confirmed broken at 5.98.0; 5.97.0 is clean — see Regression window) |
@tanstack/query-core |
5.101.2 (transitive) |
typescript |
6.0.3 |
vue |
3.5.31 |
tsdown |
0.21.4 (rolldown-plugin-dts@0.22.5, rolldown@1.0.0-rc.9) |
| Node | v24.0.0 |
| OS | Windows 11 |
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the published declarations in build/modern/_tsup-dts-rollup.d.ts and the exports in build/modern/index.d.ts, then read the queryOptions implementation and the repro repository's README.md. Run the listed tsdown and tsc reproductions; done means declarations emit without TS2527/TS2883 and downstream select composition preserves the correct query options and DataTag types.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100