devtools/docs/configuration.md
Alem Tuzlak cf8e67875c
feat(devtools): rainbow trigger, persist strip fold, and pane gutters (#510)
Use the rainbow palm as the default trigger mark and default triggerMode to floating.
Keep the folded plugin strip across reloads.
Lay plugin panes in rounded cards with even gutters, theme panel scrollbars, and keep resize handles on the live layout so they stay in the gap after a pane opens or a drag.
2026-08-19 18:50:38 +02:00

4 KiB

title id
Configuration configuration

Both TanStack DevTools and EventClient can be configured.

Important

All configuration is optional unless marked (required)

Devtools Component Configuration

The Devtools component has two configuration props, regardless of Frameworks these are the same.

  • config - Configuration for the devtool panel and interaction with it.
  • eventBusConfig - Configuration for the event bus.

The config object is mainly focused around user interaction with the devtools panel and accepts the following properties:

  • defaultOpen - If the devtools are open by default
{ defaultOpen: boolean }
  • hideUntilHover - Hides the TanStack devtools trigger until hovered
{ hideUntilHover: boolean }
  • position - The position of the TanStack devtools trigger (used when triggerMode is 'fixed')
{ position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right' }
  • triggerMode - How the trigger is placed. 'floating' (the default) lets you drag the trigger anywhere on screen, and throw it: it glides with momentum and springs back off the edges. 'fixed' anchors it to position. The floating spot is persisted in local storage.
{ triggerMode: 'fixed' | 'floating' }
  • panelLocation - The location of the devtools panel
{ panelLocation: 'top' | 'bottom' }
  • openHotkey - The hotkey set to open the devtools
type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift' | 'CtrlOrMeta';
type KeyboardKey = ModifierKey | (string & {});

{ openHotkey: Array<KeyboardKey> }
  • inspectHotkey - The hotkey set to open the source inspector
type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift' | 'CtrlOrMeta';
type KeyboardKey = ModifierKey | (string & {});

{ inspectHotkey: Array<KeyboardKey> }
  • requireUrlFlag - Requires a flag present in the url to enable devtools
{ requireUrlFlag: boolean }
  • triggerImage - The image used for the dev tools trigger
{ triggerImage: string }
  • urlFlag - The required flag that must be present in the url to enable devtools.
{ urlFlag: string }

The eventBusConfig is configuration for the back bone of the devtools, the EventClient, and accepts the following properties:

  • debug - Enables debug mode for the EventBus
{ debug: boolean }
  • connectToServerBus - Optional flag to indicate if the devtools server event bus is available to connect to
{ connectToServerBus: boolean }
  • port - The port at which the client connects to the devtools server event bus
{ port: number }

Put together here is an example in react:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { FormDevtools } from '@tanstack/react-form'

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

import App from './App'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />

    <TanStackDevtools
      config={{ hideUntilHover: true }}
      eventBusConfig={{ debug: true }}
      plugins={[
        {
          name: 'TanStack Form',
          render: <FormDevtools />,
          defaultOpen: true,
        },
      ]}
    />
  </StrictMode>,
)

EventClient Configuration

Configuration for the EventClient is as follows

  • pluginId (required) - The plugin identifier used by the event bus to direct events to listeners
{ pluginId: string }
  • debug - Enables debug mode for the EventClient
{ debug: boolean }

Put together the EventClient configuration looks like:

import { EventClient } from '@tanstack/devtools-event-client'

type EventMap = {
  'custom-state': { state: string }
}

class customEventClient extends EventClient<EventMap> {
  constructor() {
    super({
      debug: true,
      pluginId: 'custom-devtools',
    })
  }
}

More information about EventClient configuration can be found in our custom-plugins example