Vue Query DevTools

Vue Query integrates with Vue DevTools to provide powerful debugging and inspection capabilities for your queries and mutations.

Overview

The Vue Query DevTools plugin adds a dedicated inspector to Vue DevTools where you can:

View all active queries in your application
Inspect query state, data, and metadata
Manually trigger refetches, invalidations, and resets
Monitor query cache updates in real-time
Debug query lifecycle events with timeline integration
Toggle online/offline mode for testing
Force loading or error states for development

Vue Query DevTools are automatically disabled in production builds. They only work in development mode.

Installation

DevTools are included in the main @tanstack/vue-query package. No additional installation is required.

Setup

1. Enable DevTools Plugin

Enable the DevTools plugin when installing VueQueryPlugin:

import { createApp } from 'vue'
import { VueQueryPlugin } from '@tanstack/vue-query'
import App from './App.vue'

const app = createApp(App)

app.use(VueQueryPlugin, {
  enableDevtoolsV6Plugin: true,
})

app.mount('#app')

2. Install Vue DevTools

If you don’t have Vue DevTools installed:

Browser Extension: Install from Chrome Web Store or Firefox Add-ons

Standalone App: Install via npm for use with any browser

npm install -g @vue/devtools
vue-devtools

3. Open DevTools

Open your browser’s DevTools (F12) and look for the “Vue” tab. You should see a “Vue Query” inspector in the sidebar.

DevTools Interface

Query Inspector

The main inspector shows all queries in your cache:

┌─────────────────────────────────────┐
│ Vue Query                           │
├─────────────────────────────────────┤
│ 🟢 ['todos'] [3]                    │
│ 🟢 ['user', 1] [1]                  │
│ 🔴 ['posts'] [2]                    │
│ 🟡 ['comments'] [0]                 │
└─────────────────────────────────────┘

Each query shows:

Status Badge: Color-coded query state (🟢 success, 🔴 error, 🟡 pending)
Query Key: The unique identifier for the query
Observer Count: Number of active observers [n]

Query Details Panel

Click any query to see detailed information:

Query Details

Query Key: The full query key
Query Status: Current status (success, error, pending)
Observers: Number of components watching this query
Last Updated: Timestamp of last successful fetch

Data Explorer

Inspect the current query data with full object explorer:

{
  "id": 1,
  "title": "Learn Vue Query",
  "completed": false,
  "user": {
    "id": 10,
    "name": "John Doe"
  }
}

Query Explorer

View the complete Query object including:

State (data, error, status, timestamps)
Options (staleTime, cacheTime, retry config)
Observers array
Internal metadata

Query Actions

The DevTools provide quick actions for each query:

Refetch

Manually trigger a refetch of the query:

// Equivalent to:
queryClient.refetchQueries({ queryKey: ['todos'] })

Use the Refetch button (🔄 icon) to force a fresh fetch.

Invalidate

Mark the query as stale and trigger refetch:

// Equivalent to:
queryClient.invalidateQueries({ queryKey: ['todos'] })

Use the Invalidate button (⏰ icon).

Reset

Reset the query to its initial state:

// Equivalent to:
queryClient.resetQueries({ queryKey: ['todos'] })

Use the Reset button (↻ icon).

Remove

Remove the query from the cache entirely:

// Equivalent to:
queryClient.removeQueries({ queryKey: ['todos'] })

Use the Remove button (🗑️ icon).

Removing a query deletes all cached data. Active observers will immediately refetch.

Force Loading

Set the query to loading state for testing:

// Forces the query into pending state
query.setState({ data: undefined, status: 'pending' })

Use the Force Loading button (⏳ icon).

Force Error

Set the query to error state for testing:

// Forces the query into error state
query.setState({
  data: undefined,
  status: 'error',
  error: new Error('Unknown error from devtools'),
})

Use the Force Error button (⚠️ icon).

Timeline Integration

Vue Query integrates with Vue DevTools Timeline to track query events:

Query Events

The timeline shows:

Query Added: When a new query is created
Query Updated: When query data changes
Query Removed: When a query is removed from cache

Each event includes:

Query hash for identification
Timestamp
Full event data

Timeline:
├─ 12:34:56 Query Added ['todos']
├─ 12:34:57 Query Updated ['todos']
├─ 12:35:02 Query Updated ['user', 1]
└─ 12:35:10 Query Removed ['old-data']

DevTools Settings

Customize DevTools behavior with built-in settings:

Sort Cache Entries

Change the sort order of queries:

ASC: Ascending order (default)
DESC: Descending order

Sort Function

Choose how queries are sorted:

By query key
By last update time
By observer count
By status

Online Mode

Toggle online/offline mode to test reconnection behavior:

Online: Normal operation (default)
Offline: Simulates network disconnection

// Programmatically control online status
import { onlineManager } from '@tanstack/vue-query'

onlineManager.setOnline(false) // Go offline
onlineManager.setOnline(true)  // Go back online

Use offline mode to test how your app behaves without network connectivity, including refetchOnReconnect behavior.

Filtering Queries

Use the search box to filter queries by query key:

Search: user

Results:
├─ ['user', 1]
├─ ['user', 2]
└─ ['users', 'list']

The filter uses fuzzy matching to find relevant queries.

DevTools Configuration

Customize DevTools behavior when setting up the plugin:

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

const queryClient = new QueryClient()

app.use(VueQueryPlugin, {
  queryClient,
  enableDevtoolsV6Plugin: process.env.NODE_ENV === 'development',
  queryClientKey: 'custom-key', // Custom injection key
})

Environment-Based Setup

Only enable DevTools in development:

const enableDevtools = import.meta.env.DEV

app.use(VueQueryPlugin, {
  enableDevtoolsV6Plugin: enableDevtools,
})

Debugging Common Issues

Queries Not Showing Up

Verify plugin is enabled: Check that enableDevtoolsV6Plugin: true is set
Check environment: DevTools only work in development mode
Confirm Vue DevTools is installed: Ensure the browser extension is active
Restart DevTools: Close and reopen browser DevTools

DevTools Performance Impact

DevTools add minimal overhead, but with many queries:

// Disable in production automatically
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // DevTools won't affect these settings
      staleTime: 5000,
    },
  },
})

DevTools code is tree-shaken from production builds, so there’s zero runtime cost in production.

Multiple QueryClient Instances

When using multiple clients, specify which to debug:

// Primary client with DevTools
app.use(VueQueryPlugin, {
  queryClient: primaryClient,
  enableDevtoolsV6Plugin: true,
  queryClientKey: 'primary',
})

// Secondary client without DevTools
app.use(VueQueryPlugin, {
  queryClient: secondaryClient,
  enableDevtoolsV6Plugin: false,
  queryClientKey: 'secondary',
})

DevTools API

Vue Query uses @vue/devtools-api for integration:

import { setupDevtoolsPlugin } from '@vue/devtools-api'
import type { CustomInspectorNode } from '@vue/devtools-api'

// This is handled internally by Vue Query
setupDevtoolsPlugin({
  id: 'vue-query',
  label: 'Vue Query',
  packageName: 'vue-query',
  homepage: 'https://tanstack.com/query/latest',
  app,
}, (api) => {
  // DevTools plugin implementation
})

You don’t need to interact with the DevTools API directly. Vue Query handles all integration automatically.

Best Practices

Development Workflow

Use Query Keys Consistently: Descriptive query keys make debugging easier
Monitor Observer Counts: High counts may indicate unnecessary re-renders
Check Stale/Fresh Status: Verify your staleTime configuration is working
Test Error States: Use “Force Error” to test error handling
Inspect Timeline: Track query lifecycle to understand refetch behavior

Debugging Strategies

Component.vue

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

// Descriptive query keys help in DevTools
const { data } = useQuery({
  queryKey: ['user', userId.value, 'profile'],
  queryFn: fetchUserProfile,
})

// Access client for debugging
const queryClient = useQueryClient()

// Log cache state
const logCache = () => {
  const cache = queryClient.getQueryCache().getAll()
  console.log('Cache state:', cache)
}
</script>

Performance Monitoring

Use DevTools to identify performance issues:

Too Many Observers: May indicate component re-render issues
Frequent Updates: Check if staleTime is too aggressive
Large Cache: Consider reducing gcTime or using removeQueries

Next Steps

Quick Start

Learn basic usage

TypeScript

Type-safe development

API Reference

Complete API documentation

Examples

Real-world examples

React

Vue

Solid

Svelte

Angular

Documentation Index

​Vue Query DevTools

​Overview

​Installation

​Setup

​DevTools Interface

​Query Inspector

​Query Details Panel

​Query Details

​Data Explorer

​Query Explorer

​Query Actions

​Timeline Integration

​Query Events

​DevTools Settings

​Sort Cache Entries

​Sort Function

​Online Mode

​Filtering Queries

​DevTools Configuration

​Environment-Based Setup

​Debugging Common Issues

​Queries Not Showing Up

​DevTools Performance Impact

​Multiple QueryClient Instances

​DevTools API

​Best Practices

​Development Workflow

​Debugging Strategies

​Performance Monitoring

​Next Steps

Quick Start

TypeScript

API Reference

Examples

Build docs developers (and LLMs) love

Vue Query DevTools

Overview

Installation

Setup

DevTools Interface

Query Inspector

Query Details Panel

Query Details

Data Explorer

Query Explorer

Query Actions

Timeline Integration

Query Events

DevTools Settings

Sort Cache Entries

Sort Function

Online Mode

Filtering Queries

DevTools Configuration

Environment-Based Setup

Debugging Common Issues

Queries Not Showing Up

DevTools Performance Impact

Multiple QueryClient Instances

DevTools API

Best Practices

Development Workflow

Debugging Strategies

Performance Monitoring

Next Steps