0
# Svelte Query Devtools
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @tanstack/svelte-query-devtools
7
- **Package Type**: npm
8
- **Language**: TypeScript/Svelte
9
- **Installation**: `npm install @tanstack/svelte-query-devtools`
10

11
## Core Imports
12

13
```typescript
14
import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
15
```
16

17
For direct Svelte component imports:
18

19
```svelte
20
<script>
21
  import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
22
</script>
23
```
24

25
## Basic Usage
26

27
```svelte
28
<script>
29
  import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
30
</script>
31

32
<!-- Basic devtools with default settings -->
33
<SvelteQueryDevtools />
34

35
<!-- Devtools with custom positioning -->
36
<SvelteQueryDevtools
37
  position="top"
38
  buttonPosition="top-left"
39
  initialIsOpen={true}
40
/>
41
```
42

43
## Architecture
44

45
The devtools component is built around several key design patterns:
46

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

53
## Capabilities
54

55
### Svelte Query Devtools Component
56

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

59
```typescript { .api }
60
/**
61
 * Svelte component that renders TanStack Query devtools interface
62
 * Only renders in development mode and browser environment
63
 */
64
interface SvelteQueryDevtoolsProps {
65
  /** Whether the devtools panel should be open by default */
66
  initialIsOpen?: boolean;
67
  /** Position of the devtools toggle button */
68
  buttonPosition?: DevtoolsButtonPosition;
69
  /** Position of the devtools panel */
70
  position?: DevtoolsPosition;
71
  /** TanStack Query client instance to debug (defaults to context client) */
72
  client?: QueryClient;
73
  /** Array of error types to filter in the devtools interface */
74
  errorTypes?: Array<DevtoolsErrorType>;
75
  /** CSP nonce for inline styles (for strict CSP environments) */
76
  styleNonce?: string;
77
  /** Shadow DOM root to render devtools into (for isolated styling) */
78
  shadowDOMTarget?: ShadowRoot;
79
  /** Whether to hide disabled queries from the devtools interface */
80
  hideDisabledQueries?: boolean;
81
}
82
```
83

84
**Component Props:**
85

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

95
**Usage Examples:**
96

97
```svelte
98
<script>
99
  import { SvelteQueryDevtools } from "@tanstack/svelte-query-devtools";
100
  import { useQueryClient } from "@tanstack/svelte-query";
101
  
102
  const client = useQueryClient();
103
</script>
104

105
<!-- Basic usage with defaults -->
106
<SvelteQueryDevtools />
107

108
<!-- Custom positioning -->
109
<SvelteQueryDevtools
110
  position="left"
111
  buttonPosition="bottom-left" 
112
/>
113

114
<!-- With error filtering -->
115
<SvelteQueryDevtools
116
  errorTypes={[
117
    {
118
      name: "NetworkError",
119
      initializer: (query) => new Error(`Network error in ${query.queryKey}`)
120
    }
121
  ]}
122
/>
123

124
<!-- Custom client and CSP configuration -->
125
<SvelteQueryDevtools
126
  {client}
127
  styleNonce="your-csp-nonce"
128
  hideDisabledQueries={true}
129
/>
130
```
131

132
## Types
133

134
```typescript { .api }
135
/**
136
 * Position options for the devtools toggle button
137
 * Template literal type combining Y and X positions, plus relative option
138
 */
139
type DevtoolsButtonPosition = 
140
  | 'top-left' 
141
  | 'top-right' 
142
  | 'bottom-left' 
143
  | 'bottom-right' 
144
  | 'relative';
145

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

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

162
/**
163
 * TanStack Query client interface
164
 * Imported from @tanstack/svelte-query
165
 */
166
interface QueryClient {
167
  // Core query client functionality
168
  // See @tanstack/svelte-query documentation
169
}
170
```
171

172
## Runtime Behavior
173

174
The component implements several important runtime behaviors:
175

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

183
## Dependencies
184

185
### Runtime Dependencies
186
- `@tanstack/query-devtools`: Core devtools implementation
187
- `esm-env`: Environment detection utilities (DEV/BROWSER flags)
188

189
### Peer Dependencies
190
- `@tanstack/svelte-query`: TanStack Query Svelte integration (required for QueryClient and useQueryClient)
191
- `svelte`: Svelte framework (versions 3.54.0+, 4.x, or 5.x supported)
192

193
## Integration Notes
194

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