@tanstack/vue-query: Generated functions lack Vue 3 reactivity support

[adamkasper]

Description

The @tanstack/vue-query plugin generates query option functions that don't support Vue 3's reactivity system. Generated functions accept static Options parameters instead of reactive values (MaybeRefOrGetter), which prevents queries from automatically refetching when reactive dependencies change.

Current problematic behavior:

const userId = ref('user123')
const searchQuery = ref('john')

const { data } = useQuery({
  ...getUsersOptions({
    path: { id: userId.value }, // ❌ .value loses reactivity
    query: { search: searchQuery.value }, // ❌ .value loses reactivity
  }),
})

// These changes don't trigger refetch:
userId.value = 'user456' // No refetch
searchQuery.value = 'jane' // No refetch

Expected behavior:

const userId = ref('user123')
const searchQuery = ref('john')

const { data } = useQuery({
  ...getUsersOptions({
    path: { id: userId }, // ✅ Pass ref directly
    query: { search: searchQuery }, // ✅ Pass ref directly
  }),
})

// These should trigger automatic refetch:
userId.value = 'user456' // ✅ Refetch
searchQuery.value = 'jane' // ✅ Refetch

Root cause:

The plugin currently generates:

export function getUsersOptions(options: Options<GetUsersData>) {
  return queryOptions({
    queryFn: async ({ queryKey, signal }) => { /* ... */ },
    queryKey: getUsersQueryKey(options), // Static queryKey!
  })
}

It should generate:

export function getUsersOptions(options: MaybeRefOrGetter<Options<GetUsersData>>) {
  return queryOptions({
    queryFn: async ({ queryKey, signal }) => {
      const resolvedOptions = toValue(options) // Unwrap reactive values
      // ...
    },
    queryKey: computed(() => getUsersQueryKey(options)), // Reactive queryKey!
  })
}

Proposed solution:

Create Vue-specific implementations in @tanstack/vue-query plugin:

1. Import Vue utilities: MaybeRefOrGetter, toValue, computed from 'vue'
2. Wrap function parameters with MaybeRefOrGetter<Options<T>>
3. Use computed(() => queryKey(...)) for reactive query keys
4. Use toValue(options) inside queryFn to resolve reactive values

This approach aligns with TanStack Vue Query's design principles and is similar to how @pinia/colada handles reactive parameters.

Reproducible example or configuration

https://stackblitz.com/edit/nuxt-starter-ctyy1wrx?file=app%2Fpages%2Findex.vue

OpenAPI specification (optional)

No response

System information (optional)

No response

[dosubot]

Hi @adamkasper! I'm Dosu and I’m helping the openapi-ts team.

The current implementation of the @tanstack/vue-query plugin generates query option functions that accept static parameters and produce static query keys. There is no mention in the official documentation of support for Vue 3 reactivity features like passing refs directly, using MaybeRefOrGetter, or computed for query keys, nor any documented workaround or planned support for this feature. Users needing reactive query options may need to implement custom wrappers or monitor for future updates. You can review the plugin's documentation for more details here.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• nuxt-starter-ctyy1wrx (Open reproduction)

[mrlubos]

@brolnickij my Vue expert, do you agree with this assessment?

[brolnickij]

@adamkasper to get reactivity working, you need to wrap the generated *Options / *InfiniteOptions in computed

const { dataUpdatedAt } = useInfiniteQuery(
  computed(() => listUsersInfiniteOptions({
    query: {
      search: search.value
    }
  }))
)

---

@mrlubos right now the generated *Query / *InfiniteOptions are wrapped in queryOptions / infiniteQueryOptions, which is correct and matches the official TanStack docs

we did the same for @pinia/colada recently when we integrated defineQueryOptions

if developers keep asking similar questions about reactivity, we should add this to the Hey API docs

[mrlubos]

@brolnickij Thanks as always! What's your take on the ask vs your suggestion? It seems you're both using the same concept, only in different places.

Why would someone expect one approach over the other? Is there a difference in performance? Is it a matter of experience? Or purely a personal preference?

[brolnickij]

@mrlubos

What's your take on the ask vs your suggestion?

personally i think @adamkasper proposal and the ideas in #1720 make sense, because this is a common approach for Vue developers from a DX and UX point of view

for example this style is used a lot in

• @vueuse/*
• TresJS

at the same time, in @pinia/colada the "alternative approach" with getter wrappers works fine, we discussed it here #2597 (comment)

Why would someone expect one approach over the other?

as i wrote above, Vue developers are used to this style because many popular libraries use it

Is there a difference in performance?

no, theres no performance difference, the only difference is where you put computed (either outside like in my example, or inside the generated *Query like in @adamkasper example)

Is it a matter of experience?

the request is clear, its a widely used DX pattern, but thats not all

personally I see no problems with the approach I showed above, and the TanStack Query authors use it too, for example in tests

• https://github.com/TanStack/query/blob/9f82d8e56f00889db76729db03393bf972bef5c0/packages/vue-query/src/__tests__/useQuery.test-d.ts#L255-L266
• https://github.com/TanStack/query/blob/9f82d8e56f00889db76729db03393bf972bef5c0/packages/vue-query/src/__tests__/useQuery.test-d.ts#L268-L281

other developers use it in real projects as well, you can see that in issues

• [vue-query] useInfiniteQuery doesn't support infiniteQueryOptions with MaybeRef type TanStack/query#9562
• [vue-query] useQuery no longer accepts computed queryOptions TanStack/query#7474

and also this approach is not new for the Vue ecosystem (see @pinia/colada above)

Or purely a personal preference?

is it a bug - definitely no, its a "personal preference"

[mrlubos]

@brolnickij okay, sounds like we have a workaround so no one is blocked, and a potential issue to think about so fewer people trip up in the future. Would adding the proposed changes in addition to the current approach be feasible? Any concerns or should we just do it™?

[brolnickij]

@mrlubos

Would adding the proposed changes in addition to the current approach be feasible? Any concerns or should we just do it™?

im afraid its not that simple

after a deep analysis, heres what i found

• TanStack Vue query sits on vue-demi, so importing MaybeRefOrGetter / toValue / computed from vue inside the plugin would break vue@2 users (im one of them)
• those direct vue imports also dont match what TanStack exposes via vue-demi, so youd have to sprinkle // @ts-ignore and deal with fragile types that can drift
• TanStack Vue Query relies on internal helpers (cloneDeepUnref / resolveMaybeRefDeep / isPlainObject / …) that depend on vue-demi and the hooks (useQuery / queryOptions / queryKey) call those helpers, so the hooks are indirectly tied to vue-demi too - we need to reimplement that

proposal

• keep the idea on hold until TanStack Vue Query deprecates vue@2 support, or drop the idea entirely
• meanwhile use the computed(() => ...) pattern from the example above

it works, keeps the generated code clean, and adds no runtime deps :)

[mrlubos]

Thank you as always @brolnickij