Open History to see the last commit
1---
2title: Plugin Lifecycle
3id: plugin-lifecycle
4---
5β
6Every TanStack Devtools plugin follows a well-defined lifecycle: it is registered, mounted into a DOM container, rendered when activated, and cleaned up when the devtools unmount. This page walks through each stage in detail.
7β
8## Plugin Interface
9β
10All plugins implement the `TanStackDevtoolsPlugin` interface, which is the low-level contract between a plugin and the devtools core. Framework adapters (React, Vue, Solid, Preact) wrap this interface so you can work with familiar components, but under the hood every plugin is reduced to these fields:
11β
12```ts
13interface TanStackDevtoolsPlugin {
14 id?: string
15 name: string | ((el: HTMLHeadingElement, theme: 'dark' | 'light') => void)
16 render: (el: HTMLDivElement, theme: 'dark' | 'light') => void
17 destroy?: (pluginId: string) => void
18 defaultOpen?: boolean
19}
20```
21β
22### `id` (optional)
23β
24A unique identifier for the plugin. If you omit it, the core generates one from the `name` string (lowercased, spaces replaced with dashes, suffixed with the plugin's index). Providing an explicit `id` is useful when you need a stable identifier across page reloads - for example, to persist which plugins the user had open.
25β
26### `name` (required)
27β
28Displayed as the tab title in the sidebar. This can be:
29β
30- **A plain string** - rendered as text inside an `<h3>` element.
31- **A function** - receives the heading element (`HTMLHeadingElement`) and the current theme (`'dark' | 'light'`). You can render anything into the heading, such as an icon next to the name or a fully custom title.
32β
33```ts
34// Simple string name
35{ name: 'My Plugin', render: (el) => { /* ... */ } }
36β
37// Custom title via function
38{
39 name: (el, theme) => {
40 el.innerHTML = `<span style="color: ${theme === 'dark' ? '#fff' : '#000'}">My Plugin</span>`
41 },
42 render: (el) => { /* ... */ }
43}
44```
45β
46### `render` (required)
47β
48The main rendering function. It receives a `<div>` container element and the current theme. Your job is to render your plugin UI into this container using whatever approach you prefer - raw DOM manipulation, a framework portal, or anything else.
49β
50```ts
51render: (el, theme) => {
52 el.innerHTML = `<div class="${theme}">Hello from my plugin!</div>`
53}
54```
55β
56The `render` function is called:
57β
581. When the plugin's tab is first activated (clicked or opened by default).
592. When the theme changes, so your UI can adapt.
60β
61### `destroy` (optional)
62β
63Called when the plugin is removed from the active set (e.g., the user deactivates the tab) or when the devtools unmount entirely. It receives the `pluginId` as its argument. Use this for cleanup - cancelling timers, closing WebSocket connections, removing event listeners, etc.
64β
65Most plugins don't need to implement `destroy` because framework adapters handle cleanup automatically.
66β
67### `defaultOpen` (optional)
68β
69When set to `true`, the plugin's panel will open automatically when the devtools first load and no user preferences exist in localStorage. At most 3 plugins can be open simultaneously, so if more than 3 specify `defaultOpen: true`, only the first 3 are opened.
70β
71This setting does **not** override saved user preferences. Once a user has interacted with the devtools and their active-plugin selection is persisted, `defaultOpen` has no effect.
72β
73If only a single plugin is registered, it opens automatically regardless of `defaultOpen`.
74β
75## Mount Sequence
76β
77Here is what happens when you provide plugins to the devtools:
78β
791. **Initialization** - `TanStackDevtoolsCore` is instantiated with a `plugins` array. Each plugin is assigned an `id` if one is not already provided.
80β
812. **DOM containers are created** - The core's Solid-based UI creates two DOM elements per plugin:
82 - A content container: `<div id="plugin-container-{pluginId}">` where the plugin renders its UI.
83 - A title container: `<h3 id="plugin-title-container-{pluginId}">` where the plugin's name is rendered.
84β
853. **Title rendering** - For each plugin, the core checks if `name` is a string or function. If it's a string, the text is set directly on the heading element. If it's a function, the function is called with the heading element and current theme.
86β
874. **Plugin activation** - When the user clicks a plugin's tab (or the plugin is auto-opened via `defaultOpen`), the plugin is added to the `activePlugins` list. The core then calls `plugin.render(container, theme)` with the content `<div>` and the current theme.
88β
895. **Rendering** - The container is a regular `<div>` element. Your plugin can render anything into it - DOM nodes, a framework component tree via portals, a canvas, an iframe, etc.
90β
916. **Theme changes** - When the user toggles the theme in settings, `render` is called again with the new theme value. Your plugin should update its appearance accordingly.
92β
93```mermaid
94flowchart TD
95 A["User opens devtools"] --> B["TanStackDevtoolsCore created<br/>with plugins array"]
96 B --> C["Solid UI renders sidebar<br/>tabs and containers"]
97 C --> D["<h3 id='plugin-title-container-{id}'><br/>created per plugin"]
98 C --> E["<div id='plugin-container-{id}'><br/>created per active plugin"]
99 D --> F["plugin.name<br/><i>string set or function called</i>"]
100 E --> G["plugin.render(div, theme)<br/><i>called with container + theme</i>"]
101```
102β
103## Framework Adapter Pattern
104β
105You rarely interact with the raw `TanStackDevtoolsPlugin` interface directly. Instead, each framework adapter converts your familiar component model into the DOM-based plugin contract.
106β
107### React / Preact
108β
109The React adapter takes your JSX element and uses `createPortal` to render it into the plugin's container element:
110β
111```tsx
112// What you write:
113<TanStackDevtools
114 plugins={[{
115 name: 'My Plugin',
116 render: <MyPluginComponent />,
117 }]}
118/>
119β
120// What happens internally:
121// The adapter's render function calls:
122// createPortal(<MyPluginComponent />, containerElement)
123```
124β
125Your React component runs in its normal React tree with full access to hooks, context, state management, etc. It just renders into a different DOM location via the portal.
126β
127### Solid
128β
129The Solid adapter uses Solid's `<Portal>` component to mount your JSX into the container:
130β
131```tsx
132// What you write:
133<TanStackDevtools
134 plugins={[{
135 name: 'My Plugin',
136 render: <MyPluginComponent />,
137 }]}
138/>
139β
140// What happens internally:
141// The adapter wraps your component in:
142// <Portal mount={containerElement}>{yourComponent}</Portal>
143```
144β
145Since the devtools core is itself built in Solid, this is the most native integration. Your component runs inside the same Solid reactive system as the devtools shell.
146β
147### Vue
148β
149The Vue adapter uses `<Teleport>` to render your Vue component into the container:
150β
151```vue
152<!-- What you write: -->
153<TanStackDevtools
154 :plugins="[{
155 name: 'My Plugin',
156 component: MyPluginComponent,
157 props: { someProp: 'value' },
158 }]"
159/>
160β
161<!-- What happens internally: -->
162<!-- The adapter renders: -->
163<Teleport :to="'#plugin-container-' + pluginId">
164 <component :is="plugin.component" v-bind="plugin.props" :theme="theme" />
165</Teleport>
166```
167β
168Your Vue component receives the `theme` as a prop along with any other props you pass. It runs within the Vue app's reactivity system with full access to composition API, inject/provide, etc.
169β
170### The Key Insight
171β
172```mermaid
173graph LR
174 subgraph fw["Your Framework Runtime"]
175 comp["Your Plugin Component<br/><i>Full reactivity, hooks, signals</i>"]
176 end
177 subgraph core["Devtools Core (Solid.js)"]
178 container["Plugin Container<br/><div id='plugin-container-{id}'>"]
179 end
180 comp -- "Portal / Teleport" --> container
181```
182β
183Regardless of framework, your plugin component runs in its **normal framework context** with full reactivity, hooks, signals, lifecycle methods, and dependency injection. It just renders into a different DOM location via portals or teleports. This means:
184β
185- React plugins can use `useState`, `useEffect`, `useContext`, and any React library.
186- Solid plugins can use signals, stores, `createEffect`, and the full Solid API.
187- Vue plugins can use `ref`, `computed`, `watch`, `inject`, and any Vue composable.
188β
189The framework adapter handles all the wiring between your component and the devtools container.
190β
191## Plugin State
192β
193The devtools persist the active/visible plugin selection in `localStorage` under the key `tanstack_devtools_state`. This means that when a user opens specific plugin tabs, their selection survives page reloads.
194β
195Key behaviors:
196β
197- **Maximum 3 visible plugins** - At most 3 plugin panels can be displayed simultaneously. Activating a 4th plugin deactivates the earliest one.
198- **`defaultOpen` vs. saved state** - If `defaultOpen: true` is set on a plugin and no saved state exists in localStorage, the plugin opens on first load. Once the user changes the selection, their preference takes precedence.
199- **Single-plugin auto-open** - If only one plugin is registered, it opens automatically regardless of `defaultOpen` or saved state.
200- **Stale plugin cleanup** - When the devtools load, any plugin IDs in the saved state that no longer match a registered plugin are automatically removed.
201β
202## Cleanup
203β
204When `TanStackDevtoolsCore.unmount()` is called - either explicitly or because the framework component unmounts - the following happens:
205β
2061. The Solid reactive system disposes of the entire devtools component tree.
2072. For each active plugin that provides a `destroy` function, `destroy(pluginId)` is called.
2083. All DOM containers created by the core are removed.
209β
210Framework adapters handle their own cleanup automatically:
211β
212- **React** unmounts the portal, which triggers the normal React cleanup cycle (`useEffect` cleanup functions, etc.).
213- **Vue** destroys the Teleport, which runs `onUnmounted` hooks in your component.
214- **Solid** disposes of the Portal's reactive scope, running any `onCleanup` callbacks.
215β
216You typically do **not** need to implement `destroy` unless your plugin has manual subscriptions, timers, WebSocket connections, or other resources that aren't tied to your framework's lifecycle. If all your cleanup is handled by framework hooks (like `useEffect` cleanup in React or `onCleanup` in Solid), the adapter takes care of it for you.