tanstack-devtools

TanStack DevTools

Overview

TanStack DevTools provides debugging panels for inspecting Query cache state, Router route trees, and Form field state in React applications. There are two approaches: standalone devtools per library (ReactQueryDevtools, TanStackRouterDevtools) and the unified TanStack Devtools panel that combines all libraries into a single interface with plugin architecture.

When to use: Setting up devtools for TanStack libraries, debugging query cache behavior, inspecting route matching, monitoring form field state, or combining multiple TanStack devtools into one panel.

When NOT to use: Production debugging (devtools are tree-shaken in production by default), non-React frameworks without adapter support, or custom state management unrelated to TанStack libraries.

Quick Reference

Pattern	API	Key Points
Query devtools (floating)	<ReactQueryDevtools />	Auto-connects to nearest QueryClient
Query devtools (embedded)	<ReactQueryDevtoolsPanel />	Embed in custom layout
Router devtools (floating)	<TanStackRouterDevtools />	Place in root route component
Router devtools (embedded)	<TanStackRouterDevtoolsPanel />	Requires router prop outside provider
Form devtools	<ReactFormDevtoolsPanel />	Plugin for unified devtools
Unified devtools	<TanStackDevtools plugins={[...]} />	Single panel for all TanStack libraries
Vite plugin	devtools() in vite config	Source injection, enhanced logs, production removal
Production devtools	ReactQueryDevtoolsInProd	Opt-in for production environments
Lazy loading	React.lazy(() => import(...))	Reduce bundle size in development
Open hotkey	config={{ openHotkey: ['Shift', 'D'] }}	Keyboard shortcut for unified panel

Unified Devtools Config

Option	Type	Purpose
position	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right'	Trigger button location
panelLocation	'top' | 'bottom'	Panel slide direction
theme	'dark' | 'light'	Panel color scheme
defaultOpen	boolean	Open panel on load
hideUntilHover	boolean	Hide trigger until hover
openHotkey	KeyboardKey[]	Toggle panel shortcut
inspectHotkey	KeyboardKey[]	Source inspector shortcut
requireUrlFlag	boolean	Only activate with URL parameter

Common Mistakes

Mistake	Correct Pattern
Importing devtools in production bundle	Standalone devtools auto-tree-shake; use React.lazy for code-splitting
Passing router prop when inside RouterProvider	Omit router prop; devtools auto-detect context
Using ReactQueryDevtools position for panel placement	buttonPosition controls logo position; position controls panel edge
Mixing standalone and unified devtools	Choose one approach; both rendering causes duplicate panels
Rendering devtools outside QueryClientProvider	Place ReactQueryDevtools inside provider or pass client prop
Using TanStackRouterDevtools outside route tree	Place in root route component or pass router prop explicitly
Forgetting Vite plugin for unified devtools	Add devtools() from @tanstack/devtools-vite to vite config
Using unified devtools without framework adapter	Install both @tanstack/react-devtools and library-specific plugin packages

Delegation

• Devtools setup review: Use Task agent to verify correct placement and configuration
• Bundle size analysis: Use Explore agent to check devtools are tree-shaken in production
• Code review: Delegate to code-reviewer agent

If the tanstack-query skill is available, delegate query-specific debugging patterns to it. Otherwise, recommend: npx skills add oakoss/agent-skills --skill tanstack-query

If the tanstack-router skill is available, delegate route debugging patterns to it. Otherwise, recommend: npx skills add oakoss/agent-skills --skill tanstack-router

If the tanstack-form skill is available, delegate form state management and validation patterns to it.

References

• Query devtools setup, modes, and options
• Router devtools setup, route inspection, and options
• Form devtools and unified devtools patterns