0
# TanStack React Query Devtools
1
2
TanStack React Query Devtools provides React-specific developer tools for TanStack Query (formerly React Query), enabling developers to inspect, debug, and visualize query cache state, mutations, and data fetching operations in React applications. It offers both floating devtools components and embedded panels that integrate directly into applications during development.
3
4
## Package Information
5
6
- **Package Name**: @tanstack/react-query-devtools
7
- **Package Type**: npm
8
- **Language**: TypeScript/React
9
- **Installation**: `npm install @tanstack/react-query-devtools` or `pnpm add @tanstack/react-query-devtools`
10
11
## Core Imports
12
13
```typescript
14
import { ReactQueryDevtools, ReactQueryDevtoolsPanel, type DevtoolsPanelOptions } from "@tanstack/react-query-devtools";
15
```
16
17
For production builds (always renders devtools):
18
19
```typescript
20
import { ReactQueryDevtools, ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools/production";
21
// Note: No types are exported from the production entry point
22
// Import types from main entry if needed: import type { DevtoolsPanelOptions } from "@tanstack/react-query-devtools";
23
```
24
25
## Basic Usage
26
27
```typescript
28
import React from "react";
29
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
30
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
31
32
const queryClient = new QueryClient();
33
34
function App() {
35
return (
36
<QueryClientProvider client={queryClient}>
37
<div className="app">
38
{/* Your app components */}
39
</div>
40
41
{/* Floating devtools - only shows in development */}
42
<ReactQueryDevtools initialIsOpen={false} />
43
</QueryClientProvider>
44
);
45
}
46
```
47
48
## Architecture
49
50
The devtools package provides two distinct components:
51
52
- **ReactQueryDevtools**: A floating devtools component with a toggle button that can be positioned anywhere on screen
53
- **ReactQueryDevtoolsPanel**: An embedded panel component that displays devtools inline within your application
54
- **Environment Safety**: Main entry point automatically excludes devtools from production builds
55
- **Production Entry**: Separate entry point that always renders devtools for debugging production builds
56
57
Both components internally wrap the core `TanstackQueryDevtools` and `TanstackQueryDevtoolsPanel` classes from `@tanstack/query-devtools`, providing React-specific lifecycle management and context integration.
58
59
## Capabilities
60
61
### Floating Devtools Component
62
63
A toggleable floating devtools interface with customizable positioning and appearance options.
64
65
```typescript { .api }
66
/**
67
* Main floating devtools component with toggle button
68
* Returns null in production unless imported from /production entry
69
*/
70
function ReactQueryDevtools(props: DevtoolsOptions): React.ReactElement | null;
71
72
interface DevtoolsOptions {
73
/** Set to true to default devtools to open state */
74
initialIsOpen?: boolean;
75
/** Position of toggle button - defaults to 'bottom-right' */
76
buttonPosition?: DevtoolsButtonPosition;
77
/** Position of devtools panel - defaults to 'bottom' */
78
position?: DevtoolsPosition;
79
/** Custom QueryClient instance */
80
client?: QueryClient;
81
/** Custom error types for devtools display */
82
errorTypes?: Array<DevtoolsErrorType>;
83
/** CSP nonce for inline styles */
84
styleNonce?: string;
85
/** Attach styles to specific DOM element */
86
shadowDOMTarget?: ShadowRoot;
87
/** Hide disabled queries from panel */
88
hideDisabledQueries?: boolean;
89
}
90
```
91
92
**Usage Examples:**
93
94
```typescript
95
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
96
97
// Basic usage with default options
98
<ReactQueryDevtools />
99
100
// Customized positioning and initial state
101
<ReactQueryDevtools
102
initialIsOpen={true}
103
buttonPosition="top-left"
104
position="right"
105
/>
106
107
// With custom error types and CSP nonce
108
<ReactQueryDevtools
109
errorTypes={[
110
{
111
name: "CustomError",
112
initializer: (query) => new Error(`Custom error for ${query.queryKey}`)
113
}
114
]}
115
styleNonce="my-csp-nonce"
116
hideDisabledQueries={true}
117
/>
118
```
119
120
### Embedded Devtools Panel
121
122
An always-visible embedded devtools panel that integrates directly into your application layout.
123
124
```typescript { .api }
125
/**
126
* Embedded devtools panel component (always visible)
127
* Returns null in production unless imported from /production entry
128
*/
129
function ReactQueryDevtoolsPanel(props: DevtoolsPanelOptions): React.ReactElement | null;
130
131
interface DevtoolsPanelOptions {
132
/** Custom QueryClient instance */
133
client?: QueryClient;
134
/** Custom error types for devtools display */
135
errorTypes?: Array<DevtoolsErrorType>;
136
/** CSP nonce for inline styles */
137
styleNonce?: string;
138
/** Attach styles to specific DOM element */
139
shadowDOMTarget?: ShadowRoot;
140
/** Custom panel styles - defaults to { height: '500px' } */
141
style?: React.CSSProperties;
142
/** Callback when panel is closed */
143
onClose?: () => unknown;
144
/** Hide disabled queries from panel */
145
hideDisabledQueries?: boolean;
146
}
147
```
148
149
**Usage Examples:**
150
151
```typescript
152
import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools";
153
154
// Basic embedded panel
155
<ReactQueryDevtoolsPanel />
156
157
// Full-height panel with close handler
158
<ReactQueryDevtoolsPanel
159
style={{ height: "100vh" }}
160
onClose={() => console.log("Panel closed")}
161
/>
162
163
// Panel with custom dimensions and error handling
164
<ReactQueryDevtoolsPanel
165
style={{
166
height: "600px",
167
width: "100%",
168
border: "1px solid #ccc"
169
}}
170
errorTypes={customErrorTypes}
171
hideDisabledQueries={true}
172
/>
173
```
174
175
## Types
176
177
### Position Types
178
179
```typescript { .api }
180
/** Position options for the devtools toggle button */
181
type DevtoolsButtonPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'relative';
182
183
/** Position options for the devtools panel */
184
type DevtoolsPosition = 'top' | 'bottom' | 'left' | 'right';
185
```
186
187
### Error Type Definition
188
189
```typescript { .api }
190
/** Custom error type configuration for devtools display */
191
interface DevtoolsErrorType {
192
/** Name of the error type */
193
name: string;
194
/** Function to initialize the error from a query */
195
initializer: (query: Query) => Error;
196
}
197
```
198
199
### Exported Option Types
200
201
```typescript { .api }
202
/** Re-exported configuration options for ReactQueryDevtoolsPanel */
203
type DevtoolsPanelOptions = {
204
client?: QueryClient;
205
errorTypes?: Array<DevtoolsErrorType>;
206
styleNonce?: string;
207
shadowDOMTarget?: ShadowRoot;
208
style?: React.CSSProperties;
209
onClose?: () => unknown;
210
hideDisabledQueries?: boolean;
211
};
212
```
213
214
## Environment Behavior
215
216
### Development vs Production
217
218
The main entry point includes automatic production environment detection:
219
220
- **Development (`NODE_ENV === 'development'`)**: Components render normally with full functionality
221
- **Production (`NODE_ENV !== 'development'`)**: Components return `null` to prevent devtools from appearing in production builds
222
223
### Production Entry Point
224
225
For debugging production builds or when you need devtools to always render:
226
227
```typescript
228
import { ReactQueryDevtools } from "@tanstack/react-query-devtools/production";
229
// This will always render devtools regardless of NODE_ENV
230
```
231
232
## Integration Requirements
233
234
### Peer Dependencies
235
236
Required peer dependencies that must be installed separately:
237
238
- `@tanstack/react-query` (workspace:^) - Core React Query functionality
239
- `react` (^18 || ^19) - React framework
240
241
### QueryClient Context
242
243
Both components require a QueryClient to be available via React context:
244
245
```typescript
246
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
247
248
const queryClient = new QueryClient();
249
250
function App() {
251
return (
252
<QueryClientProvider client={queryClient}>
253
{/* Your app and devtools components */}
254
</QueryClientProvider>
255
);
256
}
257
```
258
259
### Custom QueryClient
260
261
You can optionally pass a custom QueryClient instance to either component:
262
263
```typescript
264
const customClient = new QueryClient({
265
defaultOptions: {
266
queries: { staleTime: 60000 }
267
}
268
});
269
270
<ReactQueryDevtools client={customClient} />
271
```
272
273
## Content Security Policy (CSP) Support
274
275
For applications using Content Security Policy with nonce-based inline styles:
276
277
```typescript
278
<ReactQueryDevtools
279
styleNonce="your-csp-nonce"
280
/>
281
282
<ReactQueryDevtoolsPanel
283
styleNonce="your-csp-nonce"
284
/>
285
```
286
287
## Shadow DOM Support
288
289
For applications using Shadow DOM, you can attach devtools styles to a specific shadow root:
290
291
```typescript
292
const shadowRoot = document.querySelector('#shadow-host').shadowRoot;
293
294
<ReactQueryDevtools
295
shadowDOMTarget={shadowRoot}
296
/>
297
```
298
299
## Common Error Patterns
300
301
### Missing QueryClient Context
302
303
If devtools fail to render, ensure QueryClientProvider wraps your components:
304
305
```typescript
306
// ❌ Missing QueryClientProvider
307
function App() {
308
return <ReactQueryDevtools />;
309
}
310
311
// ✅ Proper setup
312
function App() {
313
return (
314
<QueryClientProvider client={queryClient}>
315
<ReactQueryDevtools />
316
</QueryClientProvider>
317
);
318
}
319
```
320
321
### Production Build Issues
322
323
If devtools appear in production builds unexpectedly, check your import path:
324
325
```typescript
326
// ❌ Will not render in production
327
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
328
329
// ✅ Will always render (use only for debugging production)
330
import { ReactQueryDevtools } from "@tanstack/react-query-devtools/production";
331
```