docs(react): custom plugin docs and custom plugin example

Author: harry-whorlow

docs/framework/react/custom-plugins.md

@@ -0,0 +1,166 @@
+---
+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/react/examples/custom-plugin).
+
+This is our library code:
+
+counter.ts
+```tsx
+export function createCounter() {
+  let count = 0;
+  const history = [];
+
+  return {
+    getCount: () => count,
+    increment: () => {
+      history.push(count);
+      count++;
+    },
+    decrement: () => {
+      history.push(count);
+      count--;
+    },
+  };
+}
+```
+
+## Event Client Setup
+
+Install the [TanStack Devtools Event Client](https://tanstack.com/devtools/) 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 FormEventClient()
+```
+
+## Event Client Integration
+
+Now we need to hook our `EventClient` into out 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 = [];
+
+  return {
+    getCount: () => count,
+    increment: () => {
+      const newCount = count++
+      history.push(count);
+
+      // The emit eventSuffix must match that of the EventMap defined in eventClient.ts
+      DevtoolsEventClient.emit('counter-state', {
+        count: newCount
+        history: history
+      })
+
+      count = newCount
+    },
+    decrement: () => {
+      const newCount = count--
+      history.push(count);
+
+      DevtoolsEventClient.emit('counter-state', {
+        count: newCount
+        history: history
+      })
+
+      count = newCount
+    },
+  };
+}
+```
+
+> **Important** `EventClient` is framework agnostic so this process will be the same regardless of framework or even vanilla in 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.ts
+```tsx
+import { DevtoolsEventClient } from './eventClient.ts'
+
+export function DevtoolPanel() {
+  const [state,setState] = useState();
+
+  useEffect(() => {
+    // subscribe to the emitted event
+    const cleanup = client.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] for a more documented guide go check it out. As well as the complete [custom-plugin example](https://tanstack.com/devtools/latest/docs/framework/react/examples/custom-plugin) in our examples section.
+
+Main.tsx
+```tsx
+import { DevtoolPanel } from './DevtoolPanel'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+
+    <TanstackDevtools
+      plugins={[
+        {
+          name: 'Custom devtools',
+          render: <DevtoolPanel />,
+        },
+      ]}
+    />
+  </StrictMode>,
+)
+
+```
+
+## Debugging

examples/react/custom-devtools/.eslintrc.cjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {
+  extends: ['plugin:react/recommended', 'plugin:react-hooks/recommended'],
+  rules: {
+    'react/no-children-prop': 'off',
+  },
+}
+
+module.exports = config

examples/react/custom-devtools/.gitignore

@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/react/custom-devtools/README.md

@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`

examples/react/custom-devtools/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+
+    <title>TanStack Form React Simple Example App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

examples/react/custom-devtools/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@tanstack/devtools-custom-devtools",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port=3001",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tanstack/react-devtools": "https://pkg.pr.new/TanStack/devtools/@tanstack/react-devtools@0a0219b",
+    "@tanstack/devtools-event-client": "https://pkg.pr.new/TanStack/devtools/@tanstack/devtools-event-client@11",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.5.2",
+    "vite": "^7.0.6"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

examples/react/custom-devtools/public/emblem-light.svg

@@ -0,0 +1,27 @@
+import { useState } from 'react'
+
+import { createCounter } from './counter'
+
+const counterInstance = createCounter()
+
+export default function App() {
+  const [count, setCount] = useState(counterInstance.getCount())
+
+  const increment = () => {
+    counterInstance.increment()
+    setCount(counterInstance.getCount())
+  }
+
+  const decrement = () => {
+    counterInstance.decrement()
+    setCount(counterInstance.getCount())
+  }
+
+  return (
+    <div>
+      <h2>Count: {count}</h2>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>−</button>
+    </div>
+  )
+}

examples/react/custom-devtools/src/App.tsx

@@ -0,0 +1,23 @@
+import { useEffect, useState } from 'react'
+import { DevtoolsEventClient } from './eventClient.ts'
+
+export default function CustomDevtoolPanel() {
+  const [state, setState] = useState<
+    { count: number; history: Array<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>
+  )
+}

examples/react/custom-devtools/src/CustomDevtoolsPanel.tsx

@@ -0,0 +1,33 @@
+import { DevtoolsEventClient } from './eventClient.ts'
+
+export function createCounter() {
+  let count = 0
+  const history: Array<number> = []
+
+  return {
+    getCount: () => count,
+    increment: () => {
+      const newCount = count + 1
+      history.push(count)
+
+      // The emit eventSuffix must match that of the EventMap defined in eventClient.ts
+      DevtoolsEventClient.emit('counter-state', {
+        count: newCount,
+        history: history,
+      })
+
+      count = newCount
+    },
+    decrement: () => {
+      const newCount = count - 1
+      history.push(count)
+
+      DevtoolsEventClient.emit('counter-state', {
+        count: newCount,
+        history: history,
+      })
+
+      count = newCount
+    },
+  }
+}