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

preact.md

262 lines8.1 KB

Preact Framework Adapter Reference

Import

import {
  createPreactPlugin,
  createPreactPanel,
} from '@tanstack/devtools-utils/preact'
import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/preact'

DevtoolsPanelProps

interface DevtoolsPanelProps {
  theme?: 'light' | 'dark'
}

createPreactPlugin

Creates a [Plugin, NoOpPlugin] tuple from a Preact component and plugin metadata. Identical API to createReactPlugin.

Signature

function createPreactPlugin(options: {
  name: string
  id?: string
  defaultOpen?: boolean
  Component: (props: DevtoolsPanelProps) => JSX.Element
}): readonly [Plugin, NoOpPlugin]

Parameters

ParameterTypeRequiredDescription
namestringYesDisplay name shown in the devtools tab
idstringNoUnique identifier for the plugin
defaultOpenbooleanNoWhether the plugin panel starts open
Component(props: DevtoolsPanelProps) => JSX.ElementYesPreact 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

// 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

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

const [MyPlugin, NoOpPlugin] = createPreactPlugin({
  name: 'My Store',
  Component: ({ theme }) => <MyStorePanel theme={theme} />,
})

Production Tree-Shaking

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

function createPreactPanel<
  TComponentProps extends DevtoolsPanelProps | undefined,
  TCoreDevtoolsClass extends {
    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
    unmount: () => void
  },
>(CoreClass: new () => TCoreDevtoolsClass): readonly [Panel, NoOpPanel]

Parameters

ParameterTypeRequiredDescription
CoreClassnew () => { mount(el, theme): void; unmount(): void }YesClass 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

// 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

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

AspectReactPreact
Import path@tanstack/devtools-utils/react@tanstack/devtools-utils/preact
JSX typesreact JSXpreact JSX
Hooks importreactpreact/hooks
API shapeIdenticalIdentical
createXPlugin signatureSameSame
createXPanel signatureSameSame
DevtoolsPanelPropsSameSame

If you have working React adapter code, converting to Preact is a matter of changing the import paths.