tanstack-devtools

SKILL.md

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

npm install @tanstack/react-devtools

Basic Setup
import { TanStackDevtools } from '@tanstack/react-devtools'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools />
      {/* Your app content */}
      <MyApp />
    </QueryClientProvider>
  )
}

Built-in Plugins

Query Devtools

import { TanStackDevtools } from '@tanstack/react-devtools'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools
        plugins={[
          {
            id: 'react-query',
            name: 'React Query',
            render: () => <ReactQueryDevtoolsPanel />,
          },
        ]}
      />
      <MyApp />
    </QueryClientProvider>
  )
}

Router Devtools

import { TanStackDevtools } from '@tanstack/react-devtools'
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

function App() {
  return (
    <TanStackDevtools
      plugins={[
        {
          id: 'router',
          name: 'Router',
          render: () => <TanStackRouterDevtoolsPanel router={router} />,
        },
      ]}
    />
  )
}

Combined Setup

import { TanStackDevtools } from '@tanstack/react-devtools'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TanStackDevtools
        plugins={[
          {
            id: 'react-query',
            name: 'React Query',
            render: () => <ReactQueryDevtoolsPanel />,
          },
          {
            id: 'router',
            name: 'Router',
            render: () => <TanStackRouterDevtoolsPanel router={router} />,
          },
        ]}
      />
      <MyApp />
    </QueryClientProvider>
  )
}

AI Devtools

For debugging TanStack AI workflows:

import { TanStackDevtools } from '@tanstack/react-devtools'
import { AIDevtoolsPanel } from '@tanstack/ai-react/devtools'

function App() {
  return (
    <TanStackDevtools
      plugins={[
        {
          id: 'ai',
          name: 'AI',
          render: () => <AIDevtoolsPanel />,
        },
      ]}
    />
  )
}

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

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

Custom Plugins

import { TanStackDevtools } from '@tanstack/react-devtools'

// Custom state inspector plugin
const stateInspectorPlugin = {
  id: 'state-inspector',
  name: 'State',
  render: () => (
    <div style={{ padding: '16px' }}>
      <h3>Application State</h3>
      <pre>{JSON.stringify(appState, null, 2)}</pre>
    </div>
  ),
}

// Custom network logger plugin
const networkLoggerPlugin = {
  id: 'network-logger',
  name: 'Network',
  render: () => <NetworkLoggerPanel />,
}

function App() {
  return (
    <TanStackDevtools
      plugins={[
        stateInspectorPlugin,
        networkLoggerPlugin,
      ]}
    />
  )
}

Dynamic Plugin Registration

function App() {
  const [plugins, setPlugins] = useState<DevtoolsPlugin[]>([])

  useEffect(() => {
    // Register plugins conditionally
    const activePlugins: DevtoolsPlugin[] = []

    if (process.env.NODE_ENV === 'development') {
      activePlugins.push({
        id: 'debug',
        name: 'Debug',
        render: () => <DebugPanel />,
      })
    }

    setPlugins(activePlugins)
  }, [])

  return <TanStackDevtools plugins={plugins} />
}

Vite Plugin Integration

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackDevtools } from '@tanstack/devtools/vite'

export default defineConfig({
  plugins: [
    tanstackDevtools(),
  ],
})

Production Considerations

// Only include devtools in development
function App() {
  return (
    <>
      {process.env.NODE_ENV === 'development' && (
        <TanStackDevtools plugins={plugins} />
      )}
      <MyApp />
    </>
  )
}

// Or use lazy loading
const TanStackDevtools = lazy(() =>
  import('@tanstack/react-devtools').then((m) => ({ default: m.TanStackDevtools }))
)

Framework Support

Framework
Package
Status

React
@tanstack/react-devtools
Alpha

Solid
@tanstack/solid-devtools
Planned

Vue
@tanstack/vue-devtools
Planned

Angular
@tanstack/angular-devtools
Planned

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

Conditionally include in production - use environment checks or code splitting

Use specific plugins rather than loading all available ones

Give plugins unique IDs to prevent conflicts

Keep plugin render functions lightweight - avoid expensive computations

Use the Vite plugin for automatic setup in Vite-based projects

Combine Query + Router + AI plugins for full-stack TanStack debugging

Create domain-specific plugins for app-level state inspection

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