Documentation
DevTools Guide
Full observability into tag invalidation — see every SSE event, matched queries, tag trees, and connection health in real time.
Setup
The DevTools panel integrates with TanStack Query DevTools as a plugin — or can run standalone.
// src/integrations/tanstack-query/devtools.tsx
import { lazy } from "react"
import { queryTagsPlugin } from "@tanstack-tools/query-tags/devtools"
const TanStackQueryDevtools = lazy(() =>
import("@tanstack/react-query-devtools").then((m) => ({
default: m.ReactQueryDevtools,
}))
)
export default TanStackQueryDevtools
export { queryTagsPlugin }// In __root.tsx
import TanStackQueryDevtools, { queryTagsPlugin } from "./devtools"
// Inside your root component:
<TanStackQueryDevtools
buttonPosition="bottom-left"
plugins={[queryTagsPlugin]}
/>DevTools Tabs
The panel has five tabs, each focused on a different aspect of the invalidation system.
Tags
Browse the full tag tree. See which queries are tagged with what. Search and filter tags by name.
Timeline
Chronological log of every invalidation event. Shows tags, matched query count, and timestamp.
Dependencies
Visualize which queries depend on which tags. Trace from a tag to all queries it would invalidate.
Controls
Pause/resume invalidation processing. Queue events while paused, then release them all at once.
Connection
SSE connection health — status, reconnection attempts, last event time, scope info.
Programmatic Access
Access the debug state directly in your components with the useTagInvalidationDebugState hook.
// Access debug state programmatically
import { useTagInvalidationDebugState } from "@tanstack-tools/query-tags/react"
function MyDebugWidget() {
const { messages, isConnected, isPaused } = useTagInvalidationDebugState()
return (
<div>
<p>Events received: {messages.length}</p>
<p>Connected: {isConnected ? "Yes" : "No"}</p>
<p>Paused: {isPaused ? "Yes" : "No"}</p>
</div>
)
}FAQ
@tanstack-tools/query-tags/devtools only in development. Use dynamic import() with lazy() to ensure it's tree-shaken in production builds.Try It Live
The best way to understand the DevTools is to use them. Open the debug panel in any demo page.