Using TanStack Query in Vue.js: A Quick Guide

When building modern Vue 3 applications, managing server data can become complicated: loading states, caching, refetching, error handling… all require boilerplate code.
TanStack Vue Query solves this by giving you a powerful, declarative way to fetch, update, and sync server data — with almost no setup.

What is TanStack Vue Query?

TanStack Query (Vue Query) is a library that handles:

• Fetching async data
• Caching results
• Automatic background refetching
• Mutations (POST, PUT, DELETE)
• Error + retry logic

It focuses specifically on remote server state, not UI/local state.

Installation

npm install @tanstack/vue-query

// main.ts
import { VueQueryPlugin } from '@tanstack/vue-query'
createApp(App).use(VueQueryPlugin).mount('#app')

Basic Data Fetching with useQuery()

<script setup>
import { useQuery } from '@tanstack/vue-query'

const { data, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then(r => r.json())
})
</script>

<template>
  <div v-if="isLoading">Loading...</div>
  <div v-else-if="error">Failed to load data</div>

  <ul>
    <li v-for="u in data" :key="u.id">{{ u.name }}</li>
  </ul>
</template>

What this gives you for free:

• caching
• loading + error states
• refetch on window focus
• request deduplication

Useful TanStack Vue Query Configurations

Add this to main.ts to control the default behavior for every query in your app (global config):

// main.ts
import { VueQueryPlugin, QueryClient } from '@tanstack/vue-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // how long data stays "fresh"
      staleTime: 1000 * 60, // 1 minute

      // how long data stays in cache before GC cleanup
      gcTime: 1000 * 60 * 10, // 10 minutes

      // auto refetch when window refocuses
      refetchOnWindowFocus: true,

      // retry failed requests
      retry: 2,

      // delay between retries
      retryDelay: 1000,

      // no refetch when component mounts if cached
      refetchOnMount: false,
    },
    mutations: {
      retry: 0 // usually no retry for POST/PUT/DELETE
    }
  }
})

app.use(VueQueryPlugin, { queryClient })

Custom Query-Specific Config

const { data, isLoading } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  staleTime: 5000, // this query is fresh for 5 seconds
  retry: 3,        // retry more aggressively
  refetchInterval: 10000, // auto refetch every 10 seconds
})

Good for

• Live dashboards
• Status monitoring
• Data that changes often

Why Use TanStack Query in Vue?

• You avoid watch + onMounted for API calls
• Your API caching becomes automatic
• Your UI always stays in sync with the server
• Your code becomes cleaner and more declarative

Conclusion

TanStack Vue Query is one of the simplest and most powerful ways to manage server data in Vue 3 applications. With built-in caching, background updates, and automatic error handling, it eliminates repetitive boilerplate and gives you a clean, reliable data layer.