@tanstack/devtools-utils 0.3.3 → 0.4.0

package/skills/devtools-framework-adapters/references/vue.md

@@ -0,0 +1,270 @@
+# Vue Framework Adapter Reference
+
+## Import
+
+```ts
+import { createVuePlugin, createVuePanel } from '@tanstack/devtools-utils/vue'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
+```
+
+## DevtoolsPanelProps
+
+```ts
+// NOTE: Vue includes 'system' -- unlike React/Solid/Preact
+interface DevtoolsPanelProps {
+  theme?: 'dark' | 'light' | 'system'
+}
+```
+
+## createVuePlugin
+
+Creates a `[Plugin, NoOpPlugin]` tuple from a Vue component.
+
+**CRITICAL: Vue uses positional arguments `(name, component)`, NOT an options object.**
+
+### Signature
+
+```ts
+function createVuePlugin<TComponentProps extends Record<string, any>>(
+  name: string,
+  component: DefineComponent<TComponentProps, {}, unknown>,
+): readonly [Plugin, NoOpPlugin]
+```
+
+### Parameters
+
+| Parameter   | Type                               | Required | Description                            |
+| ----------- | ---------------------------------- | -------- | -------------------------------------- |
+| `name`      | `string`                           | Yes      | Display name shown in the devtools tab |
+| `component` | `DefineComponent<TComponentProps>` | Yes      | Vue component to render in the panel   |
+
+Note: There is **no** `id` or `defaultOpen` parameter. Vue plugins are simpler.
+
+### Return Value
+
+A `readonly [Plugin, NoOpPlugin]` tuple. Both are **functions that accept props**:
+
+- **`Plugin(props: TComponentProps)`** -- returns `{ name, component, props }` where `component` is your Vue component.
+- **`NoOpPlugin(props: TComponentProps)`** -- returns `{ name, component: Fragment, props }` where `Fragment` is Vue's built-in fragment (renders nothing visible).
+
+**This differs from React/Solid/Preact** where `Plugin()` takes no arguments.
+
+### Source
+
+```ts
+// packages/devtools-utils/src/vue/plugin.ts
+import { Fragment } from 'vue'
+import type { DefineComponent } from 'vue'
+
+export function createVuePlugin<TComponentProps extends Record<string, any>>(
+  name: string,
+  component: DefineComponent<TComponentProps, {}, unknown>,
+) {
+  function Plugin(props: TComponentProps) {
+    return {
+      name,
+      component,
+      props,
+    }
+  }
+  function NoOpPlugin(props: TComponentProps) {
+    return {
+      name,
+      component: Fragment,
+      props,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}
+```
+
+### Usage
+
+#### Basic
+
+```vue
+<!-- MyStorePanel.vue -->
+<script setup lang="ts">
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
+
+const props = defineProps<DevtoolsPanelProps>()
+</script>
+
+<template>
+  <div :class="props.theme">
+    <h2>My Store Devtools</h2>
+  </div>
+</template>
+```
+
+```ts
+import { createVuePlugin } from '@tanstack/devtools-utils/vue'
+import MyStorePanel from './MyStorePanel.vue'
+
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyStorePanel)
+```
+
+#### Using the Plugin (Vue-specific -- pass props)
+
+```ts
+// Vue plugins are called WITH props
+const plugin = MyPlugin({ theme: 'dark' })
+// Returns: { name: 'My Store', component: MyStorePanel, props: { theme: 'dark' } }
+
+const noopPlugin = NoOpPlugin({ theme: 'dark' })
+// Returns: { name: 'My Store', component: Fragment, props: { theme: 'dark' } }
+```
+
+#### Production Tree-Shaking
+
+```ts
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyStorePanel)
+
+const ActivePlugin = import.meta.env.DEV ? MyPlugin : NoOpPlugin
+```
+
+## createVuePanel
+
+Wraps a class-based devtools core in a Vue `defineComponent`.
+
+### Signature
+
+```ts
+function createVuePanel<
+  TComponentProps extends DevtoolsPanelProps,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme?: DevtoolsPanelProps['theme']) => void
+    unmount: () => void
+  },
+>(
+  CoreClass: new (props: TComponentProps) => TCoreDevtoolsClass,
+): readonly [Panel, NoOpPanel]
+```
+
+### Parameters
+
+| Parameter   | Type                                                                           | Required | Description                                                                                      |
+| ----------- | ------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------ |
+| `CoreClass` | `new (props: TComponentProps) => { mount(el, theme?): void; unmount(): void }` | Yes      | Class constructor. **Note:** Vue's constructor takes `props`, unlike React's no-arg constructor. |
+
+### Return Value
+
+A tuple of two Vue `DefineComponent`s:
+
+- **`Panel`** -- Accepts `theme` and `devtoolsProps` as props. On `onMounted`, instantiates `CoreClass(devtoolsProps)` and calls `mount(el, theme)`. On `onUnmounted`, calls `unmount()`. Renders a `<div style="height:100%">`.
+- **`NoOpPanel`** -- Renders `null`.
+
+Both components have the type:
+
+```ts
+DefineComponent<{
+  theme?: 'dark' | 'light' | 'system'
+  devtoolsProps: TComponentProps
+}>
+```
+
+### Source
+
+```ts
+// packages/devtools-utils/src/vue/panel.ts
+export function createVuePanel<
+  TComponentProps extends DevtoolsPanelProps,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme?: DevtoolsPanelProps['theme']) => void
+    unmount: () => void
+  },
+>(CoreClass: new (props: TComponentProps) => TCoreDevtoolsClass) {
+  const props = {
+    theme: { type: String as () => DevtoolsPanelProps['theme'] },
+    devtoolsProps: { type: Object as () => TComponentProps },
+  }
+
+  const Panel = defineComponent({
+    props,
+    setup(config) {
+      const devToolRef = ref<HTMLElement | null>(null)
+      const devtools = ref<TCoreDevtoolsClass | null>(null)
+      onMounted(() => {
+        const instance = new CoreClass(config.devtoolsProps as TComponentProps)
+        devtools.value = instance
+        if (devToolRef.value) {
+          instance.mount(devToolRef.value, config.theme)
+        }
+      })
+      onUnmounted(() => {
+        if (devToolRef.value && devtools.value) {
+          devtools.value.unmount()
+        }
+      })
+      return () => h('div', { style: { height: '100%' }, ref: devToolRef })
+    },
+  })
+
+  const NoOpPanel = defineComponent({
+    props,
+    setup() {
+      return () => null
+    },
+  })
+
+  return [Panel, NoOpPanel] as unknown as [
+    DefineComponent<{
+      theme?: DevtoolsPanelProps['theme']
+      devtoolsProps: TComponentProps
+    }>,
+    DefineComponent<{
+      theme?: DevtoolsPanelProps['theme']
+      devtoolsProps: TComponentProps
+    }>,
+  ]
+}
+```
+
+### Usage
+
+```ts
+import { createVuePanel, createVuePlugin } from '@tanstack/devtools-utils/vue'
+
+class MyDevtoolsCore {
+  constructor(private props: { theme?: string }) {}
+  mount(el: HTMLElement, theme?: 'dark' | 'light' | 'system') {
+    // render into el
+  }
+  unmount() {
+    // cleanup
+  }
+}
+
+// Step 1: Create panel from class
+const [MyPanel, NoOpPanel] = createVuePanel(MyDevtoolsCore)
+
+// Step 2: Create plugin from panel
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Store', MyPanel)
+```
+
+#### Using the Panel Directly in a Template
+
+```vue
+<template>
+  <MyPanel
+    theme="dark"
+    :devtools-props="{
+      /* ... */
+    }"
+  />
+</template>
+```
+
+## Vue-Specific Gotchas
+
+1. **Positional arguments, not options object.** This is the most common mistake. `createVuePlugin('name', Component)`, not `createVuePlugin({ name, Component })`.
+
+2. **Plugin functions accept props.** `MyPlugin(props)` returns `{ name, component, props }`. This differs from React/Solid/Preact where `Plugin()` takes no arguments.
+
+3. **Theme includes `'system'`.** Vue's `DevtoolsPanelProps` accepts `'dark' | 'light' | 'system'`, while all other frameworks only accept `'light' | 'dark'`.
+
+4. **No `id` or `defaultOpen`.** The Vue `createVuePlugin` API only takes `name` and `component`. There is no `id` or `defaultOpen` parameter.
+
+5. **Panel constructor takes props.** `createVuePanel`'s `CoreClass` constructor receives props: `new CoreClass(devtoolsProps)`. React/Preact/Solid constructors take no arguments.
+
+6. **`devtoolsProps` prop on panel.** The Vue panel component has a separate `devtoolsProps` prop for forwarding data to the core class, in addition to the `theme` prop.

package/src/preact/panel.tsx

@@ -1,10 +1,9 @@
 /** @jsxImportSource preact */
 
 import { useEffect, useRef } from 'preact/hooks'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
-export interface DevtoolsPanelProps {
-  theme?: 'light' | 'dark'
-}
+export interface DevtoolsPanelProps extends TanStackDevtoolsPluginProps {}
 
 /**
  * Creates a Preact component that dynamically imports and mounts a devtools panel. SSR friendly.
@@ -24,9 +23,9 @@ export interface DevtoolsPanelProps {
  * ```
  */
 export function createPreactPanel<
-  TComponentProps extends DevtoolsPanelProps | undefined,
+  TComponentProps extends DevtoolsPanelProps,
   TCoreDevtoolsClass extends {
-    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    mount: (el: HTMLElement, props: TanStackDevtoolsPluginProps) => void
     unmount: () => void
   },
 >(CoreClass: new () => TCoreDevtoolsClass) {
@@ -38,7 +37,7 @@ export function createPreactPanel<
       devtools.current = new CoreClass()
 
       if (devToolRef.current) {
-        devtools.current.mount(devToolRef.current, props?.theme ?? 'dark')
+        devtools.current.mount(devToolRef.current, props)
       }
 
       return () => {
@@ -47,7 +46,7 @@ export function createPreactPanel<
           devtools.current = null
         }
       }
-    }, [props?.theme])
+    }, [props])
 
     return <div style={{ height: '100%' }} ref={devToolRef} />
   }

package/src/preact/plugin.tsx

@@ -2,6 +2,7 @@
 
 import type { JSX } from 'preact'
 import type { DevtoolsPanelProps } from './panel'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
 export function createPreactPlugin({
   Component,
@@ -15,15 +16,15 @@ export function createPreactPlugin({
   function Plugin() {
     return {
       ...config,
-      render: (_el: HTMLElement, theme: 'light' | 'dark') => (
-        <Component theme={theme} />
+      render: (_el: HTMLElement, props: TanStackDevtoolsPluginProps) => (
+        <Component {...props} />
       ),
     }
   }
   function NoOpPlugin() {
     return {
       ...config,
-      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+      render: (_el: HTMLElement, _props: TanStackDevtoolsPluginProps) => <></>,
     }
   }
   return [Plugin, NoOpPlugin] as const

package/src/react/panel.tsx

@@ -1,8 +1,7 @@
 import { useEffect, useRef } from 'react'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
-export interface DevtoolsPanelProps {
-  theme?: 'light' | 'dark'
-}
+export interface DevtoolsPanelProps extends TanStackDevtoolsPluginProps {}
 
 /**
  * Creates a React component that dynamically imports and mounts a devtools panel. SSR friendly.
@@ -22,9 +21,9 @@ export interface DevtoolsPanelProps {
  * ```
  */
 export function createReactPanel<
-  TComponentProps extends DevtoolsPanelProps | undefined,
+  TComponentProps extends TanStackDevtoolsPluginProps,
   TCoreDevtoolsClass extends {
-    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    mount: (el: HTMLElement, props: TanStackDevtoolsPluginProps) => void
     unmount: () => void
   },
 >(CoreClass: new () => TCoreDevtoolsClass) {
@@ -36,7 +35,7 @@ export function createReactPanel<
       devtools.current = new CoreClass()
 
       if (devToolRef.current) {
-        devtools.current.mount(devToolRef.current, props?.theme ?? 'dark')
+        devtools.current.mount(devToolRef.current, props)
       }
 
       return () => {
@@ -45,7 +44,7 @@ export function createReactPanel<
           devtools.current = null
         }
       }
-    }, [props?.theme])
+    }, [props])
 
     return <div style={{ height: '100%' }} ref={devToolRef} />
   }

package/src/react/plugin.tsx

@@ -1,5 +1,6 @@
 import type { JSX } from 'react'
 import type { DevtoolsPanelProps } from './panel'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
 export function createReactPlugin({
   Component,
@@ -13,15 +14,15 @@ export function createReactPlugin({
   function Plugin() {
     return {
       ...config,
-      render: (_el: HTMLElement, theme: 'light' | 'dark') => (
-        <Component theme={theme} />
+      render: (_el: HTMLElement, props: TanStackDevtoolsPluginProps) => (
+        <Component {...props} />
       ),
     }
   }
   function NoOpPlugin() {
     return {
       ...config,
-      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+      render: (_el: HTMLElement, _props: TanStackDevtoolsPluginProps) => <></>,
     }
   }
   return [Plugin, NoOpPlugin] as const

package/src/solid/class-mount-impl.tsx

@@ -2,27 +2,24 @@
 
 import { lazy } from 'solid-js'
 import { Portal, render } from 'solid-js/web'
+
 import type { JSX } from 'solid-js'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
 export function __mountComponent(
   el: HTMLElement,
-  theme: 'light' | 'dark',
-  importFn: () => Promise<{ default: () => JSX.Element }>,
+  props: TanStackDevtoolsPluginProps,
+  importFn: () => Promise<{
+    default: (props: TanStackDevtoolsPluginProps) => JSX.Element
+  }>,
 ): () => void {
   const Component = lazy(importFn)
-  const ThemeProvider = lazy(() =>
-    import('@tanstack/devtools-ui').then((m) => ({
-      default: m.ThemeContextProvider,
-    })),
-  )
 
   return render(
     () => (
       <Portal mount={el}>
         <div style={{ height: '100%' }}>
-          <ThemeProvider theme={theme}>
-            <Component />
-          </ThemeProvider>
+          <Component {...props} />
         </div>
       </Portal>
     ),

package/src/solid/class.test.tsx

@@ -28,16 +28,23 @@ describe('constructCoreClass', () => {
     const [DevtoolsCore] = constructCoreClass(importFn)
     const instance = new DevtoolsCore()
     const el = document.createElement('div')
-    await instance.mount(el, 'dark')
-    expect(mountComponentMock).toHaveBeenCalledWith(el, 'dark', importFn)
+    const props = { theme: 'dark' as const, devtoolsOpen: true }
+    await instance.mount(el, props)
+    expect(mountComponentMock).toHaveBeenCalledWith(el, props, importFn)
   })
 
   it('DevtoolsCore should throw if mount is called twice without unmounting', async () => {
     const [DevtoolsCore] = constructCoreClass(importFn)
     const instance = new DevtoolsCore()
-    await instance.mount(document.createElement('div'), 'dark')
+    await instance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     await expect(
-      instance.mount(document.createElement('div'), 'dark'),
+      instance.mount(document.createElement('div'), {
+        theme: 'dark',
+        devtoolsOpen: true,
+      }),
     ).rejects.toThrow('Devtools is already mounted')
   })
 
@@ -50,17 +57,26 @@ describe('constructCoreClass', () => {
   it('DevtoolsCore should allow mount after unmount', async () => {
     const [DevtoolsCore] = constructCoreClass(importFn)
     const instance = new DevtoolsCore()
-    await instance.mount(document.createElement('div'), 'dark')
+    await instance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     instance.unmount()
     await expect(
-      instance.mount(document.createElement('div'), 'dark'),
+      instance.mount(document.createElement('div'), {
+        theme: 'dark',
+        devtoolsOpen: true,
+      }),
     ).resolves.not.toThrow()
   })
 
   it('DevtoolsCore should call dispose on unmount', async () => {
     const [DevtoolsCore] = constructCoreClass(importFn)
     const instance = new DevtoolsCore()
-    await instance.mount(document.createElement('div'), 'dark')
+    await instance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     instance.unmount()
     expect(disposeMock).toHaveBeenCalled()
   })
@@ -68,7 +84,10 @@ describe('constructCoreClass', () => {
   it('DevtoolsCore should abort mount if unmount is called during mounting', async () => {
     const [DevtoolsCore] = constructCoreClass(importFn)
     const instance = new DevtoolsCore()
-    const mountPromise = instance.mount(document.createElement('div'), 'dark')
+    const mountPromise = instance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     // Unmount while mount is in progress — triggers abort path
     // Note: since the mock resolves immediately, this tests the #abortMount flag
     await mountPromise
@@ -80,16 +99,25 @@ describe('constructCoreClass', () => {
   it('NoOpDevtoolsCore should not call __mountComponent when mount is called', async () => {
     const [, NoOpDevtoolsCore] = constructCoreClass(importFn)
     const noOpInstance = new NoOpDevtoolsCore()
-    await noOpInstance.mount(document.createElement('div'), 'dark')
+    await noOpInstance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     expect(mountComponentMock).not.toHaveBeenCalled()
   })
 
   it('NoOpDevtoolsCore should not throw if mount is called multiple times', async () => {
     const [, NoOpDevtoolsCore] = constructCoreClass(importFn)
     const noOpInstance = new NoOpDevtoolsCore()
-    await noOpInstance.mount(document.createElement('div'), 'dark')
+    await noOpInstance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     await expect(
-      noOpInstance.mount(document.createElement('div'), 'dark'),
+      noOpInstance.mount(document.createElement('div'), {
+        theme: 'dark',
+        devtoolsOpen: true,
+      }),
     ).resolves.not.toThrow()
   })
 
@@ -102,7 +130,10 @@ describe('constructCoreClass', () => {
   it('NoOpDevtoolsCore should not throw if unmount is called after mount', async () => {
     const [, NoOpDevtoolsCore] = constructCoreClass(importFn)
     const noOpInstance = new NoOpDevtoolsCore()
-    await noOpInstance.mount(document.createElement('div'), 'dark')
+    await noOpInstance.mount(document.createElement('div'), {
+      theme: 'dark',
+      devtoolsOpen: true,
+    })
     expect(() => noOpInstance.unmount()).not.toThrow()
   })
 })

package/src/solid/class.ts

@@ -1,3 +1,4 @@
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 import type { JSX } from 'solid-js'
 
 /**
@@ -10,7 +11,9 @@ import type { JSX } from 'solid-js'
  * @returns Tuple containing the DevtoolsCore class and a NoOpDevtoolsCore class
  */
 export function constructCoreClass(
-  importFn: () => Promise<{ default: () => JSX.Element }>,
+  importFn: () => Promise<{
+    default: (props: TanStackDevtoolsPluginProps) => JSX.Element
+  }>,
 ) {
   class DevtoolsCore {
     #isMounted = false
@@ -20,7 +23,10 @@ export function constructCoreClass(
 
     constructor() {}
 
-    async mount<T extends HTMLElement>(el: T, theme: 'light' | 'dark') {
+    async mount<T extends HTMLElement>(
+      el: T,
+      props: TanStackDevtoolsPluginProps,
+    ) {
       if (this.#isMounted || this.#isMounting) {
         throw new Error('Devtools is already mounted')
       }
@@ -35,7 +41,7 @@ export function constructCoreClass(
           return
         }
 
-        this.#dispose = __mountComponent(el, theme, importFn)
+        this.#dispose = __mountComponent(el, props, importFn)
         this.#isMounted = true
         this.#isMounting = false
       } catch (err) {
@@ -48,11 +54,13 @@ export function constructCoreClass(
       if (!this.#isMounted && !this.#isMounting) {
         throw new Error('Devtools is not mounted')
       }
+
       if (this.#isMounting) {
         this.#abortMount = true
         this.#isMounting = false
         return
       }
+
       this.#dispose?.()
       this.#isMounted = false
     }
@@ -62,7 +70,10 @@ export function constructCoreClass(
     constructor() {
       super()
     }
-    async mount<T extends HTMLElement>(_el: T, _theme: 'light' | 'dark') {}
+    async mount<T extends HTMLElement>(
+      _el: T,
+      _props: TanStackDevtoolsPluginProps,
+    ) {}
     unmount() {}
   }
 

package/src/solid/panel.tsx

@@ -2,20 +2,19 @@
 
 import { createSignal, onCleanup, onMount } from 'solid-js'
 import type { ClassType } from './class'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
-export interface DevtoolsPanelProps {
-  theme?: 'light' | 'dark'
-}
+export interface DevtoolsPanelProps extends TanStackDevtoolsPluginProps {}
 
-export function createSolidPanel<
-  TComponentProps extends DevtoolsPanelProps | undefined,
->(CoreClass: ClassType) {
+export function createSolidPanel<TComponentProps extends DevtoolsPanelProps>(
+  CoreClass: ClassType,
+) {
   function Panel(props: TComponentProps) {
     let devToolRef: HTMLDivElement | undefined
     const [devtools] = createSignal(new CoreClass())
     onMount(() => {
       if (devToolRef) {
-        devtools().mount(devToolRef, props?.theme ?? 'dark')
+        devtools().mount(devToolRef, props)
       }
       onCleanup(() => {
         devtools().unmount()

package/src/solid/plugin.tsx

@@ -2,6 +2,7 @@
 
 import type { JSX } from 'solid-js'
 import type { DevtoolsPanelProps } from './panel'
+import type { TanStackDevtoolsPluginProps } from '@tanstack/devtools'
 
 export function createSolidPlugin({
   Component,
@@ -15,15 +16,15 @@ export function createSolidPlugin({
   function Plugin() {
     return {
       ...config,
-      render: (_el: HTMLElement, theme: 'light' | 'dark') => {
-        return <Component theme={theme} />
+      render: (_el: HTMLElement, props: TanStackDevtoolsPluginProps) => {
+        return <Component {...props} />
       },
     }
   }
   function NoOpPlugin() {
     return {
       ...config,
-      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+      render: (_el: HTMLElement, _props: TanStackDevtoolsPluginProps) => <></>,
     }
   }
   return [Plugin, NoOpPlugin] as const