Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

devtools.md

302 lines13.3 KB

1---
2id: devtools
3title: Devtools
4---
5​
6> For Chrome, Firefox, and Edge users: Third-party browser extensions are available for debugging TanStack Query directly in browser DevTools. These provide the same functionality as the framework-specific devtools packages:
7>
8> - <img alt="Chrome logo" src="https://www.google.com/chrome/static/images/chrome-logo.svg" width="16" height="16" class="inline mr-1 not-prose" /> <a href="https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai">Devtools for Chrome</a>
9> - <img alt="Firefox logo" src="https://upload.wikimedia.org/wikipedia/commons/a/a0/Firefox_logo%2C_2019.svg" width="16" height="16" class="inline mr-1 not-prose" /> <a href="https://addons.mozilla.org/en-US/firefox/addon/tanstack-query-devtools/">Devtools for Firefox</a>
10> - <img alt="Edge logo" src="https://upload.wikimedia.org/wikipedia/commons/9/98/Microsoft_Edge_logo_%282019%29.svg" width="16" height="16" class="inline mr-1 not-prose" /> <a href="https://microsoftedge.microsoft.com/addons/detail/tanstack-query-devtools/edmdpkgkacmjopodhfolmphdenmddobj">Devtools for Edge</a>
11​
12## Enable devtools
13​
14Add the devtools package (in addition to `@tanstack/angular-query`):
15​
16```sh
17npm install @tanstack/angular-query-devtools
18```
19​
20The devtools help you debug and inspect your queries and mutations. You can enable the devtools by adding `withDevtools` to `provideTanStackQuery`.
21​
22By default, Angular Query Devtools only load in development.
23​
24```ts
25import { QueryClient, provideTanStackQuery } from '@tanstack/angular-query'
26import { withDevtools } from '@tanstack/angular-query-devtools'
27​
28export const appConfig: ApplicationConfig = {
29 providers: [provideTanStackQuery(() => new QueryClient(), withDevtools())],
31```
32​
33## Devtools in production
34​
35If you need the real implementation in production, import from the `production` entrypoint.
36​
37```ts
38import { withDevtools } from '@tanstack/angular-query-devtools/production'
39```
40​
41To control when devtools are rendered, use the `loadDevtools` option.
42​
43When omitted or set to `'auto'`, devtools are only rendered in development mode.
44​
45```ts
46import { withDevtools } from '@tanstack/angular-query-devtools'
47​
48providers: [provideTanStackQuery(() => new QueryClient(), withDevtools())]
49​
50// which is equivalent to
51providers: [
52 provideTanStackQuery(
53 () => new QueryClient(),
54 withDevtools(() => ({ loadDevtools: 'auto' })),
55 ),
57```
58​
59When setting the option to true, the devtools will be rendered in both development and production mode.
60​
61This is useful if you want to load devtools based on [Angular environment configurations](https://angular.dev/tools/cli/environments). E.g. you could set this to true when the application is running on your production build staging environment.
62​
63```ts
64// Make sure to use the production sub-path to load devtools in production builds
65import { withDevtools } from '@tanstack/angular-query-devtools/production'
66import { environment } from './environments/environment'
67​
68providers: [
69 provideTanStackQuery(
70 () => new QueryClient(),
71 withDevtools(() => ({ loadDevtools: environment.loadDevtools })),
72 ),
74```
75​
76When setting the option to false, the devtools will not be rendered.
77​
78```ts
79providers: [
80 provideTanStackQuery(
81 () => new QueryClient(),
82 withDevtools(() => ({ loadDevtools: false })),
83 ),
85```
86​
87### Webpack file replacements
88​
89Some webpack-based Angular builders do not apply package export conditions when
90they bundle application code. Use the explicit `production` and `stub`
91entrypoints with Angular CLI file replacements to keep the devtools dependency
92out of production bundles.
93​
94Create an application-level import that can be replaced:
95​
96```ts
97// src/app/query-devtools.ts
98export { withDevtools } from '@tanstack/angular-query-devtools/production'
99```
100​
101```ts
102// src/app/query-devtools.stub.ts
103export { withDevtools } from '@tanstack/angular-query-devtools/stub'
104```
105​
106Import the application-level module from your config:
107​
108```ts
109import { withDevtools } from './query-devtools'
110```
111​
112Then configure the production build:
113​
114```json
116 "configurations": {
117 "production": {
118 "fileReplacements": [
119 {
120 "replace": "src/app/query-devtools.ts",
121 "with": "src/app/query-devtools.stub.ts"
122 }
123 ]
124 }
125 }
127```
128​
129The same pattern is available for the [embedded panel](#embedded-mode):
130`@tanstack/angular-query-devtools/devtools-panel/production` and
131`@tanstack/angular-query-devtools/devtools-panel/stub`.
132​
133## Reactive options
134​
135Mutable options can be Angular signals. For example, a signal derived from a keyboard shortcut can show devtools on demand:
136​
137```ts
138import { Injectable, isDevMode } from '@angular/core'
139import { toSignal } from '@angular/core/rxjs-interop'
140import { fromEvent, map, scan } from 'rxjs'
141​
142@Injectable({ providedIn: 'root' })
143export class DevtoolsOptionsManager {
144 loadDevtools = toSignal(
145 fromEvent<KeyboardEvent>(document, 'keydown').pipe(
146 map(
147 (event): boolean =>
148 event.metaKey && event.ctrlKey && event.shiftKey && event.key === 'D',
149 ),
150 scan((acc, curr) => acc || curr, isDevMode()),
151 ),
152 {
153 initialValue: isDevMode(),
154 },
155 )
157```
158​
159The callback runs once in an Angular injection context, so it can call
160`inject()`. Return signals as option values to update them reactively:
161​
162```ts
163// ...
164// πŸ‘‡ Import from the production sub-path to make devtools available in production builds
165import { inject } from '@angular/core'
166import { withDevtools } from '@tanstack/angular-query-devtools/production'
167​
168export const appConfig: ApplicationConfig = {
169 providers: [
170 provideHttpClient(),
171 provideTanStackQuery(
172 () => new QueryClient(),
173 withDevtools(() => ({
174 loadDevtools: inject(DevtoolsOptionsManager).loadDevtools,
175 })),
176 ),
177 ],
179```
180​
181### Options returned from the callback
182​
183`loadDevtools`, `client`, `position`, `errorTypes`, `buttonPosition`,
184`initialIsOpen`, and `theme` accept either their documented static value or a
185signal containing that value.
186​
187`styleNonce`, `shadowDOMTarget`, `trustedTypesPolicy`, and `hideDisabledQueries`
188are construction-time options and do not accept signals.
189​
190- `loadDevtools?: 'auto' | boolean`
191 - Omit or `'auto'`: load devtools only in development mode.
192 - Use this to control whether devtools load when using the `/production` import.
193- `initialIsOpen?: Boolean`
194 - Set this to `true` if you want the tools to default to being open
195- `buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"`
196 - Defaults to `bottom-right`
197 - The position of the TanStack logo to open and close the devtools panel
198 - If `relative`, the button is placed in the location that you render the devtools.
199- `position?: "top" | "bottom" | "left" | "right"`
200 - Defaults to `bottom`
201 - The position of the Angular Query devtools panel
202- `client?: QueryClient`,
203 - Use this to use a custom QueryClient. Otherwise, the QueryClient provided through `provideTanStackQuery` will be injected.
204- `errorTypes?: { name: string; initializer: (query: Query) => TError}[]`
205 - Use this to predefine some errors that can be triggered on your queries. Initializer will be called (with the specific query) when that error is toggled on from the UI. It must return an Error.
206- `styleNonce?: string`
207 - Deprecated. The devtools no longer add a `<style>` element, so they need no nonce. This option does nothing.
208- `shadowDOMTarget?: ShadowRoot`
209 - The shadow root to add the devtools styles to. By default, the styles are added to the shadow root the devtools render in, or to the document when they do not render in a shadow root.
210- `trustedTypesPolicy?: { createHTML: (html: string) => unknown }`
211 - The Trusted Types policy the devtools use to create their HTML templates. Pass one when your page enforces `require-trusted-types-for 'script'`. The devtools only pass it their own markup, so a policy that returns its input is enough, for example `trustedTypes.createPolicy('devtools', { createHTML: (html) => html })`.
212- `hideDisabledQueries?: boolean`
213 - Defaults to `false`.
214 - Set this to true to hide disabled queries from the devtools panel.
215- `theme?: "light" | "dark" | "system"`
216 - Defaults to the theme selected in the devtools Settings menu, or `system` if none is selected.
217 - Sets the theme of the devtools panel, overriding the Settings menu selection.
218​
219## Embedded Mode
220​
221Embedded mode will show the development tools as a fixed element in your application, so you can use our panel in your own development tools.
222​
223Use `injectDevtoolsPanel` to render the devtools panel inside an element of your component. Like `withDevtools`, it is only included in development mode bundles. To use it in production builds, import it from `@tanstack/angular-query-devtools/devtools-panel/production`.
224​
225```angular-ts
226import { Component, signal, viewChild } from '@angular/core'
227import { injectDevtoolsPanel } from '@tanstack/angular-query-devtools/devtools-panel'
228import type { ElementRef } from '@angular/core'
229​
230@Component({
231 selector: 'app-root',
232 template: `
233 <button type="button" (click)="isOpen.set(!isOpen())">
234 {{ isOpen() ? 'Close' : 'Open' }} the devtools panel
235 </button>
236 @if (isOpen()) {
237 <div #div style="height: 500px"></div>
238 }
239 `,
240})
241export class AppComponent {
242 readonly isOpen = signal(false)
243 readonly divEl = viewChild<ElementRef>('div')
244​
245 readonly devtools = injectDevtoolsPanel(() => ({
246 hostElement: this.divEl(),
247 onClose: () => this.isOpen.set(false),
248 }))
250```
251​
252`injectDevtoolsPanel` must be called in an injection context. To create the panel later, for example after lazy loading the entry point, wrap the call in [`runInInjectionContext`](https://angular.dev/api/core/runInInjectionContext). It returns a `DevtoolsPanelRef`; call its `destroy()` to remove the panel before the injector that created it is destroyed.
253​
254See the [devtools panel example](./examples/devtools-panel-angular-router) for both variants.
255​
256### Options
257​
258The callback is reactive: `hostElement`, `client`, `errorTypes`, `onClose`, and `theme` are applied whenever a signal read in the callback changes.
259​
260`styleNonce`, `shadowDOMTarget`, `trustedTypesPolicy`, and `hideDisabledQueries`
261are construction-time options, read when the panel is created.
262​
263- `hostElement?: ElementRef | null`
264 - The element to render the devtools panel in. When it is `undefined` or `null`, the devtools panel is not created, or is destroyed if it exists.
265- `onClose?: () => unknown`
266 - Callback function that is called when the devtools panel is closed
267- `client?: QueryClient`,
268 - Use this to use a custom QueryClient. Otherwise, the QueryClient provided through `provideTanStackQuery` will be injected.
269- `errorTypes?: { name: string; initializer: (query: Query) => TError}[]`
270 - Use this to predefine some errors that can be triggered on your queries. Initializer will be called (with the specific query) when that error is toggled on from the UI. It must return an Error.
271- `styleNonce?: string`
272 - Deprecated. The devtools no longer add a `<style>` element, so they need no nonce. This option does nothing.
273- `shadowDOMTarget?: ShadowRoot`
274 - The shadow root to add the devtools styles to. By default, the styles are added to the shadow root the devtools render in, or to the document when they do not render in a shadow root.
275- `trustedTypesPolicy?: { createHTML: (html: string) => unknown }`
276 - The Trusted Types policy the devtools use to create their HTML templates. Pass one when your page enforces `require-trusted-types-for 'script'`. The devtools only pass it their own markup, so a policy that returns its input is enough, for example `trustedTypes.createPolicy('devtools', { createHTML: (html) => html })`.
277- `hideDisabledQueries?: boolean`
278 - Defaults to `false`.
279 - Set this to true to hide disabled queries from the devtools panel.
280- `theme?: "light" | "dark" | "system"`
281 - Defaults to the theme selected in the devtools Settings menu, or `system` if none is selected.
282 - Sets the theme of the devtools panel, overriding the Settings menu selection.
283​
284## Filter queries and mutations
285​
286The **Filter** input above the query and mutation lists uses the **Key** scope by default. Select the scope button inside the input to switch between **Key**, **Data**, and **All**:
287​
288- **Key** matches the query hash, or the mutation key and submission time.
289- **Data** matches the query data, or the mutation variables or data, the same way **Search data** does below.
290- **All** matches either.
291​
292The selected scope is remembered across reloads, like the other filter settings.
293​
294## Search query and mutation data
295​
296Select a query or mutation and use **Search data** in its Data Explorer to search nested property names and primitive values. Search uses case-insensitive text matching and treats special characters as plain text.
297​
298Matching text is highlighted. Matching editable values have a highlighted input. The explorer opens matching branches and the first matching page in each paginated collection. Other pages with matches are highlighted so you can open them. You can still inspect other rows and edit query data.
299​
300The Data Explorer highlights up to 1,000 matches at a time.
301​
302Select **Clear** or press **Escape** in the search field to restore your manual expansion. Selecting another query or mutation clears the search, unless the filter scope is **Data** or **All**: then the search starts with the filter text. For a mutation, it starts only in the variables or data that match the filter.