Merge branch 'main' into feat/bus-connection

Author: AlemTuzlak

docs/configuration.md

@@ -0,0 +1,151 @@
+---
+title: Configuration
+id: configuration
+---
+
+Both TanStack `DevTools` and `EventClient` can be configured.
+
+> **important** all configuration is optional unless marked (required)
+
+## Devtools Configuration
+
+With the `Devtools` there are two configuration objects, regardless of Frameworks these are the same and are provided to the Devtools through props.
+
+- `config` configuration for the devtool panel and interaction with it
+- `eventBusConfig` configuration for the event bus
+
+The `config` object is mainly focused around user interaction with the devtools panel and accepts the following properties:
+
+- `defaultOpen` - If the devtools are open by default
+
+```ts
+{defaultOpen: boolean}
+```
+
+- `hideUntilHover` - Hides the TanStack devtools trigger until hovered
+
+```ts
+{hideUntilHover: boolean}
+```
+
+- `position` - The position of the TanStack devtools trigger
+
+```ts
+{position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right'}
+```
+
+- `panelLocation` - The location of the devtools panel
+
+```ts
+{panelLocation: 'top' | 'bottom'}
+
+```
+
+- `openHotkey` - The hotkey set to open the devtools
+
+```ts
+type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift';
+type KeyboardKey = ModifierKey | (string & {});
+
+{openHotkey: Array<KeyboardKey>}
+```
+
+- `requireUrlFlag` - Requires a flag present in the url to enable devtools
+
+```ts
+{requireUrlFlag: boolean}
+
+```
+
+- `urlFlag` - The required flag that must be present in the url to enable devtools.
+
+```ts
+{urlFlag: string}
+```
+
+The `eventBusConfig` is configuration for the back bone of the devtools, the ``, and accepts the following properties:
+
+- `debug` - Enables debug mode for the EventBus
+
+```ts
+{debug: boolean}
+```
+
+- `connectToServerBus` - Optional flag to indicate if the devtools server event bus is available to connect to
+
+```ts
+{connectToServerBus: boolean}
+```
+
+- `port` - The port at which the client connects to the devtools server event bus
+
+```ts
+{port: number}
+```
+
+Put together here is an example in react:
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { FormDevtools } from '@tanstack/react-form'
+
+import { TanstackDevtools } from '@tanstack/react-devtools'
+
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+
+    <TanstackDevtools
+      config={{ hideUntilHover: true,  }}
+      eventBusConfig={{ debug: true }}
+      plugins={[
+        {
+          name: 'Tanstack Form',
+          render: <FormDevtools />,
+        },
+      ]}
+    />
+  </StrictMode>,
+)
+
+```
+
+## EventClient Configuration
+
+Configuration for the `EventClient` is as follows
+
+- `pluginId` (required) - The plugin identifier used by the event bus to direct events to listeners
+
+```ts
+{pluginId: string}
+```
+
+- `debug` - Enables debug mode for the EventClient
+
+```ts
+{debug: boolean}
+```
+
+Put together the `EventClient` configuration looks like:
+
+```tsx
+import { EventClient } from '@tanstack/devtools-event-client'
+
+type EventMap = {
+  'custom-devtools:custom-state': { state: string }
+}
+
+class customEventClient extends EventClient<EventMap> {
+  constructor() {
+    super({
+      debug: true,
+      pluginId: 'custom-devtools',
+    })
+  }
+}
+```
+
+More information about EventClient configuration can be found in our [custom-plugins example](https://tanstack.com/devtools/latest/docs/framework/react/examples/basic)

docs/framework/react/adapter.md renamed to docs/framework/react/guides/adapter.md

@@ -0,0 +1,198 @@
+---
+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: Array<number> = []
+
+  return {
+    getCount: () => count,
+    increment: () => {
+      history.push(count)
+
+      // The emit eventSuffix must match that of the EventMap defined in eventClient.ts
+      DevtoolsEventClient.emit('counter-state', {
+        count: count++,
+        history: history,
+      })
+    },
+    decrement: () => {
+      history.push(count)
+
+      DevtoolsEventClient.emit('counter-state', {
+        count: count--,
+        history: 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.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 it what you like, this is how it will appear in the Menu
+          name: 'Custom devtools',
+          render: <DevtoolPanel />,
+        },
+      ]}
+    />
+  </StrictMode>,
+)
+
+```
+
+## Debugging
+
+Both the TansTack `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
+```

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

@@ -6,7 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="theme-color" content="#000000" />
     <script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
-    <title>TanStack Devtools Example</title>
+    <title>Basic Example - TanStack Devtools</title>
   </head>
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>

docs/framework/solid/adapter.md renamed to docs/framework/solid/guides/adapter.md

@@ -22,7 +22,7 @@
   "devDependencies": {
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.2",
-    "@vitejs/plugin-react": "^4.4.1",
+    "@vitejs/plugin-react": "^4.5.2",
     "vite": "^7.0.6"
   },
   "browserslist": {

examples/react/basic/index.html

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