@tanstack/devtools-utils 0.3.3 → 0.4.0

package/skills/devtools-framework-adapters/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: devtools-framework-adapters
+description: >
+  Use devtools-utils factory functions to create per-framework plugin adapters.
+  createReactPlugin/createSolidPlugin/createVuePlugin/createPreactPlugin,
+  createReactPanel/createSolidPanel/createVuePanel/createPreactPanel.
+  [Plugin, NoOpPlugin] tuple for tree-shaking. DevtoolsPanelProps (theme).
+  Vue uses (name, component) not options object. Solid render must be function.
+type: framework
+library: tanstack-devtools
+library_version: '0.10.12'
+requires:
+  - tanstack-devtools/plugin-panel
+sources:
+  - 'TanStack/devtools:docs/devtools-utils.md'
+  - 'TanStack/devtools:packages/devtools-utils/src/react/plugin.tsx'
+  - 'TanStack/devtools:packages/devtools-utils/src/vue/plugin.ts'
+  - 'TanStack/devtools:packages/devtools-utils/src/solid/plugin.tsx'
+  - 'TanStack/devtools:packages/devtools-utils/src/preact/plugin.tsx'
+---
+
+Use `@tanstack/devtools-utils` factory functions to create per-framework devtools plugin adapters. Each framework has a subpath export (`/react`, `/vue`, `/solid`, `/preact`) with two factories:
+
+1. **`createXPlugin`** -- wraps a component into a `[Plugin, NoOpPlugin]` tuple for tree-shaking.
+2. **`createXPanel`** -- wraps a class-based devtools core (`mount`/`unmount`) into a `[Panel, NoOpPanel]` component tuple.
+
+## Key Source Files
+
+- `packages/devtools-utils/src/react/plugin.tsx` -- createReactPlugin
+- `packages/devtools-utils/src/react/panel.tsx` -- createReactPanel, DevtoolsPanelProps
+- `packages/devtools-utils/src/vue/plugin.ts` -- createVuePlugin (different API)
+- `packages/devtools-utils/src/vue/panel.ts` -- createVuePanel, DevtoolsPanelProps (includes 'system' theme)
+- `packages/devtools-utils/src/solid/plugin.tsx` -- createSolidPlugin
+- `packages/devtools-utils/src/solid/panel.tsx` -- createSolidPanel
+- `packages/devtools-utils/src/solid/class.ts` -- constructCoreClass (Solid-specific)
+- `packages/devtools-utils/src/preact/plugin.tsx` -- createPreactPlugin
+- `packages/devtools-utils/src/preact/panel.tsx` -- createPreactPanel
+
+## Shared Pattern
+
+All four frameworks follow the same two-factory pattern:
+
+### Plugin Factory
+
+Every `createXPlugin` returns `readonly [Plugin, NoOpPlugin]`:
+
+- **Plugin** -- returns a plugin object with metadata and a `render` function that renders your component.
+- **NoOpPlugin** -- returns a plugin object with the same metadata but renders an empty fragment.
+
+### Panel Factory
+
+Every `createXPanel` returns `readonly [Panel, NoOpPanel]`:
+
+- **Panel** -- a framework component that creates a `<div style="height:100%">`, instantiates the core class, calls `core.mount(el, theme)` on mount, and `core.unmount()` on cleanup.
+- **NoOpPanel** -- renders an empty fragment.
+
+### DevtoolsPanelProps
+
+```ts
+// React, Solid, Preact
+interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+
+// Vue (note: includes 'system')
+interface DevtoolsPanelProps {
+  theme?: 'dark' | 'light' | 'system'
+}
+```
+
+Import from the framework subpath:
+
+```ts
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/react'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/vue'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/solid'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'
+```
+
+## Primary Example (React)
+
+```tsx
+import { createReactPlugin } from '@tanstack/devtools-utils/react'
+
+function MyStorePanel({ theme }: { theme?: 'light' | 'dark' }) {
+  return <div className={theme}>My Store Devtools</div>
+}
+
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: false,
+  Component: MyStorePanel,
+})
+
+// Tree-shaking: use NoOp in production
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+### With Class-Based Panel
+
+```tsx
+import {
+  createReactPanel,
+  createReactPlugin,
+} from '@tanstack/devtools-utils/react'
+
+class MyDevtoolsCore {
+  mount(el: HTMLElement, theme: 'light' | 'dark') {
+    /* render into el */
+  }
+  unmount() {
+    /* cleanup */
+  }
+}
+
+const [MyPanel, NoOpPanel] = createReactPanel(MyDevtoolsCore)
+
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+```
+
+## Framework API Differences
+
+### React & Preact -- Options Object
+
+```ts
+createReactPlugin({ name, id?, defaultOpen?, Component })  // => [Plugin, NoOpPlugin]
+createPreactPlugin({ name, id?, defaultOpen?, Component }) // => [Plugin, NoOpPlugin]
+```
+
+- `Component` receives `DevtoolsPanelProps` (with `theme`).
+- `Plugin()` returns `{ name, id?, defaultOpen?, render(el, theme) }`.
+- Preact is identical to React but uses Preact JSX types and `preact/hooks`.
+
+### Vue -- Positional Arguments, NOT Options Object
+
+```ts
+createVuePlugin(name: string, component: DefineComponent) // => [Plugin, NoOpPlugin]
+```
+
+- Takes `(name, component)` as separate arguments, NOT an options object.
+- `Plugin(props)` returns `{ name, component, props }` -- it passes props through.
+- `NoOpPlugin(props)` returns `{ name, component: Fragment, props }`.
+- Vue's `DevtoolsPanelProps.theme` also accepts `'system'`.
+
+### Solid -- Same API as React, Different Internals
+
+```ts
+createSolidPlugin({ name, id?, defaultOpen?, Component }) // => [Plugin, NoOpPlugin]
+```
+
+- Same options-object API as React.
+- `Component` must be a Solid component function `(props: DevtoolsPanelProps) => JSX.Element`.
+- The render function internally returns `<Component theme={theme} />` -- Solid handles reactivity.
+- Solid also exports `constructCoreClass` from `@tanstack/devtools-utils/solid/class` for building lazy-loaded devtools cores.
+
+## Common Mistakes
+
+### CRITICAL: Using React JSX Pattern in Vue Adapter
+
+Vue uses positional `(name, component)` arguments, NOT an options object.
+
+```ts
+// WRONG -- will fail at compile time or produce garbage at runtime
+const [MyPlugin, NoOpPlugin] = createVuePlugin({
+  name: 'My Plugin',
+  Component: MyPanel,
+})
+
+// CORRECT
+const [MyPlugin, NoOpPlugin] = createVuePlugin('My Plugin', MyPanel)
+```
+
+Vue plugins also work differently at call time -- you pass props:
+
+```ts
+// WRONG -- calling Plugin() with no args (React pattern)
+const plugin = MyPlugin()
+
+// CORRECT -- Vue Plugin takes props
+const plugin = MyPlugin({ theme: 'dark' })
+```
+
+### CRITICAL: Solid Render Prop Not Wrapped in Function
+
+When using Solid components, `Component` must be a function reference, not raw JSX.
+
+```tsx
+// WRONG -- evaluates immediately, breaks Solid reactivity
+createSolidPlugin({
+  name: 'My Store',
+  Component: <MyPanel />, // This is JSX.Element, not a component function
+})
+
+// CORRECT -- pass the component function itself
+createSolidPlugin({
+  name: 'My Store',
+  Component: (props) => <MyPanel theme={props.theme} />,
+})
+
+// ALSO CORRECT -- pass the component reference directly
+createSolidPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+```
+
+### HIGH: Ignoring NoOp Variant for Production
+
+The factory returns `[Plugin, NoOpPlugin]`. Both must be destructured and used for proper tree-shaking.
+
+```tsx
+// WRONG -- NoOp variant discarded, devtools code ships to production
+const [MyPlugin] = createReactPlugin({ name: 'Store', Component: MyPanel })
+
+// CORRECT -- conditionally use NoOp in production
+const [MyPlugin, NoOpPlugin] = createReactPlugin({
+  name: 'Store',
+  Component: MyPanel,
+})
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+### MEDIUM: Not Passing Theme Prop to Panel Component
+
+`DevtoolsPanelProps` includes `theme`. The devtools shell passes it so panels can match light/dark mode. If your component ignores it, the panel will not adapt to theme changes.
+
+```tsx
+// WRONG -- theme is ignored
+const Component = () => <div>My Panel</div>
+
+// CORRECT -- use theme for styling
+const Component = ({ theme }: DevtoolsPanelProps) => (
+  <div className={theme === 'dark' ? 'dark-mode' : 'light-mode'}>My Panel</div>
+)
+```
+
+## Design Tension
+
+The core architecture is framework-agnostic, but each framework has different idioms:
+
+- React/Preact use an options object with `Component` as a JSX function component.
+- Vue uses positional arguments with a `DefineComponent` and passes props through.
+- Solid uses the same options API as React but with Solid's JSX and reactivity model.
+
+Agents trained on React patterns will get Vue wrong. Always check the import path to determine which factory API to use.
+
+## Cross-References
+
+- **devtools-plugin-panel** -- Build your panel component first, then wrap it with the appropriate framework adapter.
+- **devtools-production** -- NoOp variants are the primary mechanism for stripping devtools from production bundles.
+
+## Reference Files
+
+- `references/react.md` -- Full React factory API and examples
+- `references/vue.md` -- Full Vue factory API and examples (different from React)
+- `references/solid.md` -- Full Solid factory API and examples
+- `references/preact.md` -- Full Preact factory API and examples

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

@@ -0,0 +1,262 @@
+# Preact Framework Adapter Reference
+
+## Import
+
+```ts
+import {
+  createPreactPlugin,
+  createPreactPanel,
+} from '@tanstack/devtools-utils/preact'
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'
+```
+
+## DevtoolsPanelProps
+
+```ts
+interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+```
+
+## createPreactPlugin
+
+Creates a `[Plugin, NoOpPlugin]` tuple from a Preact component and plugin metadata. Identical API to `createReactPlugin`.
+
+### Signature
+
+```ts
+function createPreactPlugin(options: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}): readonly [Plugin, NoOpPlugin]
+```
+
+### Parameters
+
+| Parameter     | Type                                         | Required | Description                             |
+| ------------- | -------------------------------------------- | -------- | --------------------------------------- |
+| `name`        | `string`                                     | Yes      | Display name shown in the devtools tab  |
+| `id`          | `string`                                     | No       | Unique identifier for the plugin        |
+| `defaultOpen` | `boolean`                                    | No       | Whether the plugin panel starts open    |
+| `Component`   | `(props: DevtoolsPanelProps) => JSX.Element` | Yes      | Preact component to render in the panel |
+
+### Return Value
+
+A `readonly [Plugin, NoOpPlugin]` tuple:
+
+- **`Plugin()`** -- returns `{ name, id?, defaultOpen?, render(el, theme) }`. The `render` function renders `<Component theme={theme} />`.
+- **`NoOpPlugin()`** -- returns the same shape but `render` returns `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/preact/plugin.tsx
+/** @jsxImportSource preact */
+import type { JSX } from 'preact'
+import type { DevtoolsPanelProps } from './panel'
+
+export function createPreactPlugin({
+  Component,
+  ...config
+}: {
+  name: string
+  id?: string
+  defaultOpen?: boolean
+  Component: (props: DevtoolsPanelProps) => JSX.Element
+}) {
+  function Plugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, theme: 'light' | 'dark') => (
+        <Component theme={theme} />
+      ),
+    }
+  }
+  function NoOpPlugin() {
+    return {
+      ...config,
+      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}
+```
+
+### Usage
+
+#### Basic
+
+```tsx
+import { createPreactPlugin } from '@tanstack/devtools-utils/preact'
+
+function MyStorePanel({ theme }: { theme?: 'light' | 'dark' }) {
+  return (
+    <div class={theme === 'dark' ? 'dark' : 'light'}>
+      <h2>My Store Devtools</h2>
+    </div>
+  )
+}
+
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: false,
+  Component: MyStorePanel,
+})
+```
+
+#### Inline Component
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  Component: ({ theme }) => <MyStorePanel theme={theme} />,
+})
+```
+
+#### Production Tree-Shaking
+
+```tsx
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  Component: MyStorePanel,
+})
+
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+## createPreactPanel
+
+Wraps a class-based devtools core in a Preact component. Identical behavior to `createReactPanel` but uses `preact/hooks`.
+
+### Signature
+
+```ts
+function createPreactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass): readonly [Panel, NoOpPanel]
+```
+
+### Parameters
+
+| Parameter   | Type                                                    | Required | Description                             |
+| ----------- | ------------------------------------------------------- | -------- | --------------------------------------- |
+| `CoreClass` | `new () => { mount(el, theme): void; unmount(): void }` | Yes      | Class constructor for the devtools core |
+
+### Return Value
+
+- **`Panel`** -- A Preact component that:
+  - Creates a `<div style={{ height: '100%' }}>` with a ref.
+  - Instantiates `CoreClass` on mount via `useEffect` (from `preact/hooks`).
+  - Calls `core.mount(el, props.theme ?? 'dark')`.
+  - Calls `core.unmount()` on cleanup.
+  - Re-runs the effect when `theme` prop changes.
+- **`NoOpPanel`** -- Renders `<></>`.
+
+### Source
+
+```tsx
+// packages/devtools-utils/src/preact/panel.tsx
+/** @jsxImportSource preact */
+import { useEffect, useRef } from 'preact/hooks'
+
+export function createPreactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass) {
+  function Panel(props: TComponentProps) {
+    const devToolRef = useRef<HTMLDivElement>(null)
+    const devtools = useRef<TCoreDevtoolsClass | null>(null)
+    useEffect(() => {
+      if (devtools.current) return
+      devtools.current = new CoreClass()
+      if (devToolRef.current) {
+        devtools.current.mount(devToolRef.current, props?.theme ?? 'dark')
+      }
+      return () => {
+        if (devToolRef.current) {
+          devtools.current?.unmount()
+          devtools.current = null
+        }
+      }
+    }, [props?.theme])
+    return <div style={{ height: '100%' }} ref={devToolRef} />
+  }
+
+  function NoOpPanel(_props: TComponentProps) {
+    return <></>
+  }
+  return [Panel, NoOpPanel] as const
+}
+```
+
+### Usage
+
+```tsx
+import {
+  createPreactPanel,
+  createPreactPlugin,
+} from '@tanstack/devtools-utils/preact'
+
+class MyDevtoolsCore {
+  mount(el: HTMLElement, theme: 'light' | 'dark') {
+    // Use DOM APIs to render your devtools UI into the provided element
+    const container = document.createElement('div')
+    container.className = theme
+    container.textContent = 'Devtools loaded'
+    el.appendChild(container)
+  }
+  unmount() {
+    // cleanup
+  }
+}
+
+// Step 1: Create panel from class
+const [MyPanel, NoOpPanel] = createPreactPanel(MyDevtoolsCore)
+
+// Step 2: Create plugin from panel
+const [MyPlugin, NoOpPlugin] = createPreactPlugin({
+  name: 'My Store',
+  Component: MyPanel,
+})
+
+// Step 3: Conditional for production
+const ActivePlugin =
+  process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlugin
+```
+
+## Preact-Specific Notes
+
+1. **Identical to React API.** `createPreactPlugin` and `createPreactPanel` have the exact same API signatures as their React counterparts. The only difference is the JSX runtime (`preact` vs `react`) and hooks import (`preact/hooks` vs `react`).
+
+2. **Use `class` not `className`.** Preact supports both, but idiomatic Preact uses `class` in JSX.
+
+3. **No Strict Mode double-mount by default.** Preact does not have React's Strict Mode double-invocation behavior, but the ref guard (`if (devtools.current) return`) is still present and harmless.
+
+4. **Default theme is `'dark'`.** If `props.theme` is undefined, the panel defaults to `'dark'`.
+
+5. **Same hooks behavior.** The `useEffect` dependency on `[props?.theme]` means the panel re-mounts when theme changes, same as React.
+
+## Comparison with React
+
+| Aspect                    | React                            | Preact                            |
+| ------------------------- | -------------------------------- | --------------------------------- |
+| Import path               | `@tanstack/devtools-utils/react` | `@tanstack/devtools-utils/preact` |
+| JSX types                 | `react` JSX                      | `preact` JSX                      |
+| Hooks import              | `react`                          | `preact/hooks`                    |
+| API shape                 | Identical                        | Identical                         |
+| `createXPlugin` signature | Same                             | Same                              |
+| `createXPanel` signature  | Same                             | Same                              |
+| `DevtoolsPanelProps`      | Same                             | Same                              |
+
+If you have working React adapter code, converting to Preact is a matter of changing the import paths.