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

devtools.tsx

277 lines7.0 KB

1import React, { useEffect, useMemo, useRef, useState } from 'react'
2import { TanStackDevtoolsCore } from '@tanstack/devtools'
3import { createPortal } from 'react-dom'
4import type { JSX, ReactElement } from 'react'
5import type {
6 ClientEventBusConfig,
7 TanStackDevtoolsConfig,
8 TanStackDevtoolsPlugin,
9 TanStackDevtoolsPluginProps,
10 TanStackDevtoolsTheme,
11} from '@tanstack/devtools'
12​
13type PluginRender =
14 | JSX.Element
15 | ((el: HTMLElement, props: TanStackDevtoolsPluginProps) => JSX.Element)
16​
17type TriggerProps = {
18 theme: TanStackDevtoolsTheme
20​
21type TriggerRender =
22 | JSX.Element
23 | ((el: HTMLElement, props: TriggerProps) => JSX.Element)
24​
25export type TanStackDevtoolsReactPlugin = Omit<
26 TanStackDevtoolsPlugin,
27 'render' | 'name'
28> & {
29 /**
30 * The render function can be a React element or a function that returns a React element.
31 * If it's a function, it will be called to render the plugin, otherwise it will be rendered directly.
32 *
33 * Example:
34 * ```jsx
35 * {
36 * render: () => <CustomPluginComponent />,
37 * }
38 * ```
39 * or
40 * ```jsx
41 * {
42 * render: <CustomPluginComponent />,
43 * }
44 * ```
45 */
46 render: PluginRender
47 /**
48 * Name to be displayed in the devtools UI.
49 * If a string, it will be used as the plugin name.
50 * If a function, it will be called with the mount element.
51 *
52 * Example:
53 * ```jsx
54 * {
55 * name: "Your Plugin",
56 * render: () => <CustomPluginComponent />,
57 * }
58 * ```
59 * or
60 * ```jsx
61 * {
62 * name: <h1>Your Plugin title</h1>,
63 * render: () => <CustomPluginComponent />,
64 * }
65 * ```
66 */
67 name: string | PluginRender
69​
70type TanStackDevtoolsReactConfig = Omit<
71 Partial<TanStackDevtoolsConfig>,
72 'customTrigger'
73> & {
74 /**
75 * Optional custom trigger component for the devtools.
76 * It can be a React element or a function that renders one.
77 *
78 * Example:
79 * ```jsx
80 * {
81 * customTrigger: <CustomTriggerComponent />,
82 * }
83 * ```
84 */
85 customTrigger?: TriggerRender
87​
88export interface TanStackDevtoolsReactInit {
89 /**
90 * Array of plugins to be used in the devtools.
91 * Each plugin should have a `render` function that returns a React element or a function
92 *
93 * Example:
94 * ```jsx
95 * <TanStackDevtools
96 * plugins={[
97 * {
98 * id: "your-plugin-id",
99 * name: "Your Plugin",
100 * render: <CustomPluginComponent />,
101 * }
102 * ]}
103 * />
104 * ```
105 */
106 plugins?: Array<TanStackDevtoolsReactPlugin>
107 /**
108 * Configuration for the devtools shell. These configuration options are used to set the
109 * initial state of the devtools when it is started for the first time. Afterwards,
110 * the settings are persisted in local storage and changed through the settings panel.
111 */
112 config?: TanStackDevtoolsReactConfig
113 /**
114 * Configuration for the TanStack Devtools client event bus.
115 */
116 eventBusConfig?: ClientEventBusConfig
118​
119const convertRender = (
120 Component: PluginRender,
121 setComponents: React.Dispatch<
122 React.SetStateAction<Record<string, JSX.Element>>
123 >,
124 e: HTMLElement,
125 props: TanStackDevtoolsPluginProps,
126) => {
127 const element =
128 typeof Component === 'function' ? Component(e, props) : Component
129​
130 setComponents((prev) => ({
131 ...prev,
132 [e.getAttribute('id') as string]: element,
133 }))
135​
136const convertTrigger = (
137 Component: TriggerRender,
138 setComponent: React.Dispatch<React.SetStateAction<JSX.Element | null>>,
139 e: HTMLElement,
140 props: TriggerProps,
141) => {
142 const element =
143 typeof Component === 'function' ? Component(e, props) : Component
144 setComponent(element)
146​
147export const TanStackDevtools = ({
148 plugins,
149 config,
150 eventBusConfig,
151}: TanStackDevtoolsReactInit): ReactElement | null => {
152 const devToolRef = useRef<HTMLDivElement>(null)
153​
154 const [pluginContainers, setPluginContainers] = useState<
155 Record<string, HTMLElement>
156 >({})
157 const [titleContainers, setTitleContainers] = useState<
158 Record<string, HTMLElement>
159 >({})
160 const [triggerContainer, setTriggerContainer] = useState<HTMLElement | null>(
161 null,
162 )
163​
164 const [PluginComponents, setPluginComponents] = useState<
165 Record<string, JSX.Element>
166 >({})
167 const [TitleComponents, setTitleComponents] = useState<
168 Record<string, JSX.Element>
169 >({})
170 const [TriggerComponent, setTriggerComponent] = useState<JSX.Element | null>(
171 null,
172 )
173​
174 const pluginsMap: Array<TanStackDevtoolsPlugin> = useMemo(
175 () =>
176 plugins?.map((plugin) => {
177 return {
178 ...plugin,
179 name:
180 typeof plugin.name === 'string'
181 ? plugin.name
182 : (e, props) => {
183 const id = e.getAttribute('id')!
184 const target = e.ownerDocument.getElementById(id)
185​
186 if (target) {
187 setTitleContainers((prev) => ({
188 ...prev,
189 [id]: e,
190 }))
191 }
192​
193 convertRender(
194 plugin.name as PluginRender,
195 setTitleComponents,
196 e,
197 props,
198 )
199 },
200 render: (e, theme) => {
201 const id = e.getAttribute('id')!
202 const target = e.ownerDocument.getElementById(id)
203​
204 if (target) {
205 setPluginContainers((prev) => ({
206 ...prev,
207 [id]: e,
208 }))
209 }
210​
211 convertRender(plugin.render, setPluginComponents, e, theme)
212 },
213 }
214 }) ?? [],
215 [plugins],
216 )
217​
218 const [devtools] = useState(() => {
219 const { customTrigger, ...coreConfig } = config || {}
220 return new TanStackDevtoolsCore({
221 config: {
222 ...coreConfig,
223 customTrigger: customTrigger
224 ? (el, props) => {
225 setTriggerContainer(el)
226 convertTrigger(customTrigger, setTriggerComponent, el, props)
227 }
228 : undefined,
229 },
230 eventBusConfig,
231 plugins: pluginsMap,
232 })
233 })
234​
235 useEffect(() => {
236 devtools.setConfig({
237 plugins: pluginsMap,
238 })
239 }, [devtools, pluginsMap])
240​
241 useEffect(() => {
242 if (devToolRef.current) {
243 devtools.mount(devToolRef.current)
244 }
245​
246 return () => devtools.unmount()
247 }, [devtools])
248​
249 const hasPlugins =
250 Object.values(pluginContainers).length > 0 &&
251 Object.values(PluginComponents).length > 0
252 const hasTitles =
253 Object.values(titleContainers).length > 0 &&
254 Object.values(TitleComponents).length > 0
255​
256 return (
257 <>
258 <div style={{ position: 'absolute' }} ref={devToolRef} />
259​
260 {hasPlugins
261 ? Object.entries(pluginContainers).map(([key, pluginContainer]) =>
262 createPortal(<>{PluginComponents[key]}</>, pluginContainer),
263 )
264 : null}
265​
266 {hasTitles
267 ? Object.entries(titleContainers).map(([key, titleContainer]) =>
268 createPortal(<>{TitleComponents[key]}</>, titleContainer),
269 )
270 : null}
271​
272 {triggerContainer && TriggerComponent
273 ? createPortal(<>{TriggerComponent}</>, triggerContainer)
274 : null}
275 </>
276 )