Vue Query

Purpose and Scope

Vue Query is the Vue framework adapter for TanStack Query, the server-state manager used to fetch, cache, share, refetch, mutate, and observe asynchronous data. The repository documentation treats Vue as a first-class framework alongside React, Solid, Svelte, Angular, and Lit, and the docs configuration exposes a dedicated Vue section with overview, installation, quick start, devtools, TypeScript, reactivity, and GraphQL pages. This page orients Vue readers to that adapter-shaped workflow while tying the explanation to the shared Query concepts visible in the repository docs. Sources: docs/config.json

The most important mental model is that Vue Query is not a replacement for local component state. It coordinates remote data that can be stale, shared by multiple components, refreshed in the background, invalidated after writes, and observed by developer tools. The official product framing describes TanStack Query as giving async data a cache, lifecycle, and declarative APIs across TypeScript applications. Vue users apply those same primitives through Vue-native composables and provider setup rather than through React hooks or Angular injection functions. Sources: docs/config.json, docs/framework/angular/guides/background-fetching-indicators.md

Relevant Source Files

• docs/config.json — Defines the documentation navigation and shows Vue as a supported framework with pages for overview, installation, quick start, devtools, TypeScript, reactivity, and GraphQL.
• docs/framework/angular/reference/functions/provideTanStackQuery.md — Shows the provider-style adapter contract used to install a QueryClient into a framework application and enable optional features.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md — Documents the promise-based fetching model that applies across adapters, even when a framework has its own data client abstraction.
• docs/framework/angular/devtools.md — Explains framework-specific devtools enablement, development-mode behavior, production loading controls, and the role of shared query debugging tools.
• docs/framework/angular/guides/background-fetching-indicators.md — Demonstrates adapter-level query state such as pending, error, success, fetching, and global background-fetch indicators.
• docs/community-resources.md — Lists community learning resources and ecosystem utilities that help users deepen Query practices beyond the framework-specific quick starts.

Core Primitives

A Vue Query application is built around the same core primitives that appear throughout TanStack Query. A QueryClient owns the query and mutation caches, default options, invalidation behavior, and imperative operations such as prefetching or reading cached data. A provider makes that client available to the component tree. A query composable declares a key and an asynchronous function, then exposes status, data, error, and fetching information to the template or setup function. Mutations use the same cache contract to update server data, invalidate related queries, and coordinate optimistic user interface flows. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/guides/background-fetching-indicators.md

The Angular provider reference is useful for Vue readers because it documents the adapter pattern in explicit terms: an application supplies a QueryClient, and the framework adapter wires the providers necessary to enable TanStack Query functionality. In Vue, the exact public names differ, but the responsibilities are the same. Create one client for the part of the app that should share cache state, install it near the root, and let child components declare data requirements through framework-native APIs. Optional features, especially devtools, attach to the same provider boundary. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/devtools.md

Installation and App Setup

Start Vue Query setup by installing the Vue adapter package for your TanStack Query version, then create a QueryClient during application bootstrap. Mount the plugin or provider before components call query composables, because those composables need the client context to find the shared cache. The docs configuration places Vue installation and quick start immediately after the Vue overview, which reflects the recommended learning order: understand the adapter, install it, wire the client, then write the first query. Keep client creation outside frequently re-rendered component code so cache identity remains stable. Sources: docs/config.json

A minimal Vue application usually has three moving pieces: the application instance, the QueryClient, and the Vue Query plugin or provider. After setup, components can call the Vue composable that corresponds to a query, passing a stable query key and a function that returns a promise. Query keys are the cache identity; changing the key describes a different resource or set of parameters. Query functions are deliberately backend-agnostic. The Angular data-client guide states that TanStack Query fetching is built on promises and can work with browser fetch, GraphQL clients, or other asynchronous clients, which is the same constraint Vue query functions should satisfy. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'
import { createApp } from 'vue'
import App from './App.vue'
 
const queryClient = new QueryClient()
 
createApp(App).use(VueQueryPlugin, { queryClient }).mount('#app')

Query Composables and Fetching Flow

In a Vue component, the query flow starts when a composable is evaluated with options that include a query key and a query function. The adapter subscribes the component to a query observer, the cache deduplicates work for matching keys, and the result object exposes states for rendering. The Angular background-fetching example demonstrates the same lifecycle shape with pending, error, success, and fetching branches. Vue templates typically map those fields to loading placeholders, error messages, normal data views, and subtle refresh indicators while a successful query refetches in the background. Sources: docs/framework/angular/guides/background-fetching-indicators.md

<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
 
const todosQuery = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})
</script>
 
<template>
  <p v-if="todosQuery.isPending.value">Loading...</p>
  <p v-else-if="todosQuery.isError.value">Something went wrong</p>
  <section v-else>
    <p v-if="todosQuery.isFetching.value">Refreshing...</p>
    <TodoItem v-for="todo in todosQuery.data.value" :key="todo.id" :todo="todo" />
  </section>
</template>

Because TanStack Query is promise-based, the query function boundary is intentionally simple. If a Vue app uses fetch, an OpenAPI-generated client, a GraphQL client, or another asynchronous wrapper, the function should resolve data or throw an error. The Angular guide calls out the same rule when converting observables into promises for that framework. Vue does not require Angular’s observable conversion step, but the underlying principle still matters: the adapter owns cache lifecycle and observation, while the application owns the actual request implementation and any authentication, headers, generated client calls, or transport-specific behavior. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Devtools, Reactivity, and Background Indicators

The Vue docs spine includes a dedicated devtools page, and the Angular devtools documentation shows the broader adapter goal: make queries and mutations inspectable without changing application data flow. Devtools help developers see cache entries, observers, stale state, errors, and background work. Browser extensions are also documented for major browsers, and framework-specific packages can expose embedded or application-mounted panels. For Vue teams, devtools are most useful during key design, invalidation debugging, and situations where a component appears stale because it is observing one key while a mutation invalidates another. Sources: docs/config.json, docs/framework/angular/devtools.md

Background fetching indicators are another shared adapter pattern. A successful query can be rendering cached data and still be fetching a newer value, so a loading spinner that replaces the whole screen is often the wrong user experience after the initial load. The Angular example separates initial pending state from an is-fetching refresh hint and also shows a global fetching indicator. Vue Query users should make the same distinction in templates: block only when no useful data exists, and show lightweight refresh affordances when cached data is already available. Sources: docs/framework/angular/guides/background-fetching-indicators.md

Package Surface and Documentation Map

The repository documentation map is the most direct source for the Vue public learning surface in the supplied evidence. It names Vue pages for overview, installation, quick start, devtools, TypeScript, reactivity, and GraphQL. That structure implies a practical progression: first install and provide the QueryClient, then write queries, then learn how Vue reactivity interacts with query options and returned result fields, and finally integrate typed APIs or GraphQL clients. Community resources add broader best-practice material, including maintainer-authored posts and utilities for query keys, generated clients, normalization, and request batching. Sources: docs/config.json, docs/community-resources.md

Next Steps

After wiring Vue Query, continue with the Vue quick start and reactivity docs before designing a large cache. Pay close attention to query keys, because keys become the shared contract for reads, invalidation, prefetching, devtools inspection, and mutation follow-up work. Then add devtools in development and verify that background fetching behaves as expected in real navigation flows. If your app uses generated OpenAPI clients, GraphQL clients, or framework-specific request wrappers, keep those concerns inside promise-returning query functions and let Vue Query handle cache lifecycle, observers, retries, and refetch coordination. Sources: docs/config.json, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/framework/angular/devtools.md