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
```