devtools/docs/architecture.md
Alem Tuzlak a46d1f5959
feat: redesign TanStack Devtools workbench (#492)
* fix: update devtools trigger logo

* docs: add TanStack Devtools branding design

* feat: redesign TanStack Devtools workbench

* fix: refine TanStack Devtools workbench

* ci: apply automated fixes

* fix(devtools): polish the Workbench UI and fix its interaction regressions

Separate chrome from canvas: the header and the secondary strips paint the
brand surface and close with a translucent ink hairline, while destination
content and plugin panes paint the workspace surface. `border.decorative` is
the cream brand colour, so any rule drawn on the chrome band was invisible.

Align everything to one gutter. `WORKBENCH_GUTTER` (16px, 12px below 430px) is
now the single inline gutter for the header, the strips and each destination's
content, which previously started at 0, 8, 12 and 32px depending on the tab.

Trade competing accents for the semantic theme:
- The Marketplace partnership banner was a saturated block; it is brand paper
  with a charcoal rule. Tag filters lost their outlined container, section
  headings stopped being cards, and emoji labels are plain text.
- SEO social cards were each outlined in their network's brand colour. The
  colour survives as a small dot; the card border is neutral. The tab also ran
  on the legacy grey ramp and is on the semantic theme now.
- Featured and active plugin cards keep the neutral outline and let their badge
  carry the state; "Active" was wearing the info colour.

The palm emblem is inline SVG instead of a raster filtered with
`brightness(2.5)` to fake dark mode, so it stays sharp and takes its colour
from the theme. Plugin destinations get a real empty state.

Fold the subheader, not the panel. A pull tab on the strip's bottom edge
animates the strip's height to zero and drops to the header's edge; the panel
height, the header and the destination content are untouched, and the tab is
only rendered where a strip exists. Folded, the strip is inert.

Interaction fixes:
- The resize handle had grown to 24px at `top: -10px`, covering the top 14px of
  the 36px header, so a press aimed at a header button started a resize. It is
  a thin bar on the panel edge again.
- The Marketplace settings drawer was `position: fixed` and covered the host
  page instead of the Workbench. The marketplace is a shell with an inner
  scroll region and the drawer is absolute inside it.
- Scroll gestures chained on to the host page. The outermost scroller in each
  destination contains them; deliberately not their descendants, since a plugin
  nests empty `overflow: auto` wrappers that must chain up to the pane.
- Plugin mounts are their own positioning context. Plugins position chrome
  absolutely from a statically positioned root, so it resolved against the
  whole Workbench and painted over our header.
- The floating trigger and drawer toggle replaced their brand fill with a
  translucent state colour on hover, making them vanish over the page.
- The "New" ribbon overlapped the card icon; it is an inline pill.
- HotkeyConfig never rendered its `title`, so each shortcut was headed by its
  own description, and its modifier chips were styled as success.

Interactive controls animate over 0.3s, with one reduced-motion guard scoped to
the core-owned `data-tsd-control` / `data-tsd-surface` markers.

Also removes 41 dead style blocks, which took nearly all remaining legacy-grey
colour usage with them, and a duplicated `plugin-marketplace` test id.

* fix(devtools): stop the SEO head watcher looping and unblock CI

The `Test` job died with a JavaScript heap OOM and the `E2e` job failed on all
eight apps. Two separate causes.

The head watcher looped. `createHeadChanges` observes attributes and character
data across the whole `<head>` subtree, and goober rewrites a `<style>` tag
there on every `css()` call — it even re-stamps the tag's `nonce` attribute each
time. So an SEO analysis re-rendered, the re-render emitted CSS, the CSS mutated
`<head>`, and the analysis ran again. The loop is synchronous, so no test
timeout could break it and the worker ran to the 4 GB heap limit. Stylesheets
carry no SEO metadata, so they are filtered out.

jsdom multiplied goober's stylesheets. goober finds its single
`<style id="_goober">` through `window._goober`, the global a browser creates
for any element with an `id`. jsdom does not do that for `<style>`, so goober
appended a new sheet on every `css()` call — about 2500 per Workbench mount,
never removed. Test 1 took 0.9s and test 20 took 21s. The test setup now gives
goober the global a browser would have: 2504 sheets per mount become 8, and the
package's 236 tests run in 38s instead of running out of memory.

That let `workbench.test.tsx` finish for the first time, which exposed nine
assertions still describing the pre-polish design — the header's trailing
gutter, the strip's 8px gutter, the 24px resize handle, a fixed 44px grid row,
the strip unmounting when folded, and the SEO label foregrounds. Each now
matches the shipped Workbench.

The redesign also dropped the test hooks `@tanstack/devtools-e2e` locates the
panel and header controls with, which is why every e2e app failed on
`openViaTrigger()`. The header carries them again and the tab assertions read
`data-tsd-selected` instead of the `active` class the old tabs used.

* feat(devtools): plugin workspace with splits, stacked tabs, drag and resize (#493)

* feat(devtools): add the plugin workspace layout tree

The workspace layout becomes a tree of splits and tab groups so plugins can be
arranged in rows, columns and stacks instead of one equal-width flex row. This
commit is the maths only: no UI is wired up and no dependency is added yet.

Everything in `layout-tree.ts` is pure and imports nothing. That is deliberate.
jsdom has no layout engine, so `getBoundingClientRect` returns zeros, and rect
maths verified through the DOM would only be verifying its own mocks. Keeping it
here makes it exhaustively testable — 67 cases in 58ms — and keeps the layout
logic out of the components.

Every returned tree upholds the same invariants: a group has at least one tab, a
split has at least two children, sizes match the child count and sum to 1, the
active index names a real tab, and a plugin id appears at most once. `prune`
restores them bottom up after any edit, so closing a tab can collapse an emptied
group, unwrap a single-child split, and flatten a same-direction nested split
without the callers knowing.

`repairLayout` cannot throw. A malformed layout is a data problem, the same as
the unknown plugin ids that are already pruned on load, and it must not stop the
panel from opening; storage *access* errors still propagate. It prunes unknown
and duplicated ids, renormalises sizes, clamps the active index, and falls back
to salvaging whatever plugin ids it can find from an unrecognisable shape so a
bad write costs the arrangement but not the open plugins. The hostile-input test
caught a real stack overflow on a self-referencing object, so reads are depth
capped and the salvage walk tracks visited objects.

Design and the decisions behind it, including the measured bundle cost of each
neodrag primitive, are in
docs/superpowers/specs/2026-08-07-plugin-layout-tree-design.md.

* feat(devtools): make the layout tree the stored truth for open plugins

`state.activePlugins` is replaced by `state.layout`. The tree is now the only
record of which plugins are open, and `activePlugins` is a memo that flattens it,
so the two cannot disagree. Rendering is unchanged: the flattened order feeds the
same flex row, so this commit moves the state without moving any pixels.

Hydration migrates and repairs. State written before the tree reopens as a single
group in the stored order, an existing tree wins over the superseded key, and
everything goes through `repairLayout`, which prunes unknown plugin ids exactly
as the old `activePlugins` filter did. The result is written back once so the
migration does not repeat. Storage *access* errors still propagate.

Two things the existing tests caught, both worth recording.

`flattenTabs` builds a fresh array each call, so a bare memo made every unrelated
store write look like a change and re-ran each plugin's `render` — the activation
order test failed with a duplicated entry. The memo now compares contents.

`plugin.destroy` cannot yet hang off the pane's own `onCleanup`, which is where
the design puts it. The panes live inside the destination-switched subtree, so
navigating to Marketplace unmounts them and would destroy every open plugin —
"moves among Marketplace and core destinations without plugin destruction" failed
immediately. Teardown stays on the close path until the panes live in a container
that outlives the navigation, which is the next commit.

`MAX_ACTIVE_PLUGINS` stays at 3 for now. Raising it to 9 only makes sense once
the workspace can split and scroll, otherwise nine panes share one flex row.

* feat(devtools): render the workspace from the layout tree, up to 9 panes

The plugin panes move out of the destination-switched subtree into a workspace
that is mounted once and hidden rather than unmounted. Each pane is a direct
child of that workspace for its whole life and is placed with offsets computed
from the tree, so no drag, split or resize ever re-parents it. That is what stops
an iframe plugin reloading and a canvas plugin losing its context — the React
basic example registers a plugin whose whole body is an iframe.

Because the workspace outlives navigation, `plugin.destroy` finally moves to the
pane's own `onCleanup`: exactly once, however the pane was closed, and before the
node is detached so the plugin can still tidy up. Removing the call from the
close path at the same time was necessary, not tidying — with both in place every
close destroyed twice, which the lifecycle test caught.

`MAX_ACTIVE_PLUGINS` goes from 3 to 9. Panes can now split and stack, so the cap
limits how many are open rather than how many fit across.

Splitters, tab bars with per-tab close controls, drop-zone highlighting and full
keyboard operation all arrive with it. Each gutter is a real focusable
`role="separator"` driven by the same arrow/Home/End pattern as the whole-panel
resizer, and a tab can be picked up with Enter, moved with the arrows and dropped
with Enter, so nothing needs a pointer. A drop that has no room to split becomes
a stacked tab instead of being refused.

Three things worth recording.

`appendPane` exists because `splitAt` was wrong for opening from the strip: it
halves the last pane, so three plugins came out 1/2, 1/4, 1/4. Panes opened side
by side should match, and a test now pins the thirds.

The move hint's id was `${PLUGIN_CONTAINER_ID}-move-hint`, which matches the
`[id^="plugin-container-"]` selector the tests use and counted as a phantom pane.
PLUGIN_CONTAINER_ID is a public export and the shared prefix of every pane id;
nothing else may borrow it.

The tab bar is not a `role="tablist"`. Its arrow keys move a pane rather than
walking the tabs, so claiming the role would promise a keyboard contract this
does not implement. Selection is `aria-pressed`, the close control is a sibling
button rather than nested inside the tab, targets are 24px, and the state of a
move is narrated through a live region because `aria-grabbed` is deprecated.

* feat(devtools): drag panes from the strip, hold to drag, and raise the cap to 18

Builds on the workspace with the interactions that make it usable, and fixes what
turned up once it was driven by hand rather than by tests.

Dragging. A press only becomes a drag after being **held** for 500ms. A movement
threshold was tried first and was wrong: any distance small enough to feel
responsive is also small enough that ordinary click jitter crosses it, so clicking
a stacked tab resolved a drop target from the pointer sitting over the tab bar and
split the pane straight back out. Holding is unambiguous — a click selects, a press
picks up. Dropping on a tab bar now always means "put it in this group" rather than
splitting its top edge, so the two gestures never compete for the same few pixels.

The tab being carried follows the cursor and every surface shows the grabbing
cursor while it does. The preview is portalled to the body because `MainPanel` sets
a transform, which makes it a containing block, so a `position: fixed` child
resolved against the panel and was clipped by the workspace's overflow.

Plugins strip. Entries can be held and dragged into the workspace to place a pane
where you want it instead of appending it, including onto an empty workspace, where
it takes the whole area. The strip now lists only the plugins that are *not* open,
so each plugin has exactly one control: its strip entry while closed, its pane tab
once open. It folds itself away when everything is open and returns when a plugin
closes.

`MAX_ACTIVE_PLUGINS` goes 9 -> 18. The tests were already pinned to the constant
rather than a literal, so this was a one-line change.

Three fixes worth naming.

The workspace measured itself once at mount. A hidden element measures zero, every
rect derived from a zero box is zero, and hit-testing then silently found nothing —
so a drag did nothing at all rather than looking broken. It re-measures when the
panel opens or the destination returns, ignores zero measurements, and measures
again at the start of every drag.

The strip's click-suppression flag was sticky. A drag that ends away from the entry
produces no `click` at all, so the flag survived and swallowed the *next* genuine
click, which is why opening a plugin started taking several attempts. It resets on
each press.

The strip-to-workspace handoff moved from module-level state onto the context. This
package ships several bundles, so two components can hold different copies of the
same module and never see each other's writes.

Two e2e cases are `test.fixme` rather than deleted: both drags that start from a
strip entry work with real pointer input, verified by hand in two apps, but do not
trigger under Playwright's synthetic mouse. Each carries a comment saying what is
covered elsewhere and what is left unproven.

* fix(devtools): unbreak CI — knip, duplicated Vue plugins, unstable gutters

Three separate causes behind the red `Test` and `E2e` jobs.

**knip.** `layout-tree.ts` exported five things nothing outside it uses —
`isGroup`, `isSplit`, `findGroupById`, `nodeAtPath` and the `Size` type. They are
module-private now. The two findings that remain locally (`check-font-assets.mjs`,
a `svelte` config hint) reproduce on the untouched base branch and pass on CI.

**Vue rendered every plugin twice.** The adapter's `render` and title callbacks
appended to `pluginsToRender` / `titlesToRender` without dropping the previous
entry for that mount element. `render` is called again whenever the theme or the
panel's open state changes, so this was always wrong — it only became visible now
that the core keeps one mount node per plugin for its lifetime instead of building
a fresh one. Previously each call landed in a new node and the duplicate was never
in the document. Both callbacks now replace by id. React was already correct: it
keys by element id.

**Gutters were rebuilt on every re-measure.** `splitterHandles` returns fresh
objects, so a keyed `For` destroyed and recreated every splitter whenever the
geometry changed. That threw keyboard focus away mid-resize and left stale element
references behind — the cause of both the flaky keyboard-resize test and
`boundingBox()` returning null in the drag test. Switched to `Index`, which keeps
the elements and updates their values, and the handle is read through its accessor
at gesture time so a re-measured gutter still moves the right sizes.

The e2e specs also wait for the geometry to settle rather than the tab bars alone,
and drive the keyboard through `locator.press` so focus and keypress are one step.

react-vite: 30 passed, 2 skipped, no flakes over repeated runs. vue: passing.
323 unit tests green.

* fix(devtools): make a tab's close button reliable, and drop the design spec

Closing a tab worked only sometimes. The close button sits inside the sortable
row's element, so the drag layer saw its pointerdown, decided a sort might be
starting, and swallowed the `click` that would have followed — which press landed
and which did not came down to a pixel of pointer movement.

The close control now stops the pointer events at itself and closes on pointerup,
with the `click` handler kept for keyboard activation, which fires no pointer
events at all. Closing twice is harmless: the second call finds no such tab and
returns the tree unchanged. Verified by closing three panes in a row, each press
landing.

Also removes `docs/superpowers/specs/2026-08-07-plugin-layout-tree-design.md`. It
is a planning artifact, not source, and does not belong in the history. The two
earlier commits mention it by path; the reasoning that matters is in the code
comments, `docs/plugin-workspace.md` and the changeset.

* fix(devtools): take the close button out of the drag surface, stop restyling the host page

**Closing a tab.** `SortableRow` is only a data attribute — the drag engine listens
globally and walks *up* from whatever the pointer hit looking for that key. Anything
inside the row is therefore a drag surface no matter what its own handlers do, so
the `stopPropagation` in the previous commit could not have worked. The close button
is now a sibling of the sortable row, positioned over the tab's right end, so a
press on it never reaches a sortable key.

Verified in the browser: pressing the X, moving 6px and holding for 700ms produces
no drag preview and still closes the pane, and three consecutive closes all land.

**The host page's cursor is not ours to change.** The grabbing cursor was applied to
`document.documentElement` with a descendant selector, which forced
`cursor: grabbing !important` onto every element of the page under inspection for
the length of a drag. It is scoped to the devtools panel now. Measured during a
drag: the host `<html>`, `<body>` and `<h1>` all stay at `auto` while the panel
shows `grabbing`, and the e2e test asserts both halves of that.

Everything else the devtools inject was already contained: an audit of every rule in
every injected stylesheet found zero selectors that could match an element the host
page owns — each one is scoped to a goober hash, `.tsd-*`, `[data-tsd*]`,
`[data-plugin*]` or `#tanstack_devtools`.

SSR verified across all three server runtimes: react-start, react-nitro and
react-cloudflare e2e all pass, including the server-to-client event bridge. Nothing
added here touches a browser global at module scope, and `layout-tree.ts` has no DOM
access at all.

* chore(devtools): pin @neodrag/solid to 3.0.0-next.11

The new release does not change `splitpane` — that file is byte-identical to
`next.10`, which this branch already used. What is new is its documentation page.
It does change `sortable`, `drop` and `resize`, and this uses `createSortable`, so
the bump is worth taking for whatever landed there.

Size goes 59.56 kB -> 61.23 kB, still inside the 65 kB limit. 323 unit tests and
30 react-vite e2e pass on it with no flakes.

Still pinned exactly rather than floated on `@next`: v3 is unreleased and its
published exports have already drifted from its docs more than once.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-08-10 14:12:44 +02:00

17 KiB

title id
Architecture Overview architecture

TanStack Devtools is a modular system of packages organized into three layers: Framework Adapters, Core Shell, and Event Transport. This architecture lets you use pre-built devtools panels or build your own custom ones, regardless of which frontend framework you use.

block-beta
    columns 1
    block:framework["Framework Layer"]
        columns 4
        React Vue Solid Preact
    end
    block:core["Core Layer"]
        columns 3
        Workbench["Devtools Workbench"] UI["UI components + private semantic theme"] Client["Event Client"]
    end
    block:transport["Transport Layer"]
        columns 3
        ClientBus["Client Event Bus"] ServerBus["Server Event Bus"] Vite["Vite Plugin"]
    end

    framework --> core
    core --> transport

Package Dependency Graph

graph TD
    subgraph Framework["Framework Adapters"]
        react["@tanstack/react-devtools"]
        vue["@tanstack/vue-devtools"]
        solid["@tanstack/solid-devtools"]
        preact["@tanstack/preact-devtools"]
    end

    subgraph Core["Core Layer"]
        shell["@tanstack/devtools<br/><i>Core Workbench (Solid.js)</i>"]
        client["@tanstack/devtools-client<br/><i>Core devtools events</i>"]
        eventClient["@tanstack/devtools-event-client<br/><i>Generic EventClient</i>"]
        ui["@tanstack/devtools-ui<br/><i>Shared UI + private semantic-theme owner</i>"]
        clientBus["@tanstack/devtools-event-bus/client<br/><i>ClientEventBus</i>"]
    end

    subgraph Build["Build Layer"]
        vite["@tanstack/devtools-vite"]
        serverBus["@tanstack/devtools-event-bus/server<br/><i>ServerEventBus</i>"]
    end

    subgraph Utilities
        utils["@tanstack/devtools-utils"]
    end

    react --> shell
    vue --> shell
    solid --> shell
    preact --> shell

    shell --> client
    shell --> ui
    shell --> clientBus
    client --> eventClient

    vite --> client
    vite --> serverBus

    utils --> ui

Each framework adapter depends only on @tanstack/devtools. The core shell pulls in everything it needs, so end users install just two packages: their framework adapter and the Vite plugin.

Transport Layer

The transport layer handles event delivery between plugins, the devtools UI, and (optionally) a dev server. It is composed of three pieces.

ServerEventBus (@tanstack/devtools-event-bus/server)

Runs inside the Vite dev server process (Node.js). It creates an HTTP server (or piggybacks on Vite's existing server when HTTPS is enabled) that accepts both WebSocket and SSE connections. When a message arrives from any client, the server broadcasts it to every other connected client and dispatches it on a server-side EventTarget so server-side listeners (like the Vite plugin's package-manager helpers) can react to it.

Key details:

  • Default port is 4206, auto-increments if the port is in use.
  • Handles /__devtools/ws for WebSocket upgrades, /__devtools/sse for SSE streams, and /__devtools/send for SSE POST fallback.
  • Sets globalThis.__TANSTACK_EVENT_TARGET__ so that EventClient instances running on the server can dispatch events onto the same target.

ClientEventBus (@tanstack/devtools-event-bus/client)

Runs in the browser. Started automatically when the core shell mounts via TanStackDevtoolsCore.mount(). Its responsibilities:

  1. Local dispatch -- Listens for tanstack-dispatch-event CustomEvents on window, re-dispatches them as both a type-specific CustomEvent (e.g. my-plugin:state-update) and a global tanstack-devtools-global event so listeners can subscribe to individual event types or to all events.
  2. Server forwarding -- If connected to a server bus, forwards every dispatched event over WebSocket (preferred) or SSE POST fallback.
  3. Cross-tab sync -- Uses BroadcastChannel('tanstack-devtools') to replicate events across browser tabs without round-tripping through the server.
  4. Connection handshake -- Responds to tanstack-connect events with tanstack-connect-success, allowing EventClient instances to discover the bus.

EventClient (@tanstack/devtools-event-client)

The high-level, typed API that plugins use to send and receive events. Each EventClient is created with a pluginId and a type map that defines the events it can emit and listen to.

import { EventClient } from '@tanstack/devtools-event-client'

type MyEvents = {
  'state-update': { count: number }
  'reset': void
}

const client = new EventClient<MyEvents>({ pluginId: 'my-plugin' })

When you call client.emit('state-update', { count: 42 }), the EventClient:

  1. Dispatches a CustomEvent on its internal EventTarget (for same-page listeners using the withEventTarget option).
  2. Dispatches a tanstack-dispatch-event CustomEvent on the global target (typically window), with a payload of { type: 'my-plugin:state-update', payload: { count: 42 }, pluginId: 'my-plugin' }.
  3. The ClientEventBus picks up that tanstack-dispatch-event, re-dispatches it as a my-plugin:state-update CustomEvent on window, and forwards it to the server bus via WebSocket.

When you call client.on('state-update', callback), the EventClient registers a listener on the global target for my-plugin:state-update events, so it receives events regardless of whether they came from a local emit or from the server bus.

Note

The server bus is optional. Without the Vite plugin, EventClient still works for same-page communication via CustomEvent dispatch on window. Events simply won't cross tab or process boundaries.

Event Flow Summary

flowchart LR
    emit["EventClient.emit()"] --> dispatch["CustomEvent<br/><b>tanstack-dispatch-event</b><br/>on window"]
    dispatch --> bus["ClientEventBus"]
    bus --> local["Re-dispatch as<br/><b>my-plugin:state-update</b><br/>on window"]
    local --> onLocal["EventClient.on()<br/>callbacks fire"]
    bus --> bc["BroadcastChannel"]
    bc --> otherTabs["Other tabs<br/>receive event"]
    bus --> ws["WebSocket"]
    ws --> server["ServerEventBus"]
    server --> broadcast["Broadcast to all<br/>connected clients"]
    broadcast --> remote["EventClient.on()<br/>callbacks fire<br/>in other clients"]

Core Layer

@tanstack/devtools -- The Shell

The devtools shell is a Solid.js application that renders the entire devtools UI. It exposes the TanStackDevtoolsCore class with three methods:

  • mount(el) -- Renders the Solid.js devtools application into the given DOM element. Starts a ClientEventBus and lazy-loads the UI. Wraps everything in a DevtoolsProvider (reactive store for plugins, settings, state) and a PiPProvider (Picture-in-Picture support).
  • unmount() -- Tears down the Solid.js app and stops the event bus.
  • setConfig(config) -- Updates configuration and plugins at runtime. Plugins are reactive: adding or removing them updates the tab bar immediately.

The shell renders:

  • A trigger button (the floating devtools toggle, customizable or replaceable)
  • A resizable Workbench panel (docked to the top or bottom of the viewport, resizable via pointer or keyboard)
  • A compact 36px TanStack Devtools header with Plugins, Marketplace, SEO, and Settings destinations. The palm emblem is inline SVG, so it stays sharp and takes its colour from the theme.
  • A fixed-height 44px secondary strip for plugin and SEO navigation. It scrolls horizontally when space is limited, and a pull tab on its bottom edge folds it away behind the header. Folding changes nothing else — the panel keeps its height and the destination content keeps running — so the tab is rendered only on the destinations that have a strip.
  • A separate Marketplace header tab that does not disturb mounted plugin panes
  • A settings panel for theme, hotkeys, position, and other preferences
  • Up to three simultaneous plugin mount frames, divided into equal widths by static separators

Settings and UI state (panel size, position, active tab, theme) are persisted in localStorage so they survive page reloads.

The core shell owns the Workbench header, navigation, mount-frame geometry, separators, and surrounding light/dark surfaces. Each external plugin owns everything inside its mount target; core styling deliberately does not reach into plugin descendants. Detaching the Workbench uses a fixed 100vh Picture-in-Picture layout and restores the stored docked height when reattached.

Workbench surfaces and gutters

Two rules keep the shell reading as one surface:

  • Chrome versus canvas. The header and every secondary strip paint the brand surface (cream in light mode, near-black in dark mode) and close with a translucent ink hairline. Destination content and plugin mount frames paint the workspace surface. A plugin pane can paint any colour it likes, so the separator between panes uses a mid-tone border that stays visible against both.
  • One gutter. WORKBENCH_GUTTER (16px, or WORKBENCH_GUTTER_NARROW at 12px below 430px) is the single inline gutter. The header, the strips, and each destination's content all start there, so the left edge is one column instead of three. MainPanel withPadding uses the same value.

Colour comes from the semantic theme only. Raw hex values in core-owned source are rejected by tests/semantic-color-usage.test.ts unless they carry a narrow, path-scoped semantic-color-exempt marker — currently only third-party network marks and the source-inspector highlight alpha. Status colours (success, warning, error, info) mark real state; identity accents do not compete with them, so a card that is both featured and active keeps the neutral outline and lets its badge say which it is.

@tanstack/devtools-ui -- Component Library

A shared Solid.js component library used by the core shell and available for use in Solid.js plugins. Provides buttons, inputs, checkboxes, a JSON tree viewer, section layouts, and other UI primitives. The @tanstack/devtools-utils package also depends on it to provide framework-specific plugin helpers.

Core packages share a private semantic resolver through @tanstack/devtools-ui/internal. It supplies TanStack light/dark colors, typography, spacing, status roles, and focus treatment to core-owned UI and the accessibility plugin. This internal subpath is an implementation boundary, not a public theming API for application plugins.

@tanstack/devtools-client -- Core Event Client

A specialized EventClient pre-configured with pluginId: 'tanstack-devtools-core' and a fixed event map for devtools-internal operations:

  • mounted -- Fired when the devtools UI has mounted, triggers the server to send current package.json and outdated dependency data.
  • package-json-read / outdated-deps-read -- Carries project metadata from the Vite server to the devtools UI.
  • install-devtools / devtools-installed -- Request/response cycle for installing a plugin package from the marketplace.
  • add-plugin-to-devtools / plugin-added -- Request/response cycle for injecting a plugin into the user's source code.
  • trigger-toggled -- Synchronizes the open/closed state of the devtools panel.

This client is a singleton (devtoolsEventClient) used by both the core shell and the Vite plugin to coordinate.

Framework Layer

Each framework adapter is a thin wrapper that bridges its framework's component model to the core Solid.js shell. The pattern is the same across all adapters:

  1. Creates a TanStackDevtoolsCore instance with the user's plugins and config.
  2. Mounts it to a DOM element using the framework's lifecycle hooks (useEffect in React, onMounted in Vue, onMount in Solid).
  3. Converts framework-specific plugin definitions into the core's DOM-based render(el, theme) interface. Each adapter defines its own plugin type (e.g. TanStackDevtoolsReactPlugin) that accepts framework-native components, then wraps them in a render callback that the core calls with a target DOM element and the current theme.
  4. Uses the framework's portal/teleport mechanism to render plugin components into the core's DOM containers:
    • React -- createPortal() from react-dom
    • Vue -- <Teleport :to="'#' + plugin.id" />
    • Solid -- <Portal mount={el} />
    • Preact -- Same portal pattern as React

The key insight: the core shell is always Solid.js, but your plugins run in your framework. A React plugin is a real React component rendered by React's createPortal into a DOM element that the Solid.js shell created. A Vue plugin is a real Vue component rendered by Vue's <Teleport>. The adapters bridge this gap so you never need to think about Solid.js unless you want to.

What an adapter does NOT do

Adapters do not re-implement the devtools UI, manage settings, handle events, or communicate with the server. All of that lives in the core shell. Adapters are intentionally minimal -- typically a single file under 300 lines.

Build Layer

@tanstack/devtools-vite is a collection of Vite plugins that enhance the development experience and clean up production builds. It returns an array of Vite plugins, each handling a specific concern:

Source injection (@tanstack/devtools:inject-source)

Parses JSX/TSX files with oxc-parser and injects data-tsd-source attributes on every JSX element via MagicString. These attributes encode the file path, line number, and column number of each element in source code, which the source inspector feature uses to implement click-to-open-in-editor.

Server event bus (@tanstack/devtools:custom-server)

Starts a ServerEventBus on the Vite dev server. Also sets up middleware for the go-to-source editor integration and bidirectional console piping (client logs appear in the terminal, server logs appear in the browser).

Production stripping (@tanstack/devtools:remove-devtools-on-build)

On production builds, transforms any file that imports from @tanstack/*-devtools to remove the devtools imports and JSX usage entirely. This means devtools add zero bytes to your production bundle.

Console piping (@tanstack/devtools:console-pipe-transform)

Injects a small runtime into your application's entry file that intercepts console.log/warn/error/info/debug calls and forwards them to the Vite dev server via HTTP POST. The server then broadcasts them to connected SSE clients, enabling server-to-browser log forwarding.

Enhanced logging (@tanstack/devtools:better-console-logs)

Transforms console.* calls to prepend source location information (file, line, column), making it possible to click a console log and jump directly to the source.

Plugin marketplace support (@tanstack/devtools:event-client-setup)

Listens for install-devtools events from the devtools UI, runs the package manager to install the requested package, and then uses AST manipulation to inject the plugin import and configuration into the user's source code.

Connection injection (@tanstack/devtools:connection-injection)

Replaces compile-time placeholders (__TANSTACK_DEVTOOLS_PORT__, __TANSTACK_DEVTOOLS_HOST__, __TANSTACK_DEVTOOLS_PROTOCOL__) in the event bus client code with the actual values from the running dev server, so the client automatically connects to the correct server.

Data Flow

To tie everything together, here is what happens when a plugin emits an event end-to-end:

  1. Your library code calls eventClient.emit('state-update', data).

  2. EventClient constructs a payload { type: 'my-plugin:state-update', payload: data, pluginId: 'my-plugin' } and dispatches it as a tanstack-dispatch-event CustomEvent on window.

  3. ClientEventBus receives the tanstack-dispatch-event. It does three things:

    • Dispatches a CustomEvent named my-plugin:state-update on window so that any eventClient.on('state-update', callback) listeners on this page fire immediately.
    • Dispatches a tanstack-devtools-global CustomEvent on window so that onAll() and onAllPluginEvents() listeners fire.
    • Posts the event to the BroadcastChannel so other tabs receive it.
  4. If connected to the server bus, ClientEventBus also sends the event over WebSocket to ServerEventBus.

  5. ServerEventBus receives the WebSocket message and broadcasts it to all other connected clients (WebSocket and SSE). It also dispatches the event on its server-side EventTarget so server-side listeners (e.g., the Vite plugin) can react.

  6. In other browser tabs/windows, the event arrives via WebSocket from the server (or via BroadcastChannel from step 3). The local ClientEventBus dispatches it as a my-plugin:state-update CustomEvent, and any eventClient.on('state-update', callback) listeners fire with the data.

Without the Vite plugin and server bus, steps 4-6 are skipped, but steps 1-3 still work. This means plugins can communicate within a single page without any server infrastructure -- the server bus just adds cross-tab and cross-process capabilities.