Skip to main content

​
Installation

Get started with Vue Query in your Vue 2 or Vue 3 application.

​
Package Installation

npm install @tanstack/vue-query

​
Vue Version Requirements

Vue Query supports:
  • Vue 3.3+: Full support with Composition API
  • Vue 2.7: Built-in Composition API support
  • Vue 2.6: Requires @vue/composition-api plugin
Vue Query uses vue-demi to provide compatibility across Vue 2 and Vue 3, allowing you to use the same API regardless of your Vue version.

​
Vue 2.6 Setup

If you’re using Vue 2.6, you must install the Composition API plugin: 
npm install @vue/composition-api

​
Plugin Configuration

1
1. Initialize the Plugin
2
Register VueQueryPlugin to provide the QueryClient to your entire application:
3
Vue 3
import { createApp } from 'vue'
import { VueQueryPlugin } from '@tanstack/vue-query'
import App from './App.vue'

const app = createApp(App)
app.use(VueQueryPlugin)
app.mount('#app')
Vue 2.7
import Vue from 'vue'
import { VueQueryPlugin } from '@tanstack/vue-query'
import App from './App.vue'

Vue.use(VueQueryPlugin)

new Vue({
  render: (h) => h(App),
}).$mount('#app')
Vue 2.6
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { VueQueryPlugin } from '@tanstack/vue-query'
import App from './App.vue'

// Must install Composition API plugin first
Vue.use(VueCompositionAPI)
Vue.use(VueQueryPlugin)

new Vue({
  render: (h) => h(App),
}).$mount('#app')
4
2. Configure Default Options (Optional)
5
Customize default query and mutation behavior:
6
import { createApp } from 'vue'
import { VueQueryPlugin, QueryClient } from '@tanstack/vue-query'
import App from './App.vue'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      gcTime: 1000 * 60 * 10, // 10 minutes
      refetchOnWindowFocus: false,
      retry: 3,
    },
  },
})

const app = createApp(App)
app.use(VueQueryPlugin, { queryClient })
app.mount('#app')
7
3. Start Using Queries
8
Use Vue Query hooks in your components:
9
<script setup>
import { useQuery } from '@tanstack/vue-query'

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

<template>
  <div v-if="isLoading">Loading...</div>
  <div v-else>{{ data }}</div>
</template>

​
Configuration Options

The VueQueryPlugin accepts several configuration options:

​
Using a Custom QueryClient

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

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
})

app.use(VueQueryPlugin, {
  queryClient,
})

​
Using QueryClientConfig

Alternatively, pass configuration directly: 
app.use(VueQueryPlugin, {
  queryClientConfig: {
    defaultOptions: {
      queries: {
        staleTime: 1000 * 60 * 5,
      },
    },
  },
})

​
Enable DevTools

Enable Vue DevTools integration in development: 
app.use(VueQueryPlugin, {
  queryClient,
  enableDevtoolsV6Plugin: true,
})
DevTools are automatically disabled in production builds. The enableDevtoolsV6Plugin option only works in development mode.

​
Custom Client Key

Use a custom injection key for multiple QueryClient instances: 
app.use(VueQueryPlugin, {
  queryClient: primaryClient,
  queryClientKey: 'primary',
})

app.use(VueQueryPlugin, {
  queryClient: secondaryClient,
  queryClientKey: 'secondary',
})

// In components
const primaryClient = useQueryClient('primary')
const secondaryClient = useQueryClient('secondary')

​
Client Persistence

Persist and restore query cache using persisters: 
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const persister = createSyncStoragePersister({
  storage: window.localStorage,
})

app.use(VueQueryPlugin, {
  queryClient,
  clientPersister: (client) => {
    const unsubscribe = persister.persistClient(client)
    const restorePromise = persister.restoreClient(client)
    
    return [unsubscribe, restorePromise]
  },
  clientPersisterOnSuccess: (client) => {
    console.log('Client restored successfully')
  },
})

​
TypeScript Configuration

For the best TypeScript experience, configure your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": false,
    "types": ["@tanstack/vue-query"]
  }
}
Vue Query has excellent TypeScript support with full type inference. See the TypeScript guide for advanced patterns.

​
Vite Configuration

If you’re using Vite, no additional configuration is needed. Vue Query works out of the box:
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

​
Webpack Configuration

For Webpack users with Vue 2, configure vue-demi aliasing:
webpack.config.js
module.exports = {
  resolve: {
    alias: {
      vue: 'vue/dist/vue.esm.js',
    },
  },
}

​
Nuxt Configuration

For Nuxt applications, create a plugin file: 
import { VueQueryPlugin, QueryClient } from '@tanstack/vue-query'

export default defineNuxtPlugin((nuxtApp) => {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5000,
      },
    },
  })

  nuxtApp.vueApp.use(VueQueryPlugin, { queryClient })
})

​
Troubleshooting

​
”No ‘queryClient’ found in Vue context”

This error occurs when VueQueryPlugin isn’t installed:
  1. Verify you’ve called app.use(VueQueryPlugin) before mounting
  2. Check that hooks are used inside setup() or within an active effect scope
  3. Ensure the plugin is installed at the root level, not in a child component

​
”vue-query hooks can only be used inside setup()”

Vue Query hooks must be called within:
  • Component setup() functions
  • <script setup> blocks
  • Active effect scopes created by effectScope()
<script setup>
// ✅ Correct: Inside setup
import { useQuery } from '@tanstack/vue-query'

const query = useQuery({ queryKey: ['data'], queryFn: fetchData })
</script>

<script>
export default {
  setup() {
    // ✅ Correct: Inside setup function
    const query = useQuery({ queryKey: ['data'], queryFn: fetchData })
    return { query }
  },
  
  mounted() {
    // ❌ Wrong: Outside setup
    const query = useQuery({ queryKey: ['data'], queryFn: fetchData })
  },
}
</script>

​
Vue 2.6 Compatibility Issues

If you encounter errors with Vue 2.6:
  1. Ensure @vue/composition-api is installed
  2. Install it before VueQueryPlugin
  3. Use version 1.7.2 or higher of @vue/composition-api

​
Next Steps

Quick Start

Create your first query

TypeScript

Set up type safety

DevTools

Install and use DevTools

Overview

Learn core concepts

Build docs developers (and LLMs) love

Get started for freeTalk to us