repository·main·Indexed 19 days ago
https://github.com/tanstack/devtoolsA unified debugging toolkit for inspecting and monitoring application state and behavior in real time. It integrates with the TanStack ecosystem and supports various frameworks, including React, Solid, and Angular.
TanStack Devtools is a framework-agnostic foundation for building and managing custom developer tools. It is organized into several layers, allowing you to install only what you need based on your use case.
Thin wrappers to integrate devtools into specific frameworks:
@tanstack/react-devtools@tanstack/vue-devtools@tanstack/solid-devtools@tanstack/preact-devtools@tanstack/devtools: The devtools shell UI (built in Solid.js). It provides the plugin system, tab navigation, settings panel, and the trigger button.Used for communication between plugins and the shell:
@tanstack/devtools-event-client: A type-safe event client for building custom plugins.@tanstack/devtools-event-bus: The WebSocket/SSE transport layer connecting the client and server.@tanstack/devtools-vite: A Vite plugin that provides source inspection, console piping, enhanced logging, and automatic stripping of devtools from production builds.@tanstack/devtools-utils: Plugin factory helpers for each framework.@tanstack/devtools-ui: A shared Solid.js UI component library.@tanstack/devtools-client: Internal typed event client for core devtools operations.TanStack Devtools is a framework-agnostic toolkit designed for building custom developer tool panels. It uses a plugin system with typed event communication to provide a unified debugging experience across different frontend frameworks.
Key components include:
TanStack Devtools provides several built-in capabilities for developers:
The Preact adapter for TanStack Devtools provides utilities to integrate custom devtools panels into the TanStack Devtools ecosystem using Preact. It is functionally identical to the React adapter but uses preact JSX and preact/hooks.
@tanstack/devtools-utils/preact instead of @tanstack/devtools-utils/react.preact JSX runtime.preact/hooks.class instead of className in Preact.'dark'.TanStack Devtools uses two independent mechanisms to ensure devtools code is excluded from production bundles:
Vite Plugin Auto-Stripping: For Vite projects, the @tanstack/devtools-vite plugin uses AST-based stripping. It parses source files and removes imports from devtools packages (e.g., @tanstack/react-devtools, @tanstack/devtools) along with any associated JSX elements. This happens automatically during vite build when the mode is production.
Conditional Exports: The @tanstack/devtools core package uses Node.js conditional exports to serve different bundles. In a browser environment, it resolves to dev.js during development (including dev-only extras) and index.js for production builds.
The system relies on a typed event system for data flow between the application and the devtools panels.
Core Concepts:
structuredClone for creating snapshots to ensure data integrity and avoid issues in cross-tab scenarios.pluginId prefix in your event names; the system handles namespacing internally.Use the factory functions (createReactPlugin, createVuePlugin, etc.) when building a reusable library plugin intended for publication. They provide:
NoOpPlugin for production tree-shaking.Use manual objects when building a one-off internal devtools panel for your own application. This is simpler and avoids extra abstraction:
// Manual approach for one-off panels
{
name: 'App State',
render: (el, theme) => <MyPanel theme={theme} />,
}// Manual approach -- fine for one-off panels
{
name: 'App State',
render: (el, theme) => <MyPanel theme={theme} />,
}src/routes directory. Adding a new file to this directory automatically generates a new route.Custom plugins are built by creating event clients and panel components that interact with the TanStack Devtools shell.
Plugin Development Best Practices:
EventClient class to manage the connection lifecycle and event maps. Ensure each plugin has a unique pluginId to avoid event collisions.theme prop provided by the devtools to ensure visual consistency.TanStack Devtools allows you to create custom plugins by emitting and listening to an event bus. This is achieved using the @tanstack/devtools-event-client package. The process involves three main steps:
EventClient: Define an EventMap where keys are event suffixes and values are the payload types. Extend the EventClient class and provide a pluginId in the constructor. The pluginId is automatically prepended to all event keys.DevtoolsEventClient.emit(eventSuffix, payload) whenever a state change occurs. The eventSuffix must match a key in your EventMap.DevtoolsEventClient.on(eventSuffix, callback). The callback receives the payload.EventClient is framework-agnostic and works in vanilla JavaScript as well as React, Vue, or Angular.
// 1. Setup
type EventMap = {
'counter-state': { count: number, history: number[] }
}
class CustomEventClient extends EventClient<EventMap> {
constructor() {
super({ pluginId: 'custom-devtools' })
}
}
const DevtoolsEventClient = new CustomEventClient()
// 2. Emit
DevtoolsEventClient.emit('counter-state', { count: 1, history: [1] })
// 3. Consume
DevtoolsEventClient.on('counter-state', e => setState(e.payload))