Overview

TanStack Devtools provides a unified debugging interface that consolidates devtools for TanStack Query, Router, and other libraries into a single panel. It features a framework-agnostic plugin architecture, real-time state inspection, and support for custom plugins. Built with Solid.js for lightweight performance.

React: @tanstack/react-devtools Core: @tanstack/devtools Status: Alpha

Installation

bash
1npm install @tanstack/react-devtools

Basic Setup

tsx
1import { TanStackDevtools } from '@tanstack/react-devtools'
2import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
3
4const queryClient = new QueryClient()
5
6function App() {
7  return (
8    <QueryClientProvider client={queryClient}>
9      <TanStackDevtools />
10      {/* Your app content */}
11      <MyApp />
12    </QueryClientProvider>
13  )
14}

Built-in Plugins

Query Devtools

tsx
1import { TanStackDevtools } from '@tanstack/react-devtools'
2import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
3
4function App() {
5  return (
6    <QueryClientProvider client={queryClient}>
7      <TanStackDevtools
8        plugins={[
9          {
10            id: 'react-query',
11            name: 'React Query',
12            render: () => <ReactQueryDevtoolsPanel />,
13          },
14        ]}
15      />
16      <MyApp />
17    </QueryClientProvider>
18  )
19}

Router Devtools

tsx
1import { TanStackDevtools } from '@tanstack/react-devtools'
2import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
3
4function App() {
5  return (
6    <TanStackDevtools
7      plugins={[
8        {
9          id: 'router',
10          name: 'Router',
11          render: () => <TanStackRouterDevtoolsPanel router={router} />,
12        },
13      ]}
14    />
15  )
16}

Combined Setup

tsx
1import { TanStackDevtools } from '@tanstack/react-devtools'
2import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
3import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
4
5function App() {
6  return (
7    <QueryClientProvider client={queryClient}>
8      <TanStackDevtools
9        plugins={[
10          {
11            id: 'react-query',
12            name: 'React Query',
13            render: () => <ReactQueryDevtoolsPanel />,
14          },
15          {
16            id: 'router',
17            name: 'Router',
18            render: () => <TanStackRouterDevtoolsPanel router={router} />,
19          },
20        ]}
21      />
22      <MyApp />
23    </QueryClientProvider>
24  )
25}

AI Devtools

For debugging TanStack AI workflows:

tsx
1import { TanStackDevtools } from '@tanstack/react-devtools'
2import { AIDevtoolsPanel } from '@tanstack/ai-react/devtools'
3
4function App() {
5  return (
6    <TanStackDevtools
7      plugins={[
8        {
9          id: 'ai',
10          name: 'AI',
11          render: () => <AIDevtoolsPanel />,
12        },
13      ]}
14    />
15  )
16}

AI Devtools features:

• Message Inspector - View full conversation history with metadata
• Token Usage - Track input/output tokens and costs per request
• Streaming Visualization - Real-time view of streaming chunks
• Tool Call Debugging - Inspect tool calls, parameters, and results
• Thinking/Reasoning Viewer - Debug reasoning tokens from thinking models
• Adapter Switching - Test different providers in development

Plugin System

Plugin Interface

typescript
1interface DevtoolsPlugin {
2  id: string          // Unique identifier
3  name: string        // Display name in the devtools panel
4  render: () => JSX.Element  // React component to render
5}

Custom Plugins

tsx
1import { TanStackDevtools } from '@tanstack/react-devtools'
2
3// Custom state inspector plugin
4const stateInspectorPlugin = {
5  id: 'state-inspector',
6  name: 'State',
7  render: () => (
8    <div style={{ padding: '16px' }}>
9      <h3>Application State</h3>
10      <pre>{JSON.stringify(appState, null, 2)}</pre>
11    </div>
12  ),
13}
14
15// Custom network logger plugin
16const networkLoggerPlugin = {
17  id: 'network-logger',
18  name: 'Network',
19  render: () => <NetworkLoggerPanel />,
20}
21
22function App() {
23  return (
24    <TanStackDevtools
25      plugins={[
26        stateInspectorPlugin,
27        networkLoggerPlugin,
28      ]}
29    />
30  )
31}

Dynamic Plugin Registration

tsx
1function App() {
2  const [plugins, setPlugins] = useState<DevtoolsPlugin[]>([])
3
4  useEffect(() => {
5    // Register plugins conditionally
6    const activePlugins: DevtoolsPlugin[] = []
7
8    if (process.env.NODE_ENV === 'development') {
9      activePlugins.push({
10        id: 'debug',
11        name: 'Debug',
12        render: () => <DebugPanel />,
13      })
14    }
15
16    setPlugins(activePlugins)
17  }, [])
18
19  return <TanStackDevtools plugins={plugins} />
20}

Vite Plugin Integration

typescript
1// vite.config.ts
2import { defineConfig } from 'vite'
3import { tanstackDevtools } from '@tanstack/devtools/vite'
4
5export default defineConfig({
6  plugins: [
7    tanstackDevtools(),
8  ],
9})

Production Considerations

tsx
1// Only include devtools in development
2function App() {
3  return (
4    <>
5      {process.env.NODE_ENV === 'development' && (
6        <TanStackDevtools plugins={plugins} />
7      )}
8      <MyApp />
9    </>
10  )
11}
12
13// Or use lazy loading
14const TanStackDevtools = lazy(() =>
15  import('@tanstack/react-devtools').then((m) => ({ default: m.TanStackDevtools }))
16)

Framework Support

Features

• Unified Panel - Single interface for all TanStack debugging
• Real-time Updates - Live monitoring of state changes
• Plugin Architecture - Extensible with custom and third-party plugins
• Built-in Plugins - Query, Router, and AI devtools panels
• Lightweight - Built with Solid.js for minimal overhead
• Type-safe - Full TypeScript support for plugin definitions
• Framework-agnostic Core - Plugin logic works across frameworks

Best Practices

1. Conditionally include in production - use environment checks or code splitting
2. Use specific plugins rather than loading all available ones
3. Give plugins unique IDs to prevent conflicts
4. Keep plugin render functions lightweight - avoid expensive computations
5. Use the Vite plugin for automatic setup in Vite-based projects
6. Combine Query + Router + AI plugins for full-stack TanStack debugging
7. Create domain-specific plugins for app-level state inspection
8. Use AI devtools when debugging streaming, tool calls, or token usage

Common Pitfalls

• Including devtools in production builds without tree-shaking
• Using duplicate plugin IDs (causes rendering conflicts)
• Heavy render functions in plugins (slows down the devtools panel)
• Forgetting to wrap with QueryClientProvider when using Query plugin
• Not passing the router instance to Router devtools panel