Svelte Query Devtools

Svelte Query Devtools provides developer tools specifically designed for Svelte applications using TanStack Query (formerly React Query). It offers a Svelte component that renders an interactive devtools panel for visualizing and debugging the query cache, inspecting query states, mutations, and cache data.

Package Information

• Package Name: @tanstack/svelte-query-devtools
• Package Type: npm
• Language: TypeScript/Svelte
• Installation: npm install @tanstack/svelte-query-devtools

Core Imports

import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";

For direct Svelte component imports:

<script>
  import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
</script>

Basic Usage

<script>
  import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
</script>

<!-- Basic devtools with default settings -->
<SvelteQueryDevtools />

<!-- Devtools with custom positioning -->
<SvelteQueryDevtools
  position="top"
  buttonPosition="top-left"
  initialIsOpen={true}
/>

Architecture

The devtools component is built around several key design patterns:

• Svelte Wrapper: Provides a Svelte-specific interface around the core @tanstack/query-devtools library
• Environment Detection: Only renders in development mode and browser environments to avoid production overhead
• Dynamic Loading: Lazy loads the core devtools library on component mount to minimize bundle size
• Reactive Configuration: Uses Svelte's reactive statements to dynamically update devtools settings when props change
• Context Integration: Automatically integrates with existing TanStack Query client context

Capabilities

Svelte Query Devtools Component

Interactive developer tools component that provides visualization and debugging capabilities for TanStack Query cache in Svelte applications.

/**
 * Svelte component that renders TanStack Query devtools interface
 * Only renders in development mode and browser environment
 */
interface SvelteQueryDevtoolsProps {
  /** Whether the devtools panel should be open by default */
  initialIsOpen?: boolean;
  /** Position of the devtools toggle button */
  buttonPosition?: DevtoolsButtonPosition;
  /** Position of the devtools panel */
  position?: DevtoolsPosition;
  /** TanStack Query client instance to debug (defaults to context client) */
  client?: QueryClient;
  /** Array of error types to filter in the devtools interface */
  errorTypes?: Array<DevtoolsErrorType>;
  /** CSP nonce for inline styles (for strict CSP environments) */
  styleNonce?: string;
  /** Shadow DOM root to render devtools into (for isolated styling) */
  shadowDOMTarget?: ShadowRoot;
  /** Whether to hide disabled queries from the devtools interface */
  hideDisabledQueries?: boolean;
}

Component Props:

• initialIsOpen: Whether the devtools panel should be open by default
• buttonPosition: Position of the devtools toggle button
• position: Position of the devtools panel
• client: TanStack Query client instance to debug (defaults to context client)
• errorTypes: Array of error types to filter in the devtools interface
• styleNonce: CSP nonce for inline styles (for strict CSP environments)
• shadowDOMTarget: Shadow DOM root to render devtools into (for isolated styling)
• hideDisabledQueries: Whether to hide disabled queries from the devtools interface

Usage Examples:

<script>
  import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
  import { useQueryClient } from "@tanstack/svelte-query";
  
  const client = useQueryClient();
</script>

<!-- Basic usage with defaults -->
<SvelteQueryDevtools />

<!-- Custom positioning -->
<SvelteQueryDevtools
  position="left"
  buttonPosition="bottom-left" 
/>

<!-- With error filtering -->
<SvelteQueryDevtools
  errorTypes={[
    {
      name: "NetworkError",
      initializer: (query) => new Error(`Network error in ${query.queryKey}`)
    }
  ]}
/>

<!-- Custom client and CSP configuration -->
<SvelteQueryDevtools
  {client}
  styleNonce="your-csp-nonce"
  hideDisabledQueries={true}
/>

Types

/**
 * Position options for the devtools toggle button
 * Template literal type combining Y and X positions, plus relative option
 */
type DevtoolsButtonPosition = 
  | 'top-left' 
  | 'top-right' 
  | 'bottom-left' 
  | 'bottom-right' 
  | 'relative';

/**
 * Position options for the devtools panel
 * Can be positioned on any edge of the screen
 */
type DevtoolsPosition = 'top' | 'bottom' | 'left' | 'right';

/**
 * Configuration for error type filtering in devtools
 */
interface DevtoolsErrorType {
  /** The name of the error type */
  name: string;
  /** Function that creates an error instance from a query */
  initializer: (query: import('@tanstack/query-core').Query) => Error;
}

/**
 * TanStack Query client interface
 * Imported from @tanstack/svelte-query
 */
interface QueryClient {
  // Core query client functionality
  // See @tanstack/svelte-query documentation
}

Runtime Behavior

The component implements several important runtime behaviors:

• Development Only: Component only renders content when DEV && BROWSER environment conditions are met
• Lazy Loading: Core devtools library is dynamically imported on component mount to avoid including it in production builds
• Automatic Cleanup: Properly unmounts devtools when the Svelte component is destroyed
• Context Integration: Uses useQueryClient() by default to automatically access the query client from Svelte context
• Reactive Updates: Uses Svelte reactive statements ($:) to update devtools configuration when props change
• Error Boundary: Safe initialization that prevents crashes if devtools cannot be loaded

Dependencies

Runtime Dependencies

• @tanstack/query-devtools: Core devtools implementation
• esm-env: Environment detection utilities (DEV/BROWSER flags)

Peer Dependencies

• @tanstack/svelte-query: TanStack Query Svelte integration (required for QueryClient and useQueryClient)
• svelte: Svelte framework (versions 3.54.0+, 4.x, or 5.x supported)

Integration Notes

• The component is designed to be drop-in compatible with existing TanStack Query Svelte applications
• No additional setup required beyond importing and using the component
• Automatically integrates with the existing query client context
• Tree-shakeable in production builds when not used
• Supports all modern Svelte versions and compilation targets