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

Unified Devtools Config

Common Mistakes

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

Form Devtools and Unified Panel

Form Devtools

TanStack Form devtools are available through the unified TanStack Devtools panel as a plugin. There is no standalone floating component for form devtools.

Installation

pnpm add @tanstack/react-devtools @tanstack/react-form-devtools

Both the unified devtools adapter and the form-specific plugin package are required.

Basic Setup

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

function App() {
  return (
    <>
      <YourApp />
      <TanStackDevtools
        plugins={[
          {
            id: 'tanstack-form',
            name: 'TanStack Form',
            render: <ReactFormDevtoolsPanel />,
            defaultOpen: true,
          },
        ]}
      />
    </>
  );
}

Unified TanStack Devtools

The unified devtools panel combines Query, Router, and Form devtools into a single interface. It replaces multiple floating panels with one centralized tool.

Installation

pnpm add @tanstack/react-devtools @tanstack/react-query-devtools @tanstack/react-router-devtools @tanstack/react-form-devtools

Install the core adapter and each library-specific plugin you need.

Full Setup with All Plugins

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

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
      <TanStackDevtools
        plugins={[
          {
            id: 'tanstack-query',
            name: 'TanStack Query',
            render: <ReactQueryDevtoolsPanel />,
            defaultOpen: true,
          },
          {
            id: 'tanstack-router',
            name: 'TanStack Router',
            render: <TanStackRouterDevtoolsPanel router={router} />,
          },
          {
            id: 'tanstack-form',
            name: 'TanStack Form',
            render: <ReactFormDevtoolsPanel />,
          },
        ]}
      />
    </QueryClientProvider>
  );
}

Config Options

<TanStackDevtools
  config={{
    position: 'bottom-right',
    panelLocation: 'bottom',
    theme: 'dark',
    defaultOpen: false,
    hideUntilHover: false,
    openHotkey: ['Shift', 'D'],
    inspectHotkey: ['Shift', 'I'],
    requireUrlFlag: false,
    urlFlag: 'devtools',
  }}
  eventBusConfig={{
    debug: false,
    connectToServerBus: true,
    port: 42069,
  }}
  plugins={[...]}
/>

Config Reference

Event Bus Config

Vite Plugin

The @tanstack/devtools-vite plugin enhances the development experience with source injection, enhanced logging, and automatic production removal.

import { defineConfig } from 'vite';
import { devtools } from '@tanstack/devtools-vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    devtools({
      removeDevtoolsOnBuild: true,
      logging: true,
      enhancedLogs: { enabled: true },
      injectSource: {
        enabled: true,
        ignore: {
          files: [/node_modules/, /\.test\.(ts|tsx)$/],
          components: [/^Internal/, /^Private/],
        },
      },
      eventBusConfig: {
        enabled: true,
        port: 42069,
      },
    }),
    react(),
  ],
});

Vite Plugin Options

Next.js Considerations

When using unified devtools in Next.js, wrap the devtools component in a client component to avoid server-side rendering errors:

'use client';

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

export function DevtoolsProvider() {
  return (
    <TanStackDevtools
      plugins={[
        {
          id: 'tanstack-query',
          name: 'TanStack Query',
          render: <ReactQueryDevtoolsPanel />,
        },
      ]}
    />
  );
}

Then render <DevtoolsProvider /> in your root layout.

Query Devtools

Installation

pnpm add @tanstack/react-query-devtools

The package is a separate install from @tanstack/react-query. It is automatically tree-shaken from production builds when imported from the default entry point.

Floating Mode

Floating mode renders a toggle button fixed to the screen corner. Panel state persists in localStorage across reloads.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

Floating Mode Props

Embedded Mode

Embedded mode renders the panel inline as a regular component. Use ReactQueryDevtoolsPanel for custom layouts or dashboards.

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

function DebugPanel() {
  const [isOpen, setIsOpen] = useState(true);

  if (!isOpen) return null;

  return (
    <div style={{ height: 300 }}>
      <ReactQueryDevtoolsPanel
        style={{ height: '100%' }}
        onClose={() => setIsOpen(false)}
      />
    </div>
  );
}

Embedded Mode Props

Production Builds

By default, ReactQueryDevtools is excluded from production bundles via process.env.NODE_ENV checks. To opt in to production devtools, use the production export:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools/production';

ReactQueryDevtoolsPanel also has a /production export for embedded mode in production environments.

Lazy Loading

Reduce development bundle impact by lazy-loading devtools:

import { lazy, Suspense } from 'react';

const ReactQueryDevtools = lazy(() =>
  import('@tanstack/react-query-devtools').then((mod) => ({
    default: mod.ReactQueryDevtools,
  })),
);

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <Suspense fallback={null}>
        <ReactQueryDevtools />
      </Suspense>
    </QueryClientProvider>
  );
}

Devtools Features

The query devtools panel provides:

• Query list: All cached queries with status indicators (fresh, stale, inactive, fetching)
• Query detail: Selected query data, metadata, and timing information
• Cache actions: Manually refetch, invalidate, reset, or remove individual queries
• Error simulation: Trigger predefined errors on queries via the errorTypes prop
• Filter and sort: Search queries by key and sort by status, last updated, or key hash

Integration with Unified Devtools

Query devtools can also run as a plugin in the unified TanStack Devtools panel. See the form devtools and unified patterns reference for the plugin approach.

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

<TanStackDevtools
  plugins={[
    {
      id: 'tanstack-query',
      name: 'TanStack Query',
      render: <ReactQueryDevtoolsPanel />,
    },
  ]}
/>;

Router Devtools

Installation

pnpm add @tanstack/react-router-devtools

The package is separate from @tanstack/react-router. Devtools are automatically excluded from production bundles by default.

Floating Mode

Place TanStackRouterDevtools inside a route component (typically the root route) for automatic router detection via context. Panel toggle state persists in localStorage.

Inside Root Route (Recommended)

import { createRootRoute, Outlet } from '@tanstack/react-router';
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools';

export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
});

Outside RouterProvider

When rendering outside the provider, pass the router instance explicitly:

import { RouterProvider, createRouter } from '@tanstack/react-router';
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools';

const router = createRouter({ routeTree });

function App() {
  return (
    <>
      <RouterProvider router={router} />
      <TanStackRouterDevtools router={router} />
    </>
  );
}

Floating Mode Props

Embedded Mode

Use TanStackRouterDevtoolsPanel for inline rendering in custom layouts:

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

function RouterDebugPanel({ router }: { router: Router }) {
  const [isOpen, setIsOpen] = useState(true);

  return (
    <div style={{ height: 400 }}>
      <TanStackRouterDevtoolsPanel
        router={router}
        isOpen={isOpen}
        setIsOpen={setIsOpen}
        style={{ height: '100%' }}
      />
    </div>
  );
}

Embedded Mode Props

Production Builds

By default, TanStackRouterDevtools is excluded from production bundles. To enable devtools in production, import the production variant:

import { TanStackRouterDevtoolsInProd } from '@tanstack/react-router-devtools';

TanStackRouterDevtoolsInProd accepts the same props as TanStackRouterDevtools.

Lazy Loading

Code-split devtools to keep them out of the initial bundle:

import { lazy, Suspense } from 'react';

const TanStackRouterDevtools = lazy(() =>
  import('@tanstack/react-router-devtools').then((mod) => ({
    default: mod.TanStackRouterDevtools,
  })),
);

export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <Suspense fallback={null}>
        <TanStackRouterDevtools />
      </Suspense>
    </>
  ),
});

Devtools Features

The router devtools panel provides:

• Route tree visualization: Full route hierarchy with active route highlighting
• Match inspection: Current route matches with params, search params, and loader data
• Route timing: Load and pending timing for each matched route
• Search param viewer: Parsed and serialized search parameters
• Navigation history: Recent navigations with details

Integration with Unified Devtools

Router devtools can run as a plugin in the unified TanStack Devtools panel:

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

<TanStackDevtools
  plugins={[
    {
      id: 'tanstack-router',
      name: 'TanStack Router',
      render: <TanStackRouterDevtoolsPanel router={router} />,
    },
  ]}
/>;

When using the unified panel, pass the router prop explicitly to the panel component since it renders outside the RouterProvider context.