Installation

Install and configure Vue Query in your Vue application

Installation

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

Package Installation

npm

npm install @tanstack/vue-query

pnpm add @tanstack/vue-query

yarn add @tanstack/vue-query

bun add @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

npm install @vue/composition-api

pnpm add @vue/composition-api

yarn add @vue/composition-api

Plugin Configuration

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:

plugins/vue-query.ts (Nuxt 3)

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

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

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

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

const queryClient = new QueryClient()

export default () => {
  Vue.use(VueQueryPlugin, { queryClient })
}

Troubleshooting

”No ‘queryClient’ found in Vue context”

This error occurs when VueQueryPlugin isn’t installed:

”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