Call operations

@kubb/plugin-vue-query turns each operation into a composable that wraps the client function from @kubb/plugin-axios or @kubb/plugin-fetch. Read operations become useFoo, write operations become useFoo mutations, and every composable is typed from the spec.

IMPORTANT

By default the plugin emits only the factory helpers (queryOptions, queryKey, mutationKey). Set hooks: true in the plugin options to also generate the use* composables shown below.

Queries

A query composable takes the operation's grouped request config as its first argument. Parameters accept a value, a ref, or a getter (MaybeRefOrGetter), so the query re-runs when a reactive parameter changes:

import { ref } from 'vue'
import { useFindPetsByTags } from './gen/hooks/useFindPetsByTags'

const tags = ref(['dog'])
const { data, error, isLoading } = useFindPetsByTags({ query: () => ({ tags: tags.value }) })

The second argument holds two option groups. query takes any TanStack Query option plus a client to target a specific QueryClient. client takes per-call request config for the underlying client:

import { useFindPetsByTags } from './gen/hooks/useFindPetsByTags'

useFindPetsByTags(
  { query: { tags: ['dog'] } },
  {
    query: { staleTime: 60_000 },
    client: { headers: { 'X-Trace': 'abc' } },
  },
)

Factories

Every query operation also exports a queryOptions factory and a queryKey helper for prefetching and invalidation. The key is [{ url }, query], built from the operation path and its query params:

import { useQueryClient } from '@tanstack/vue-query'
import { findPetsByTagsQueryKey, findPetsByTagsQueryOptions } from './gen/hooks/useFindPetsByTags'

const queryClient = useQueryClient()

await queryClient.prefetchQuery(findPetsByTagsQueryOptions({ query: { tags: ['dog'] } }))
queryClient.invalidateQueries({ queryKey: findPetsByTagsQueryKey({ query: { tags: ['dog'] } }) })

Mutations export a mutationKey helper next to the composable.

Mutations

A mutation composable takes only an options object. The grouped request config is the mutation variable, so you pass it to mutate or mutateAsync:

import { useQueryClient } from '@tanstack/vue-query'
import { useUpdatePetWithForm } from './gen/hooks/useUpdatePetWithForm'

const queryClient = useQueryClient()

const { mutate } = useUpdatePetWithForm({
  mutation: { onSuccess: () => queryClient.invalidateQueries() },
})

mutate({ path: { petId: 1 }, query: { name: 'Fluffy' } })

Errors and transport

The generated hooks call the client operation with throwOnError: true, so failures surface through the query library's error state, typed from the spec's error responses. Transport concerns (base URL, authentication, interceptors, serialization, validation) live on the client plugin: see the plugin-fetch or plugin-axios guides.