Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

devtools-utils.md

365 lines10.8 KB

1---
2title: Using devtools-utils
3id: devtools-utils
4---
5​
6`@tanstack/devtools-utils` provides factory functions that simplify creating devtools plugins for each framework. Instead of manually wiring up render functions and no-op variants, these helpers produce correctly-typed plugin objects (and their production-safe no-op counterparts) from your components. Each framework has its own subpath export with an API tailored to that framework's conventions.
7​
8## Installation
9​
10```bash
11npm install @tanstack/devtools-utils
12```
13​
14## DevtoolsPanelProps
15​
16Every panel component receives a `theme` prop so the panel can match the devtools shell appearance. The interface is defined per-framework in each subpath:
17​
18```ts
19interface DevtoolsPanelProps {
20 theme?: 'light' | 'dark'
22```
23​
24> The Vue and Svelte variants additionally accept `'system'` as a theme value.
25​
26Import it from the framework-specific subpath:
27​
28```ts
29// React
30import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/react'
31​
32// Solid
33import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/solid'
34​
35// Preact
36import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'
37​
38// Vue
39import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
40​
41// Svelte
42import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/svelte'
43​
44// Angular
45import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/angular'
46```
47​
48## React
49​
50### createReactPlugin
51​
52Creates a `[Plugin, NoOpPlugin]` tuple from a React component and plugin metadata.
53​
54**Signature:**
55​
56```ts
57function createReactPlugin(options: {
58 name: string
59 id?: string
60 defaultOpen?: boolean
61 Component: (props: DevtoolsPanelProps) => JSX.Element
62}): readonly [Plugin, NoOpPlugin]
63```
64​
65**Usage:**
66​
67```tsx
68import { createReactPlugin } from '@tanstack/devtools-utils/react'
69​
70const [MyPlugin, NoOpPlugin] = createReactPlugin({
71 name: 'My Store',
72 id: 'my-store',
73 defaultOpen: false,
74 Component: ({ theme }) => <MyStorePanel theme={theme} />,
75})
76```
77​
78The returned tuple contains two factory functions:
79​
80- **`Plugin()`** -- returns a plugin object with `name`, `id`, `defaultOpen`, and a `render` function that renders your `Component` with the current theme.
81- **`NoOpPlugin()`** -- returns a plugin object with the same metadata but a `render` function that renders an empty fragment. Use this for production builds where you want to strip devtools out.
82​
83A common pattern for tree-shaking:
84​
85```tsx
86const [MyPlugin, NoOpPlugin] = createReactPlugin({ /* ... */ })
87​
88const ActivePlugin = process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
89```
90​
91### createReactPanel
92​
93For library authors shipping a class-based devtools core that exposes `mount(el, theme)` and `unmount()` methods. This factory wraps that class in a React component that handles mounting into a `div`, passing the theme, and cleaning up on unmount.
94​
95**Signature:**
96​
97```ts
98function createReactPanel<
99 TComponentProps extends DevtoolsPanelProps | undefined,
100 TCoreDevtoolsClass extends {
101 mount: (el: HTMLElement, theme: 'light' | 'dark') => void
102 unmount: () => void
103 },
104>(CoreClass: new () => TCoreDevtoolsClass): readonly [Panel, NoOpPanel]
105```
106​
107**Usage:**
108​
109```tsx
110import { createReactPanel } from '@tanstack/devtools-utils/react'
111​
112class MyDevtoolsCore {
113 mount(el: HTMLElement, theme: 'light' | 'dark') {
114 // render your devtools UI into el
115 }
116 unmount() {
117 // cleanup
118 }
120​
121const [MyPanel, NoOpPanel] = createReactPanel(MyDevtoolsCore)
122​
123// Then use the panel component inside createReactPlugin:
124const [MyPlugin, NoOpPlugin] = createReactPlugin({
125 name: 'My Store',
126 Component: MyPanel,
127})
128```
129​
130The returned `Panel` component:
131- Creates a `div` with `height: 100%` and stores a ref to it.
132- Instantiates `CoreClass` on mount and calls `core.mount(el, theme)`.
133- Calls `core.unmount()` on cleanup.
134- Re-mounts when the `theme` prop changes.
135​
136`NoOpPanel` renders an empty fragment and does nothing.
137​
138## Preact
139​
140### createPreactPlugin
141​
142Identical API to `createReactPlugin`, using Preact's JSX types. Import from `@tanstack/devtools-utils/preact`.
143​
144**Signature:**
145​
146```ts
147function createPreactPlugin(options: {
148 name: string
149 id?: string
150 defaultOpen?: boolean
151 Component: (props: DevtoolsPanelProps) => JSX.Element
152}): readonly [Plugin, NoOpPlugin]
153```
154​
155**Usage:**
156​
157```tsx
158import { createPreactPlugin } from '@tanstack/devtools-utils/preact'
159​
160const [MyPlugin, NoOpPlugin] = createPreactPlugin({
161 name: 'My Store',
162 id: 'my-store',
163 Component: ({ theme }) => <MyStorePanel theme={theme} />,
164})
165```
166​
167The return value and behavior are the same as `createReactPlugin` -- a `[Plugin, NoOpPlugin]` tuple where `Plugin` renders your component and `NoOpPlugin` renders nothing.
168​
169### createPreactPanel
170​
171Also available for Preact with the same class-based API as `createReactPanel`:
172​
173```ts
174import { createPreactPanel } from '@tanstack/devtools-utils/preact'
175​
176const [MyPanel, NoOpPanel] = createPreactPanel(MyDevtoolsCore)
177```
178​
179## Solid
180​
181### createSolidPlugin
182​
183Same option-object API as React and Preact, using Solid's JSX types. Import from `@tanstack/devtools-utils/solid`.
184​
185**Signature:**
186​
187```ts
188function createSolidPlugin(options: {
189 name: string
190 id?: string
191 defaultOpen?: boolean
192 Component: (props: DevtoolsPanelProps) => JSX.Element
193}): readonly [Plugin, NoOpPlugin]
194```
195​
196**Usage:**
197​
198```tsx
199import { createSolidPlugin } from '@tanstack/devtools-utils/solid'
200​
201const [MyPlugin, NoOpPlugin] = createSolidPlugin({
202 name: 'My Store',
203 id: 'my-store',
204 Component: (props) => <MyStorePanel theme={props.theme} />,
205})
206```
207​
208### createSolidPanel
209​
210Solid also provides a class-based panel factory. It uses `createSignal` and `onMount`/`onCleanup` instead of React hooks:
211​
212```ts
213import { createSolidPanel } from '@tanstack/devtools-utils/solid'
214​
215const [MyPanel, NoOpPanel] = createSolidPanel(MyDevtoolsCore)
216```
217​
218## Vue
219​
220### createVuePlugin
221​
222The Vue factory has a different API from the JSX-based frameworks. It takes a `name` string and a Vue `DefineComponent` as separate arguments rather than an options object.
223​
224**Signature:**
225​
226```ts
227function createVuePlugin<TComponentProps extends Record<string, any>>(
228 name: string,
229 component: DefineComponent<TComponentProps, {}, unknown>,
230): readonly [Plugin, NoOpPlugin]
231```
232​
233**Usage:**
234​
235```ts
236import { createVuePlugin } from '@tanstack/devtools-utils/vue'
237import MyStorePanel from './MyStorePanel.vue'
238​
239const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyStorePanel)
240```
241​
242The returned functions differ from the JSX-based variants:
243​
244- **`Plugin(props)`** -- returns `{ name, component, props }` where `component` is your Vue component.
245- **`NoOpPlugin(props)`** -- returns `{ name, component: Fragment, props }` where the component is Vue's built-in `Fragment` (renders nothing visible).
246​
247Both accept props that get forwarded to the component.
248​
249### createVuePanel
250​
251For class-based devtools cores, Vue provides `createVuePanel`. It creates a Vue `defineComponent` that handles mounting and unmounting the core class:
252​
253```ts
254import { createVuePanel } from '@tanstack/devtools-utils/vue'
255​
256const [MyPanel, NoOpPanel] = createVuePanel(MyDevtoolsCore)
257```
258​
259The panel component accepts `theme` and `devtoolsProps` as props. It mounts the core instance into a `div` element on `onMounted` and calls `unmount()` on `onUnmounted`.
260​
261## Svelte
262​
263### createSveltePlugin
264​
265The Svelte factory takes a `name` string and a Svelte component as separate arguments, similar to the Vue API.
266​
267**Signature:**
268​
269```ts
270function createSveltePlugin<TComponentProps extends Record<string, any>>(
271 name: string,
272 component: Component<TComponentProps>,
273): readonly [Plugin, NoOpPlugin]
274```
275​
276**Usage:**
277​
278```ts
279import { createSveltePlugin } from '@tanstack/devtools-utils/svelte'
280import MyStorePanel from './MyStorePanel.svelte'
281​
282const [MyPlugin, NoOpPlugin] = createSveltePlugin('My Store', MyStorePanel)
283```
284​
285The returned functions:
286​
287- **`Plugin(props?)`** -- returns `{ name, component, props }` where `component` is your Svelte component.
288- **`NoOpPlugin(props?)`** -- returns `{ name, component: NoOpComponent, props }` where the component renders nothing visible.
289​
290Both accept an optional `props` object that gets forwarded to the component on mount.
291​
292### createSveltePanel
293​
294For class-based devtools cores, Svelte provides `createSveltePanel`. It creates a wrapper that handles mounting and unmounting the core class:
295​
296```ts
297import { createSveltePanel } from '@tanstack/devtools-utils/svelte'
298​
299const [MyPanel, NoOpPanel] = createSveltePanel(MyDevtoolsCore)
300```
301​
302The panel accepts `theme` and `devtoolsProps` props. It creates a `div` element, mounts the core instance into it, and calls `unmount()` on cleanup.
303​
304## Angular
305​
306### createAngularPlugin
307​
308The Angular factory takes a `name` string and an Angular component class as separate arguments, similar to the Vue API.
309​
310**Signature:**
311​
312```ts
313function createAngularPlugin(
314 name: string,
315 component: Type<any>,
316): readonly [Plugin, NoOpPlugin]
317```
318​
319**Usage:**
320​
321```ts
322import { createAngularPlugin } from '@tanstack/devtools-utils/angular'
323import { MyStorePanelComponent } from './my-store-panel.component'
324​
325const [MyPlugin, NoOpPlugin] = createAngularPlugin('My Store', MyStorePanelComponent)
326```
327​
328The returned functions:
329​
330- **`Plugin(inputs?)`** -- returns `{ name, component, inputs }` where `component` is your Angular component class.
331- **`NoOpPlugin(inputs?)`** -- returns `{ name, component: NoOpComponent, inputs }` where the component is an empty standalone component (renders nothing visible).
332​
333Both accept an optional `inputs` object that gets forwarded to the component via `setInput()`.
334​
335### createAngularPanel
336​
337For class-based devtools cores, Angular provides `createAngularPanel`. It creates a standalone Angular component that handles mounting and unmounting the core class:
338​
339```ts
340import { createAngularPanel } from '@tanstack/devtools-utils/angular'
341​
342const [MyPanel, NoOpPanel] = createAngularPanel(MyDevtoolsCore)
343```
344​
345The panel component accepts `theme` and `devtoolsProps` as signal inputs. It mounts the core instance into a `div` element using `afterNextRender` and calls `unmount()` via `DestroyRef.onDestroy`.
346​
347## When to Use Factories vs Manual Plugin Objects
348​
349**Use the factories** when you are building a reusable library plugin that will be published as a package. The factories ensure:
350​
351- Consistent plugin object shape across frameworks.
352- A matching `NoOpPlugin` variant for production tree-shaking.
353- Correct typing without manual type annotations.
354​
355**Use manual plugin objects** when you are building a one-off internal devtools panel for your application. In that case, passing `name` and `render` directly to the devtools configuration is simpler and avoids the extra abstraction:
356​
357```tsx
358// Manual approach -- fine for one-off panels
360 name: 'App State',
361 render: (el, theme) => <MyPanel theme={theme} />,
363```
364​
365The factory approach becomes more valuable as you add `id`, `defaultOpen`, and need both a development and production variant of the same plugin.