@tanstack/devtools-vite 0.5.4 → 0.5.5

package/bin/intent.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/devtools-vite",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "TanStack Vite plugin used to enhance the core devtools with additional functionalities",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -29,13 +29,18 @@
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=18"
   },
   "files": [
     "dist/",
-    "src"
+    "src",
+    "skills",
+    "bin"
   ],
   "peerDependencies": {
     "vite": "^6.0.0 || ^7.0.0"

package/skills/devtools-vite-plugin/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: devtools-vite-plugin
+description: >
+  Configure @tanstack/devtools-vite for source inspection (data-tsd-source,
+  inspectHotkey, ignore patterns), console piping (client-to-server,
+  server-to-client, levels), enhanced logging, server event bus (port, host,
+  HTTPS), production stripping (removeDevtoolsOnBuild), editor integration
+  (launch-editor, custom editor.open). Must be FIRST plugin in Vite config.
+  Vite ^6 || ^7 only.
+type: core
+library: tanstack-devtools
+library_version: '0.10.12'
+sources:
+  - 'TanStack/devtools:docs/vite-plugin.md'
+  - 'TanStack/devtools:docs/source-inspector.md'
+  - 'TanStack/devtools:packages/devtools-vite/src/plugin.ts'
+---
+
+Configure @tanstack/devtools-vite -- the Vite plugin that enhances TanStack Devtools with source inspection, console piping, enhanced logging, a server event bus, production stripping, editor integration, and a plugin marketplace. The plugin returns an array of sub-plugins, all using `enforce: 'pre'`, so it must be the FIRST plugin in the Vite config.
+
+## Installation and Basic Setup
+
+```ts
+// vite.config.ts
+import { devtools } from '@tanstack/devtools-vite'
+
+export default {
+  plugins: [
+    devtools(),
+    // ... other plugins AFTER devtools
+  ],
+}
+```
+
+Install as a dev dependency:
+
+```sh
+pnpm add -D @tanstack/devtools-vite
+```
+
+There is also a `defineDevtoolsConfig` helper for type-safe config objects:
+
+```ts
+import { devtools, defineDevtoolsConfig } from '@tanstack/devtools-vite'
+
+const config = defineDevtoolsConfig({
+  // fully typed options
+})
+
+export default {
+  plugins: [devtools(config)],
+}
+```
+
+## Exports
+
+From `packages/devtools-vite/src/index.ts`:
+
+- `devtools` -- main plugin factory, returns `Array<Plugin>`
+- `defineDevtoolsConfig` -- identity function for type-safe config
+- `TanStackDevtoolsViteConfig` -- config type (re-exported)
+- `ConsoleLevel` -- `'log' | 'warn' | 'error' | 'info' | 'debug'`
+
+## Architecture: Sub-Plugins
+
+`devtools()` returns an array of Vite plugins. Each has `enforce: 'pre'` and only activates when its conditions are met (dev mode, serve command, etc.).
+
+| Sub-plugin name                               | What it does                                                                                                       | When active                                                |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `@tanstack/devtools:inject-source`            | Babel transform adding `data-tsd-source` attrs to JSX                                                              | dev mode + `injectSource.enabled`                          |
+| `@tanstack/devtools:config`                   | Reserved for future config modifications                                                                           | serve command only                                         |
+| `@tanstack/devtools:custom-server`            | Starts ServerEventBus, registers middleware for open-source/console-pipe endpoints                                 | dev mode                                                   |
+| `@tanstack/devtools:remove-devtools-on-build` | Strips devtools imports/JSX from production bundles                                                                | build command or production mode + `removeDevtoolsOnBuild` |
+| `@tanstack/devtools:event-client-setup`       | Marketplace: listens for install/add-plugin events via devtoolsEventClient                                         | dev mode + serve + not CI                                  |
+| `@tanstack/devtools:console-pipe-transform`   | Injects runtime console-pipe code into entry files                                                                 | dev mode + serve + `consolePiping.enabled`                 |
+| `@tanstack/devtools:better-console-logs`      | Babel transform prepending source location to `console.log`/`console.error`                                        | dev mode + `enhancedLogs.enabled`                          |
+| `@tanstack/devtools:inject-plugin`            | Detects which file imports TanStackDevtools (for marketplace injection)                                            | dev mode + serve                                           |
+| `@tanstack/devtools:connection-injection`     | Replaces `__TANSTACK_DEVTOOLS_PORT__`, `__TANSTACK_DEVTOOLS_HOST__`, `__TANSTACK_DEVTOOLS_PROTOCOL__` placeholders | dev mode + serve                                           |
+
+## Subsystem Details
+
+### Source Injection
+
+Adds `data-tsd-source="<relative-path>:<line>:<column>"` attributes to every JSX opening element via Babel. This powers the "Go to Source" feature -- hold the inspect hotkey (default: Shift+Alt+Ctrl/Meta), hover over elements, click to open in editor.
+
+**Key behaviors:**
+
+- Skips `<Fragment>` and `<React.Fragment>`
+- Skips elements where the component's props parameter is spread (`{...props}`) -- this is because injecting the attribute would be overwritten by the spread
+- Skips files matching `injectSource.ignore.files` patterns
+- Skips components matching `injectSource.ignore.components` patterns
+- Patterns can be strings (matched via picomatch) or RegExp
+- Transform filter excludes `node_modules`, `?raw` imports, `/dist/`, `/build/`
+
+**Source files:** `packages/devtools-vite/src/inject-source.ts`, `packages/devtools-vite/src/matcher.ts`
+
+```ts
+devtools({
+  injectSource: {
+    enabled: true,
+    ignore: {
+      files: ['node_modules', /.*\.test\.(js|ts|jsx|tsx)$/],
+      components: ['InternalComponent', /.*Provider$/],
+    },
+  },
+})
+```
+
+### Console Piping
+
+Bidirectional console piping between client and server. Injects runtime code (IIFE) into entry files that:
+
+**Client side:**
+
+1. Wraps `console[level]` to batch and POST entries to `/__tsd/console-pipe`
+2. Opens an EventSource on `/__tsd/console-pipe/sse` to receive server logs
+3. Server logs appear in browser console with a purple `[Server]` prefix
+4. Client logs appear in terminal with a cyan `[Client]` prefix
+
+**Server side (SSR/Nitro):**
+
+1. Wraps `console[level]` to batch and POST entries to `<viteServerUrl>/__tsd/console-pipe/server`
+2. These are then broadcast to all SSE clients
+
+**Entry file detection:** looks for `<html` tag, `StartClient`, `hydrateRoot`, `createRoot`, or `solid-js/web` + `render(` in code.
+
+**Source files:** `packages/devtools-vite/src/virtual-console.ts`, `packages/devtools-vite/src/utils.ts` (middleware handlers)
+
+```ts
+devtools({
+  consolePiping: {
+    enabled: true,
+    levels: ['log', 'warn', 'error', 'info', 'debug'],
+  },
+})
+```
+
+### Enhanced Logging
+
+Babel transform that prepends source location info to `console.log()` and `console.error()` calls. In the browser, this renders as a clickable "Go to Source" link. On the server, it shows `LOG <path>:<line>:<column>` in chalk colors.
+
+The transform inserts a spread of a conditional expression: `...(typeof window === 'undefined' ? serverLogMessage : browserLogMessage)` as the first argument of the console call.
+
+**Source file:** `packages/devtools-vite/src/enhance-logs.ts`
+
+```ts
+devtools({
+  enhancedLogs: {
+    enabled: true, // default
+  },
+})
+```
+
+### Production Stripping
+
+Removes all devtools code from production builds. The transform:
+
+1. Finds files importing from these packages: `@tanstack/react-devtools`, `@tanstack/preact-devtools`, `@tanstack/solid-devtools`, `@tanstack/vue-devtools`, `@tanstack/devtools`
+2. Removes the import declarations
+3. Removes the JSX elements that use the imported components
+4. Cleans up leftover imports that were only used inside the removed JSX (e.g., plugin panel components)
+
+Active when: `command !== 'serve'` OR `config.mode === 'production'` (handles hosting providers like Cloudflare/Netlify that may not use `build` command but set mode to production).
+
+**Source file:** `packages/devtools-vite/src/remove-devtools.ts`
+
+```ts
+devtools({
+  removeDevtoolsOnBuild: true, // default
+})
+```
+
+### Server Event Bus
+
+A WebSocket + SSE server for devtools-to-client communication. Managed by `@tanstack/devtools-event-bus/server`.
+
+**Key behaviors:**
+
+- Default port: 4206
+- On EADDRINUSE: falls back to OS-assigned port (port 0)
+- When Vite uses HTTPS: piggybacks on Vite's httpServer instead of creating a standalone one (shares TLS certificate)
+- Uses global variables (`__TANSTACK_DEVTOOLS_SERVER__`, etc.) to survive HMR without restarting
+- The actual port is injected into client code via `__TANSTACK_DEVTOOLS_PORT__` placeholder replacement
+
+**Source file:** `packages/event-bus/src/server/server.ts`
+
+```ts
+devtools({
+  eventBusConfig: {
+    port: 4206, // default
+    enabled: true, // default; set false for storybook/vitest
+    debug: false, // default; logs internal bus activity
+  },
+})
+```
+
+### Editor Integration
+
+Uses `launch-editor` to open source files in the editor. Default editor is VS Code. The `editor.open` callback receives `(path, lineNumber, columnNumber)` as strings.
+
+The open-source flow: browser requests `/__tsd/open-source?source=<encoded-path:line:col>` --> Vite middleware parses source param --> calls `editor.open`.
+
+Supported editors via launch-editor: VS Code, WebStorm, Sublime Text, Atom, and more. For unsupported editors, provide a custom `editor.open` function.
+
+**Source file:** `packages/devtools-vite/src/editor.ts`
+
+```ts
+devtools({
+  editor: {
+    name: 'Cursor',
+    open: async (path, lineNumber, columnNumber) => {
+      // Custom editor open logic
+      // path is the absolute file path
+      // lineNumber and columnNumber are strings or undefined
+    },
+  },
+})
+```
+
+### Plugin Marketplace
+
+When the dev server is running, listens for events via `devtoolsEventClient`:
+
+- `install-devtools` -- runs package manager install, then auto-injects plugin into devtools setup file
+- `add-plugin-to-devtools` -- injects plugin import and JSX/function call into the file containing `<TanStackDevtools>`
+- `bump-package-version` -- updates a package to a minimum version
+- `mounted` -- sends package.json and outdated deps to the UI
+
+Auto-detection of the devtools setup file: the `inject-plugin` sub-plugin scans transforms for files importing from `@tanstack/react-devtools`, `@tanstack/solid-devtools`, `@tanstack/vue-devtools`, etc., and stores the file ID.
+
+**Source files:** `packages/devtools-vite/src/inject-plugin.ts`, `packages/devtools-vite/src/package-manager.ts`
+
+## Common Mistakes
+
+### 1. Not placing devtools() first in Vite plugins (HIGH)
+
+All sub-plugins use `enforce: 'pre'`. They must transform code before framework plugins (React, Vue, Solid, etc.) process it. If devtools is not first, source injection and enhanced logs may silently fail because framework transforms remove the raw JSX before devtools can annotate it.
+
+```ts
+// WRONG
+export default {
+  plugins: [
+    react(),
+    devtools(), // too late -- react() already transformed JSX
+  ],
+}
+
+// CORRECT
+export default {
+  plugins: [devtools(), react()],
+}
+```
+
+### 2. Using devtools-vite with non-Vite bundlers (HIGH)
+
+`@tanstack/devtools-vite` has a peer dependency on `vite ^6.0.0 || ^7.0.0`. It uses Vite-specific APIs (`configureServer`, `handleHotUpdate`, `transform` with filter objects, `Plugin` type). It will not work with webpack, rspack, esbuild, or other bundlers. For non-Vite setups, use `@tanstack/devtools-event-bus` client directly without the Vite plugin.
+
+### 3. Expecting Vite plugin features in production (MEDIUM)
+
+Source injection, console piping, enhanced logging, the server event bus, and the marketplace only operate during development (`config.mode === 'development'` and `command === 'serve'`). In production builds, the only active sub-plugin is `remove-devtools-on-build` (which strips devtools code). Do not rely on any of these features being available at runtime in production.
+
+### 4. Source injection on spread-props elements (MEDIUM)
+
+The Babel transform in `inject-source.ts` explicitly skips any JSX element that has a `{...props}` spread where `props` is the component's parameter name. This is intentional -- the spread would overwrite the injected `data-tsd-source` attribute. If source inspection doesn't work for a specific component, check if it spreads its props parameter.
+
+```tsx
+// data-tsd-source will NOT be injected on <div> here
+const MyComponent = (props) => {
+  return <div {...props}>content</div>
+}
+```
+
+### 5. Event bus port conflict in multi-project setups (MEDIUM)
+
+The default event bus port is 4206. When running multiple Vite dev servers concurrently (monorepo), the second server will hit EADDRINUSE. The event bus handles this by falling back to an OS-assigned port (port 0), and the actual port is injected via placeholder replacement. However, if you need predictable ports (e.g., for firewall rules), set different ports explicitly:
+
+```ts
+// Project A
+devtools({ eventBusConfig: { port: 4206 } })
+
+// Project B
+devtools({ eventBusConfig: { port: 4207 } })
+```
+
+## Internal Middleware Endpoints
+
+These are registered on the Vite dev server (not the event bus server):
+
+| Endpoint                                    | Method | Purpose                                                   |
+| ------------------------------------------- | ------ | --------------------------------------------------------- |
+| `/__tsd/open-source?source=<path:line:col>` | GET    | Opens file in editor, returns HTML that closes the window |
+| `/__tsd/console-pipe`                       | POST   | Receives client console entries (batched JSON)            |
+| `/__tsd/console-pipe/server`                | POST   | Receives server-side console entries                      |
+| `/__tsd/console-pipe/sse`                   | GET    | SSE stream for broadcasting server logs to browser        |
+
+## Cross-References
+
+- **devtools-app-setup** -- How to set up `<TanStackDevtools>` in your app (must be done before the Vite plugin provides value)
+- **devtools-production** -- Details on production stripping configuration and keeping devtools in production builds
+
+## Key Source Files
+
+- `packages/devtools-vite/src/plugin.ts` -- Main plugin factory with all sub-plugins and config type
+- `packages/devtools-vite/src/inject-source.ts` -- Babel transform for data-tsd-source injection
+- `packages/devtools-vite/src/enhance-logs.ts` -- Babel transform for enhanced console logs
+- `packages/devtools-vite/src/remove-devtools.ts` -- Production stripping transform
+- `packages/devtools-vite/src/virtual-console.ts` -- Console pipe runtime code generator
+- `packages/devtools-vite/src/editor.ts` -- Editor config type and launch-editor integration
+- `packages/devtools-vite/src/inject-plugin.ts` -- Marketplace plugin injection into devtools setup file
+- `packages/devtools-vite/src/utils.ts` -- Middleware request handling and helpers
+- `packages/devtools-vite/src/matcher.ts` -- Picomatch/RegExp pattern matcher
+- `packages/event-bus/src/server/server.ts` -- ServerEventBus implementation (WebSocket + SSE + EADDRINUSE fallback)

package/skills/devtools-vite-plugin/references/vite-options.md

@@ -0,0 +1,413 @@
+# @tanstack/devtools-vite Options Reference
+
+Complete configuration reference for the `devtools()` Vite plugin. All options are optional -- calling `devtools()` with no arguments uses sensible defaults.
+
+**Source of truth:** `packages/devtools-vite/src/plugin.ts` (type `TanStackDevtoolsViteConfig`)
+
+## Top-Level Config Type
+
+```ts
+import type { Plugin } from 'vite'
+
+type ConsoleLevel = 'log' | 'warn' | 'error' | 'info' | 'debug'
+
+type TanStackDevtoolsViteConfig = {
+  editor?: EditorConfig
+  eventBusConfig?: ServerEventBusConfig & { enabled?: boolean }
+  enhancedLogs?: { enabled: boolean }
+  removeDevtoolsOnBuild?: boolean
+  logging?: boolean
+  injectSource?: {
+    enabled: boolean
+    ignore?: {
+      files?: Array<string | RegExp>
+      components?: Array<string | RegExp>
+    }
+  }
+  consolePiping?: {
+    enabled?: boolean
+    levels?: Array<ConsoleLevel>
+  }
+}
+
+// Returns Array<Plugin> (9 sub-plugins)
+declare function devtools(args?: TanStackDevtoolsViteConfig): Array<Plugin>
+
+// Identity function for type-safe config objects
+declare function defineDevtoolsConfig(
+  config: TanStackDevtoolsViteConfig,
+): TanStackDevtoolsViteConfig
+```
+
+---
+
+## `injectSource`
+
+Controls source injection -- the Babel transform that adds `data-tsd-source` attributes to JSX elements for the "Go to Source" feature.
+
+| Field               | Type                      | Default     | Description                                                                                                                                                                                              |
+| ------------------- | ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`           | `boolean`                 | `true`      | Whether to inject `data-tsd-source` attributes into JSX elements during development.                                                                                                                     |
+| `ignore`            | `object`                  | `undefined` | Patterns to exclude from injection.                                                                                                                                                                      |
+| `ignore.files`      | `Array<string \| RegExp>` | `[]`        | File paths to skip. Strings are matched via picomatch glob syntax. RegExp patterns are tested directly. Matched against the file's path relative to `process.cwd()`.                                     |
+| `ignore.components` | `Array<string \| RegExp>` | `[]`        | Component/element names to skip. Strings are matched via picomatch. RegExp patterns are tested directly. Matched against the JSX element name (e.g., `"div"`, `"MyComponent"`, `"Namespace.Component"`). |
+
+**Built-in exclusions (hardcoded in transform filter, not configurable):**
+
+- `node_modules`
+- `?raw` imports
+- `/dist/` paths
+- `/build/` paths
+- `<Fragment>` and `<React.Fragment>` elements
+- Elements with `{...propsParam}` spread (where `propsParam` is the function's parameter name)
+
+**Example:**
+
+```ts
+devtools({
+  injectSource: {
+    enabled: true,
+    ignore: {
+      files: ['node_modules', /.*\.test\.(js|ts|jsx|tsx)$/, '**/generated/**'],
+      components: ['InternalComponent', /.*Provider$/, /^Styled/],
+    },
+  },
+})
+```
+
+---
+
+## `consolePiping`
+
+Controls bidirectional console log piping between client (browser) and server (terminal/SSR runtime).
+
+| Field     | Type                  | Default                                     | Description                                                                                                                                                                |
+| --------- | --------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled` | `boolean`             | `true`                                      | Whether to enable console piping. When enabled, client `console.*` calls are forwarded to the terminal, and server `console.*` calls are forwarded to the browser console. |
+| `levels`  | `Array<ConsoleLevel>` | `['log', 'warn', 'error', 'info', 'debug']` | Which console methods to intercept and pipe. `ConsoleLevel` is `'log' \| 'warn' \| 'error' \| 'info' \| 'debug'`.                                                          |
+
+**Runtime behavior:**
+
+- Client batches entries (max 50, flush after 100ms) and POSTs to `/__tsd/console-pipe`
+- Server batches entries (max 20, flush after 50ms) and POSTs to `<viteServerUrl>/__tsd/console-pipe/server`
+- Browser subscribes to server logs via `EventSource` at `/__tsd/console-pipe/sse`
+- Self-referential log messages (containing `[TSD Console Pipe]` or `[@tanstack/devtools`) are excluded to prevent recursion
+- Flushes remaining batch on `beforeunload` (client only)
+
+**Example:**
+
+```ts
+// Only pipe errors and warnings
+devtools({
+  consolePiping: {
+    enabled: true,
+    levels: ['error', 'warn'],
+  },
+})
+
+// Disable entirely
+devtools({
+  consolePiping: {
+    enabled: false,
+  },
+})
+```
+
+---
+
+## `enhancedLogs`
+
+Controls the Babel transform that prepends source location information to `console.log()` and `console.error()` calls.
+
+| Field     | Type      | Default | Description                                                                                                                                                                                           |
+| --------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled` | `boolean` | `true`  | Whether to enhance console.log and console.error with source location. When enabled, each log call gets a clickable "Go to Source" link in the browser and a file:line:column prefix in the terminal. |
+
+**What gets transformed:**
+
+- Only `console.log(...)` and `console.error(...)` calls (not `warn`, `info`, `debug`)
+- Skips `node_modules`, `?raw`, `/dist/`, `/build/`
+- Skips files that don't contain the string `console.`
+
+**Browser output format:**
+
+```
+%cLOG%c %cGo to Source: http://localhost:5173/__tsd/open-source?source=...%c
+ -> <original args>
+```
+
+**Server output format (chalk):**
+
+```
+LOG /src/components/Header.tsx:26:13
+ -> <original args>
+```
+
+**Example:**
+
+```ts
+devtools({
+  enhancedLogs: {
+    enabled: false, // disable source-annotated logs
+  },
+})
+```
+
+---
+
+## `removeDevtoolsOnBuild`
+
+Controls whether devtools code is stripped from production builds.
+
+| Field                   | Type      | Default | Description                                                                   |
+| ----------------------- | --------- | ------- | ----------------------------------------------------------------------------- |
+| `removeDevtoolsOnBuild` | `boolean` | `true`  | When true, removes all devtools imports and JSX usage from production builds. |
+
+**Packages stripped:**
+
+- `@tanstack/react-devtools`
+- `@tanstack/preact-devtools`
+- `@tanstack/solid-devtools`
+- `@tanstack/vue-devtools`
+- `@tanstack/devtools`
+
+**Activation condition:** Active when `command !== 'serve'` OR `config.mode === 'production'`. This dual check supports hosting providers (Cloudflare, Netlify, Heroku) that may not use the `build` command but always set mode to `production`.
+
+**What gets removed:**
+
+1. Import declarations from the listed packages
+2. JSX elements using the imported component names
+3. Leftover imports that were only referenced inside the removed JSX (e.g., plugin panel components referenced in the `plugins` prop)
+
+**Example:**
+
+```ts
+// Keep devtools in production (for staging/QA environments)
+devtools({
+  removeDevtoolsOnBuild: false,
+})
+```
+
+---
+
+## `logging`
+
+Controls the plugin's own console output.
+
+| Field     | Type      | Default | Description                                                                                                 |
+| --------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `logging` | `boolean` | `true`  | Whether the devtools plugin logs status messages to the terminal (e.g., "Removed devtools code from: ..."). |
+
+**Example:**
+
+```ts
+devtools({
+  logging: false, // suppress devtools plugin output
+})
+```
+
+---
+
+## `eventBusConfig`
+
+Configuration for the server event bus that handles devtools-to-client communication via WebSocket and SSE.
+
+| Field        | Type             | Default                                                     | Description                                                                                                                                                                                                                                                                                |
+| ------------ | ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`    | `boolean`        | `true`                                                      | Whether to start the server event bus. Set to `false` when running devtools in environments that don't need it (e.g., Storybook, Vitest). This field is specific to the Vite plugin wrapper; it is not part of `ServerEventBusConfig` from `@tanstack/devtools-event-bus/server`.          |
+| `port`       | `number`         | `4206`                                                      | Preferred port for the event bus server. If the port is in use (EADDRINUSE), the bus falls back to an OS-assigned port (port 0).                                                                                                                                                           |
+| `host`       | `string`         | Derived from `server.host` in Vite config, or `'localhost'` | Hostname to bind the event bus server to.                                                                                                                                                                                                                                                  |
+| `debug`      | `boolean`        | `false`                                                     | When true, logs internal event bus activity (connections, dispatches, etc.) to the console.                                                                                                                                                                                                |
+| `httpServer` | `HttpServerLike` | `undefined`                                                 | An external HTTP server to attach to instead of creating a standalone one. The Vite plugin automatically sets this when HTTPS is enabled (uses `server.httpServer` from Vite) so WebSocket/SSE connections share the same TLS certificate. You generally do not need to set this manually. |
+
+**`HttpServerLike` interface:**
+
+```ts
+interface HttpServerLike {
+  on: (event: string, listener: (...args: Array<any>) => void) => this
+  removeListener: (
+    event: string,
+    listener: (...args: Array<any>) => void,
+  ) => this
+  address: () =>
+    | { port: number; family: string; address: string }
+    | string
+    | null
+}
+```
+
+**`ServerEventBusConfig` type (from `@tanstack/devtools-event-bus/server`):**
+
+```ts
+interface ServerEventBusConfig {
+  port?: number | undefined
+  host?: string | undefined
+  debug?: boolean | undefined
+  httpServer?: HttpServerLike | undefined
+}
+```
+
+**HTTPS behavior:** When `server.https` is configured in Vite, the plugin passes `server.httpServer` as `httpServer` to the event bus. This causes the bus to piggyback on Vite's server rather than creating a standalone HTTP server, ensuring WebSocket and SSE connections use the same TLS certificate.
+
+**Port fallback:** The `ServerEventBus.start()` method tries the configured port first. On `EADDRINUSE`, it retries with port 0 (OS-assigned). The actual port is stored and injected into client code via `__TANSTACK_DEVTOOLS_PORT__` placeholder.
+
+**Example:**
+
+```ts
+devtools({
+  eventBusConfig: {
+    port: 4300,
+    enabled: true,
+    debug: true, // see all event bus activity
+  },
+})
+
+// Disable for Storybook
+devtools({
+  eventBusConfig: {
+    enabled: false,
+  },
+})
+```
+
+---
+
+## `editor`
+
+Configuration for the "open in editor" functionality used by the source inspector.
+
+| Field  | Type                                                                                      | Default                              | Description                                                                                                                                                     |
+| ------ | ----------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` | `string`                                                                                  | `'VSCode'`                           | Name of the editor, used for debugging/logging purposes.                                                                                                        |
+| `open` | `(path: string, lineNumber: string \| undefined, columnNumber?: string) => Promise<void>` | Uses `launch-editor` to open VS Code | Callback function that opens a file in the editor. The `path` is an absolute file path. `lineNumber` and `columnNumber` are strings (not numbers) or undefined. |
+
+**`EditorConfig` type (from `packages/devtools-vite/src/editor.ts`):**
+
+```ts
+type EditorConfig = {
+  name: string
+  open: (
+    path: string,
+    lineNumber: string | undefined,
+    columnNumber?: string,
+  ) => Promise<void>
+}
+```
+
+**Default implementation:**
+
+```ts
+const DEFAULT_EDITOR_CONFIG: EditorConfig = {
+  name: 'VSCode',
+  open: async (path, lineNumber, columnNumber) => {
+    const launch = (await import('launch-editor')).default
+    launch(
+      `${path.replaceAll('$', '\\$')}${lineNumber ? `:${lineNumber}` : ''}${columnNumber ? `:${columnNumber}` : ''}`,
+      undefined,
+      (filename, err) => {
+        console.warn(`Failed to open ${filename} in editor: ${err}`)
+      },
+    )
+  },
+}
+```
+
+**Supported editors via launch-editor:** VS Code, WebStorm, IntelliJ IDEA, Sublime Text, Atom, Vim, Emacs, and more. Full list: https://github.com/yyx990803/launch-editor#supported-editors
+
+**Example -- custom editor:**
+
+```ts
+devtools({
+  editor: {
+    name: 'Neovim',
+    open: async (path, lineNumber, columnNumber) => {
+      const { execFile } = await import('node:child_process')
+      const lineArg = lineNumber ? `+${lineNumber}` : ''
+      execFile('nvim', [lineArg, path].filter(Boolean))
+    },
+  },
+})
+```
+
+---
+
+## Connection Placeholders
+
+These are not user-facing config options but are relevant if you work on `@tanstack/devtools` internals. The `connection-injection` sub-plugin replaces these string literals in `@tanstack/devtools*` and `@tanstack/event-bus` source code during dev:
+
+| Placeholder                      | Replaced with                       | Fallback      |
+| -------------------------------- | ----------------------------------- | ------------- |
+| `__TANSTACK_DEVTOOLS_PORT__`     | Actual event bus port (number)      | `4206`        |
+| `__TANSTACK_DEVTOOLS_HOST__`     | Event bus hostname (JSON string)    | `"localhost"` |
+| `__TANSTACK_DEVTOOLS_PROTOCOL__` | `"http"` or `"https"` (JSON string) | `"http"`      |
+
+---
+
+## Full Configuration Example
+
+```ts
+import { devtools } from '@tanstack/devtools-vite'
+
+export default {
+  plugins: [
+    devtools({
+      // Source injection for Go to Source feature
+      injectSource: {
+        enabled: true,
+        ignore: {
+          files: [/.*\.stories\.(js|ts|jsx|tsx)$/],
+          components: [/^Styled/, 'InternalWrapper'],
+        },
+      },
+
+      // Bidirectional console piping
+      consolePiping: {
+        enabled: true,
+        levels: ['log', 'warn', 'error'],
+      },
+
+      // Enhanced console.log/error with source locations
+      enhancedLogs: {
+        enabled: true,
+      },
+
+      // Strip devtools from production builds
+      removeDevtoolsOnBuild: true,
+
+      // Plugin console output
+      logging: true,
+
+      // Server event bus
+      eventBusConfig: {
+        port: 4206,
+        enabled: true,
+        debug: false,
+      },
+
+      // Editor integration (default: VS Code via launch-editor)
+      // editor: { name: 'VSCode', open: async (path, line, col) => { ... } },
+    }),
+    // ... framework plugin (react(), vue(), solid(), etc.)
+  ],
+}
+```
+
+---
+
+## Defaults Summary
+
+| Option                   | Default Value                               |
+| ------------------------ | ------------------------------------------- |
+| `injectSource.enabled`   | `true`                                      |
+| `injectSource.ignore`    | `undefined` (no ignores)                    |
+| `consolePiping.enabled`  | `true`                                      |
+| `consolePiping.levels`   | `['log', 'warn', 'error', 'info', 'debug']` |
+| `enhancedLogs.enabled`   | `true`                                      |
+| `removeDevtoolsOnBuild`  | `true`                                      |
+| `logging`                | `true`                                      |
+| `eventBusConfig.enabled` | `true`                                      |
+| `eventBusConfig.port`    | `4206`                                      |
+| `eventBusConfig.host`    | Vite's `server.host` or `'localhost'`       |
+| `eventBusConfig.debug`   | `false`                                     |
+| `editor.name`            | `'VSCode'`                                  |
+| `editor.open`            | Uses `launch-editor`                        |