DevTools

Debug and visualize your Svelte Query cache with the official DevTools

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

   npm install -D @tanstack/svelte-query-devtools
   

   pnpm add -D @tanstack/svelte-query-devtools
   

   yarn add -D @tanstack/svelte-query-devtools
   

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

• DevTools Source Code
• TanStack Query DevTools
• Report Issues

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