Skip to main content
The Svelte Query DevTools help you visualize all of the inner workings of Svelte Query and will likely save you hours of debugging if you find yourself in a pinch.

​
Installation

1

Install the package

Install the DevTools package as a dev dependency:
npm install -D @tanstack/svelte-query-devtools
The DevTools package version is 6.0.4 and is compatible with @tanstack/svelte-query 6.0.0+.
2

Import and add to your app

Add the SvelteQueryDevtools component to your root layout:
+layout.svelte
<script lang="ts">
import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'
import { SvelteQueryDevtools } from '@tanstack/svelte-query-devtools'

const queryClient = new QueryClient()
const { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
  <SvelteQueryDevtools />
</QueryClientProvider>
Place the DevTools component anywhere inside the QueryClientProvider. It’s common to put it at the end of your layout.
3

Start your app

The DevTools will now appear in your app during development. They are automatically removed from production builds.
npm run dev

​
Features

The Svelte Query DevTools provide powerful debugging capabilities:

​
Query Explorer

View all queries in your application:
  • Active queries - Currently mounted and in use
  • Inactive queries - Cached but not mounted
  • Stale queries - Data that needs refetching
  • Fresh queries - Recently fetched data

​
Query Inspector

Click on any query to see detailed information:
  • Query key
  • Query status (pending, error, success)
  • Last updated timestamp
  • Data preview
  • Query configuration
  • Observers count
  • Query tags

​
Mutation Inspector

Track all mutations in your app:
  • Mutation status
  • Variables passed to mutation
  • Mutation response data
  • Error information

​
Actions

Perform actions on queries:
  • Refetch - Manually trigger a refetch
  • Invalidate - Mark query as stale
  • Remove - Remove query from cache
  • Reset - Reset error state

​
Configuration

Customize the DevTools appearance and behavior:
+layout.svelte
<script lang="ts">
import { SvelteQueryDevtools } from '@tanstack/svelte-query-devtools'

const queryClient = new QueryClient()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
  
  <SvelteQueryDevtools
    initialIsOpen={false}
    buttonPosition="bottom-right"
    position="bottom"
    client={queryClient}
  />
</QueryClientProvider>

​
Options

​
initialIsOpen
boolean
default:"false"
Set to true to have the DevTools open by default on page load.
<SvelteQueryDevtools initialIsOpen={true} />
​
buttonPosition
string
default:"bottom-right"
Position of the toggle button. Options: 'top-left', 'top-right', 'bottom-left', 'bottom-right'.
<SvelteQueryDevtools buttonPosition="top-left" />
​
position
string
default:"bottom"
Position of the DevTools panel. Options: 'top', 'bottom', 'left', 'right'.
<SvelteQueryDevtools position="right" />
​
client
QueryClient
default:"useQueryClient()"
Custom QueryClient instance. By default, uses the client from context.
<SvelteQueryDevtools client={customQueryClient} />
​
errorTypes
Array<DevtoolsErrorType>
default:"[]"
Custom error types to display in the DevTools.
<SvelteQueryDevtools
  errorTypes={[
    { name: 'ValidationError', initializer: (data) => data },
  ]}
/>
​
styleNonce
string
Nonce for Content Security Policy (CSP). Used for inline styles.
<SvelteQueryDevtools styleNonce="random-nonce-123" />
​
shadowDOMTarget
ShadowRoot
Attach DevTools styles to a specific Shadow DOM target.
<SvelteQueryDevtools shadowDOMTarget={shadowRoot} />
​
hideDisabledQueries
boolean
default:"false"
Hide disabled queries from the query list.
<SvelteQueryDevtools hideDisabledQueries={true} />

​
Usage Examples

​
Basic Setup

The simplest configuration:
+layout.svelte
<script lang="ts">
import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'
import { SvelteQueryDevtools } from '@tanstack/svelte-query-devtools'

const queryClient = new QueryClient()
const { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
  <SvelteQueryDevtools />
</QueryClientProvider>

​
Custom Position

Position the DevTools on the right side: 
<SvelteQueryDevtools
  position="right"
  buttonPosition="bottom-right"
/>

​
Open by Default

Useful during development: 
<SvelteQueryDevtools
  initialIsOpen={true}
  position="bottom"
/>

​
With SvelteKit

Only show DevTools in development:
+layout.svelte
<script lang="ts">
import { dev } from '$app/environment'
import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'
import { SvelteQueryDevtools } from '@tanstack/svelte-query-devtools'

const queryClient = new QueryClient()
const { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
  {#if dev}
    <SvelteQueryDevtools />
  {/if}
</QueryClientProvider>
The DevTools are automatically tree-shaken from production builds, but you can add an explicit check for clarity.

​
DevTools Interface

​
Query States

Queries are color-coded by state:
  • Green - Fresh data (within staleTime)
  • Yellow - Stale data (needs refetch)
  • Gray - Inactive (cached but not mounted)
  • Blue - Fetching (currently refetching)
  • Red - Error state

​
Filter Queries

Use the search bar to filter queries: 
// Filter by query key
posts

// Filter by status
status:stale

// Filter by observer count
observers:>0

​
Sort Queries

Sort queries by:
  • Query key
  • Last updated
  • Observer count
  • Status

​
Debugging Tips

1

Inspect query keys

Click on a query to see its full query key structure. This helps ensure your keys are unique and properly structured.
// Good query key structure
['posts', { status: 'published', author: 1 }]

// Query key visible in DevTools
2

Monitor refetch behavior

Watch the “Last Updated” timestamp to see when queries refetch. This helps debug issues with:
  • staleTime configuration
  • Window focus refetching
  • Interval refetching
3

Check observer count

The observer count shows how many components are using a query. If it’s 0, the query is inactive and may be garbage collected.
4

Inspect error states

When a query fails, click on it to see:
  • Error message
  • Error stack trace
  • Failed query configuration
  • Retry count

​
Advanced Features

​
Custom Error Types

Display custom error information: 
<script lang="ts">
import type { DevtoolsErrorType } from '@tanstack/query-devtools'

const errorTypes: DevtoolsErrorType[] = [
  {
    name: 'ApiError',
    initializer: (error: any) => ({
      message: error.message,
      statusCode: error.statusCode,
      endpoint: error.endpoint,
    }),
  },
]
</script>

<SvelteQueryDevtools {errorTypes} />

​
Shadow DOM Integration

For apps using Shadow DOM: 
<script lang="ts">
import { onMount } from 'svelte'

let shadowRoot: ShadowRoot

onMount(() => {
  const host = document.getElementById('app')
  shadowRoot = host?.shadowRoot
})
</script>

<SvelteQueryDevtools shadowDOMTarget={shadowRoot} />

​
CSP Nonce Support

For Content Security Policy compliance: 
<script lang="ts">
const nonce = 'random-nonce-value'
</script>

<SvelteQueryDevtools styleNonce={nonce} />

​
Performance

The DevTools are designed to have minimal performance impact:
  • Lazy loaded - Only imported when used
  • Development only - Automatically removed in production
  • Efficient updates - Only re-renders when query state changes
  • Virtual scrolling - Handles thousands of queries efficiently
While the DevTools are optimized, having hundreds of active queries may slow down the interface. Consider using query filters or hideDisabledQueries in such cases.

​
Keyboard Shortcuts

Use keyboard shortcuts for faster navigation:
  • Cmd/Ctrl + K - Toggle DevTools
  • / - Focus search
  • ↑/↓ - Navigate queries
  • Enter - Open selected query
  • Esc - Close query detail

​
Troubleshooting

​
DevTools not appearing

Check that:
  1. You’re in development mode
  2. The component is inside QueryClientProvider
  3. The package is installed correctly
npm list @tanstack/svelte-query-devtools

​
DevTools in production

The DevTools should be automatically removed. If they appear in production:
  1. Check your build configuration
  2. Ensure you’re using a production build:
npm run build

​
Styling conflicts

If DevTools styles conflict with your app:
  1. Use shadowDOMTarget to isolate styles
  2. Adjust position and buttonPosition
  3. Apply custom CSS overrides

​
Implementation Details

The DevTools component is implemented in /packages/svelte-query-devtools/src/Devtools.svelte and uses:
  • Svelte 5 runes - $state, $effect, $derived
  • Dynamic import - Lazy loads @tanstack/query-devtools
  • Environment detection - DEV and BROWSER from esm-env
  • QueryClient integration - Uses useQueryClient and onlineManager
// Internal implementation
if (DEV && BROWSER) {
  import('@tanstack/query-devtools').then((m) => {
    const QueryDevtools = m.TanstackQueryDevtools
    devtools = new QueryDevtools({
      client,
      queryFlavor: 'Svelte Query',
      version: '5',
      onlineManager,
      // ... options
    })
    devtools.mount(ref)
  })
}

​
Next Steps

1

Explore Advanced Features

Learn about SSR, persistence, and more advanced patterns.Advanced Guides →
2

Production Deployment

Learn best practices for deploying Svelte Query apps.Best Practices →

​
Resources

The Svelte Query DevTools are maintained as part of the TanStack Query project and follow the same versioning and release cycle.

Build docs developers (and LLMs) love

Get started for freeTalk to us