feat: add preact devtools (#283)

* feat: add preact devtools

* changeset

* ci: apply automated fixes

* fix example jsx issue

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: KevinVandy

.changeset/every-crabs-rule.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/preact-devtools': minor
+'@tanstack/devtools-utils': minor
+---
+
+feat: add preact adapter for devtools. Add preact to devtool-utils

docs/config.json

@@ -56,6 +56,19 @@
             }
           ]
         },
+        {
+          "label": "preact",
+          "children": [
+            {
+              "label": "Basic setup",
+              "to": "framework/preact/basic-setup"
+            },
+            {
+              "label": "Preact adapter",
+              "to": "framework/preact/adapter"
+            }
+          ]
+        },
         {
           "label": "solid",
           "children": [
@@ -84,6 +97,15 @@
             }
           ]
         },
+        {
+          "label": "preact",
+          "children": [
+            {
+              "label": "Custom plugins",
+              "to": "framework/preact/guides/custom-plugins"
+            }
+          ]
+        },
         {
           "label": "solid",
           "children": []
@@ -108,6 +130,15 @@
             }
           ]
         },
+        {
+          "label": "preact",
+          "children": [
+            {
+              "label": "Preact Hooks",
+              "to": "framework/preact/reference/index"
+            }
+          ]
+        },
         {
           "label": "solid",
           "children": [
@@ -140,6 +171,19 @@
             }
           ]
         },
+        {
+          "label": "preact",
+          "children": [
+            {
+              "label": "Basic",
+              "to": "framework/preact/examples/basic"
+            },
+            {
+              "label": "Custom devtools",
+              "to": "framework/preact/examples/custom-devtools"
+            }
+          ]
+        },
         {
           "label": "solid",
           "children": [

docs/framework/preact/adapter.md

@@ -0,0 +1,16 @@
+---
+title: TanStack Devtools Preact Adapter
+id: adapter
+---
+
+If you are using TanStack Devtools in a Preact application, we recommend using the Preact Adapter. The Preact Adapter provides a set of easy-to-use hooks on top of the core Devtools utilities. If you find yourself wanting to use the core Devtools classes/functions directly, the Preact Adapter will also re-export everything from the core package.
+
+## Installation
+
+```sh
+npm install @tanstack/preact-devtools
+```
+
+## Preact Hooks
+
+TODO

docs/framework/preact/basic-setup.md

@@ -0,0 +1,69 @@
+---
+title: Basic setup
+id: basic-setup
+---
+
+TanStack devtools provides you with an easy to use and modular client that allows you to compose multiple devtools into one easy to use panel.
+
+## Setup
+
+Install the [TanStack Devtools](https://www.npmjs.com/package/@tanstack/preact-devtools) library, this will install the devtools core as well as provide you framework specific adapters.
+
+```bash
+npm i @tanstack/preact-devtools
+```
+
+Next in the root of your application import the `TanStackDevtools` from the required framework adapter (in this case @tanstack/preact-devtools).
+
+```tsx
+import { TanStackDevtools } from '@tanstack/preact-devtools'
+import { render } from 'preact'
+
+import App from './App'
+
+render(
+  <>
+    <App />
+
+    <TanStackDevtools />
+  </>,
+  document.getElementById('root')!,
+)
+```
+
+Import the desired devtools and provide it to the `TanStackDevtools` component along with a label for the menu.
+
+Currently TanStack offers:
+
+- `QueryDevtools`
+- `RouterDevtools`
+- `PacerDevtools`
+- `FormDevtools` [coming soon](https://github.com/TanStack/form/pull/1692)
+
+```tsx
+import { render } from 'preact'
+
+import { TanStackDevtools } from '@tanstack/preact-devtools'
+
+import App from './App'
+
+render(
+  <>
+    <App />
+
+    <TanStackDevtools
+      plugins={[
+        {
+          name: 'Your Plugin',
+          render: <YourPluginComponent />,
+        },
+      ]}
+    />
+  </>,
+  document.getElementById('root')!,
+)
+```
+
+Finally add any additional configuration you desire to the `TanStackDevtools` component, more information can be found under the [TanStack Devtools Configuration](../../configuration.md) section.
+
+A complete working example can be found in our [basic example](https://tanstack.com/devtools/latest/docs/framework/preact/examples/basic).

docs/framework/preact/guides/custom-plugins.md

@@ -0,0 +1,204 @@
+---
+title: Custom plugins
+id: custom-plugins
+---
+
+TanStack devtools allows you to create your own custom plugins by emitting and listening to our event bus.
+
+## Prerequisite
+
+This guide will walk you through a simple example where our library is a counter with a count history. A working example can be found in our [custom-plugin example](https://tanstack.com/devtools/latest/docs/framework/preact/examples/custom-plugin).
+
+This is our library code:
+
+counter.ts
+```tsx
+export function createCounter() {
+  let count = 0
+  const history = []
+
+  return {
+    getCount: () => count,
+    increment: () => {
+      count++
+      history.push(count)
+    },
+    decrement: () => {
+      count--
+      history.push(count)
+    },
+  };
+}
+```
+
+## Event Client Setup
+
+Install the [TanStack Devtools Event Client](https://www.npmjs.com/package/@tanstack/devtools-event-client) utils.
+
+```bash
+npm i @tanstack/devtools-event-client
+```
+
+First you will need to setup the `EventClient`.
+
+eventClient.ts
+```tsx
+import { EventClient } from '@tanstack/devtools-event-client'
+
+
+type EventMap = {
+  // The key of the event map is a combination of {pluginId}:{eventSuffix}
+  // The value is the expected type of the event payload
+  'custom-devtools:counter-state': { count: number, history: number[] }
+}
+
+class CustomEventClient extends EventClient<EventMap> {
+  constructor() {
+    super({
+      // The pluginId must match that of the event map key
+      pluginId: 'custom-devtools',
+    })
+  }
+}
+
+// This is where the magic happens, it'll be used throughout your application.
+export const DevtoolsEventClient = new CustomEventClient()
+```
+
+## Event Client Integration
+
+Now we need to hook our `EventClient` into the application code. This can be done in many way's, a useEffect that emits the current state, or a subscription to an observer, all that matters is that when you want to emit the current state you do the following.
+
+Our new library code will looks as follows:
+
+counter.ts
+```tsx
+import { DevtoolsEventClient } from './eventClient.ts'
+
+export function createCounter() {
+  let count = 0
+  const history: Array<number> = []
+
+  return {
+    getCount: () => count,
+    increment: () => {
+      count++
+      history.push(count)
+
+      // The emit eventSuffix must match that of the EventMap defined in eventClient.ts
+      DevtoolsEventClient.emit('counter-state', {
+        count,
+        history,
+      })
+    },
+    decrement: () => {
+      count--
+      history.push(count)
+
+      DevtoolsEventClient.emit('counter-state', {
+        count,
+        history,
+      })
+    },
+  }
+}
+```
+
+> [!IMPORTANT] 
+> `EventClient` is framework agnostic so this process will be the same regardless of framework or even in vanilla JavaScript.
+
+## Consuming The Event Client
+
+Now we need to create our devtools panel, for a simple approach write the devtools in the framework that the adapter is, be aware that this will make the plugin framework specific.
+
+> Because TanStack is framework agnostic we have taken a more complicated approach that will be explained in coming docs (if framework agnosticism is not a concern to you, you can ignore this).
+
+DevtoolsPanel.tsx
+```tsx
+import { useEffect, useState } from 'preact/hooks'
+import { DevtoolsEventClient } from './eventClient.ts'
+
+export function DevtoolPanel() {
+  const [state, setState] = useState<{ count: number; history: number[] } | undefined>()
+
+  useEffect(() => {
+    // subscribe to the emitted event
+    const cleanup = DevtoolsEventClient.on("counter-state", e => setState(e.payload))
+    return cleanup
+  }, [])
+
+  return (
+    <div>
+      <div>{state?.count}</div>
+      <div>{JSON.stringify(state?.history)}</div>
+    </div>
+  )
+}
+```
+
+## Application Integration
+
+This step follows what's shown in [basic-setup](../basic-setup.md)  for a more documented guide go check it out. As well as the complete [custom-devtools example](https://tanstack.com/devtools/latest/docs/framework/preact/examples/custom-devtools) in our examples section.
+
+Main.tsx
+```tsx
+import { render } from 'preact'
+import { DevtoolPanel } from './DevtoolPanel'
+
+render(
+  <>
+    <App />
+
+    <TanStackDevtools
+      plugins={[
+        {
+          // Name it what you like, this is how it will appear in the Menu
+          name: 'Custom devtools',
+          render: <DevtoolPanel />,
+        },
+      ]}
+    />
+  </>,
+  document.getElementById('root')!,
+)
+
+```
+
+## Debugging
+
+Both the `TanStackDevtools` component and the TanStack `EventClient` come with built in debug mode which will log to the console the emitted event as well as the EventClient status.
+
+TanStackDevtool's debugging mode can be activated like so:
+```tsx
+<TanStackDevtools
+  eventBusConfig={{ debug: true }}
+  plugins={[
+    {
+      // call it what you like, this is how it will appear in the Menu
+      name: 'Custom devtools',
+      render: <DevtoolPanel />,
+    },
+  ]}
+/>
+```
+
+Where as the EventClient's debug mode can be activated by:
+```tsx
+class CustomEventClient extends EventClient<EventMap> {
+  constructor() {
+    super({
+      pluginId: 'custom-devtools',
+      debug: true,
+    })
+  }
+}
+```
+
+Activating the debug mode will log to the console the current events that emitter has emitted or listened to. The EventClient will have appended `[tanstack-devtools:${pluginId}]` and the client will have appended `[tanstack-devtools:client-bus]`.
+
+Heres an example of both:
+```
+🌴 [tanstack-devtools:client-bus] Initializing client event bus
+
+🌴 [tanstack-devtools:custom-devtools-plugin] Registered event to bus custom-devtools:counter-state
+```