Open History to see the last commit
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'
21}
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 }
119}
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
359{
360 name: 'App State',
361 render: (el, theme) => <MyPanel theme={theme} />,
362}
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.