Open History to see the last commit
1# TanStack Devtools β Skill Spec
2β
3TanStack Devtools is a framework-agnostic toolkit for building custom devtools panels via a plugin system with typed event communication. It provides the shell UI, event transport, framework adapters, and build tooling so library authors can focus on their debugging UI while end-app developers get a unified devtools experience across React, Vue, Solid, and Preact.
4β
5## Domains
6β
7| Domain | Description | Skills |
8| ----------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
9| Setting up devtools | Installing, configuring, and mounting devtools in an app | app-setup |
10| Building plugins | Creating custom plugins: event clients, panels, marketplace | plugin-panel-development, marketplace-publishing |
11| Event communication | Typed event system for plugin data flow | event-client-creation, bidirectional-communication |
12| Framework adaptation | Per-framework adapters using factory functions | framework-adapters |
13| Build and production | Vite plugin features and production concerns | vite-plugin, production-setup |
14| Library instrumentation | Strategic event emission placement in codebases | strategic-instrumentation |
15β
16## Skill Inventory
17β
18| Skill | Type | Domain | What it covers | Failure modes |
19| --------------------------- | --------- | -------------------- | --------------------------------------------------------------------------------- | ------------- |
20| app-setup | core | setup | TanStackDevtools component, plugins prop, config, framework adapters | 4 |
21| vite-plugin | core | build-production | Source injection, console piping, enhanced logs, production stripping, server bus | 5 |
22| event-client-creation | core | event-communication | EventClient class, event maps, connection lifecycle, namespacing | 7 |
23| strategic-instrumentation | core | instrumentation | Finding critical emission points, consolidation, performance | 3 |
24| plugin-panel-development | core | plugin-development | Panel components, event listening, theming, devtools-ui | 7 |
25| framework-adapters | framework | framework-adaptation | createReactPlugin, createSolidPlugin, createVuePlugin, NoOp variants | 4 |
26| bidirectional-communication | core | event-communication | Commands, state editing, time-travel, structuredClone | 3 |
27| production-setup | lifecycle | build-production | removeDevtoolsOnBuild, conditional imports, NoOp patterns | 3 |
28| marketplace-publishing | lifecycle | plugin-development | PluginMetadata, registry format, auto-install config | 3 |
29β
30## Failure Mode Inventory
31β
32### app-setup (4 failure modes)
33β
34| # | Mistake | Priority | Source | Cross-skill? |
35| --- | ----------------------------------------------------- | -------- | ----------------------------- | ------------------ |
36| 1 | Vite plugin not placed first in plugins array | HIGH | docs/vite-plugin.md | vite-plugin |
37| 2 | Vue plugin uses render instead of component | CRITICAL | docs/framework/vue/adapter.md | framework-adapters |
38| 3 | Installing as regular dep for dev-only use | MEDIUM | docs/installation.md | β |
39| 4 | Mounting TanStackDevtools in SSR without client guard | HIGH | packages/devtools/src/core.ts | β |
40β
41### vite-plugin (5 failure modes)
42β
43| # | Mistake | Priority | Source | Cross-skill? |
44| --- | ----------------------------------------------- | -------- | ------------------------------------------- | ------------ |
45| 1 | Expecting Vite plugin features in production | MEDIUM | packages/devtools-vite/src/plugin.ts | β |
46| 2 | Not placing devtools() first in Vite plugins | HIGH | docs/vite-plugin.md | app-setup |
47| 3 | Source injection on spread props elements | MEDIUM | packages/devtools-vite/src/inject-source.ts | β |
48| 4 | Using devtools-vite with non-Vite bundlers | HIGH | packages/devtools-vite/package.json | β |
49| 5 | Event bus port conflict in multi-project setups | MEDIUM | packages/event-bus/src/server/server.ts | β |
50β
51### event-client-creation (7 failure modes)
52β
53| # | Mistake | Priority | Source | Cross-skill? |
54| --- | --------------------------------------------------- | -------- | --------------------------------------- | --------------------------- |
55| 1 | Including pluginId prefix in event names | CRITICAL | packages/event-bus-client/src/plugin.ts | β |
56| 2 | Creating multiple EventClient instances per plugin | CRITICAL | docs/building-custom-plugins.md | β |
57| 3 | Non-unique pluginId causing event collisions | CRITICAL | maintainer interview | β |
58| 4 | Not realizing events drop after 5 failed retries | HIGH | packages/event-bus-client/src/plugin.ts | β |
59| 5 | Listening before emitting and expecting connection | HIGH | packages/event-bus-client/src/plugin.ts | β |
60| 6 | Using non-serializable payloads | HIGH | packages/event-bus/src/utils/json.ts | bidirectional-communication |
61| 7 | Not stripping EventClient emit calls for production | HIGH | maintainer interview | production-setup |
62β
63### strategic-instrumentation (3 failure modes)
64β
65| # | Mistake | Priority | Source | Cross-skill? |
66| --- | ---------------------------------------- | -------- | ----------------------------------- | ------------ |
67| 1 | Emitting too many granular events | HIGH | maintainer interview | β |
68| 2 | Emitting in hot loops without debouncing | HIGH | docs/bidirectional-communication.md | β |
69| 3 | Not emitting at architecture boundaries | MEDIUM | maintainer interview | β |
70β
71### plugin-panel-development (7 failure modes)
72β
73| # | Mistake | Priority | Source | Cross-skill? |
74| --- | ------------------------------------------------------- | -------- | --------------------------------------------------------- | ------------------------- |
75| 1 | Not cleaning up event listeners | CRITICAL | docs/building-custom-plugins.md | β |
76| 2 | Oversubscribing to events in multiple places | HIGH | maintainer interview | β |
77| 3 | Hardcoding repeated event payload fields | MEDIUM | maintainer interview | strategic-instrumentation |
78| 4 | Ignoring theme prop in panel component | MEDIUM | docs/plugin-lifecycle.md | β |
79| 5 | Not knowing max 3 active plugins limit | MEDIUM | packages/devtools/src/utils/get-default-active-plugins.ts | β |
80| 6 | Using raw DOM manipulation instead of framework portals | MEDIUM | docs/plugin-lifecycle.md | β |
81| 7 | Not keeping devtools packages at latest versions | MEDIUM | maintainer interview | app-setup |
82β
83### framework-adapters (4 failure modes)
84β
85| # | Mistake | Priority | Source | Cross-skill? |
86| --- | ----------------------------------------- | -------- | -------------------------------------------- | ---------------- |
87| 1 | Using React JSX pattern in Vue adapter | CRITICAL | packages/devtools-utils/src/vue/plugin.ts | app-setup |
88| 2 | Solid render prop not wrapped in function | CRITICAL | docs/framework/solid/adapter.md | β |
89| 3 | Ignoring NoOp variant for production | HIGH | docs/devtools-utils.md | production-setup |
90| 4 | Not passing theme prop to panel component | MEDIUM | packages/devtools-utils/src/react/plugin.tsx | β |
91β
92### bidirectional-communication (3 failure modes)
93β
94| # | Mistake | Priority | Source | Cross-skill? |
95| --- | -------------------------------------------------- | -------- | ------------------------------------ | --------------------- |
96| 1 | Not using structuredClone for snapshots | HIGH | docs/bidirectional-communication.md | β |
97| 2 | Not distinguishing observation from command events | MEDIUM | docs/bidirectional-communication.md | β |
98| 3 | Non-serializable payloads in cross-tab scenarios | HIGH | packages/event-bus/src/utils/json.ts | event-client-creation |
99β
100### production-setup (3 failure modes)
101β
102| # | Mistake | Priority | Source | Cross-skill? |
103| --- | ---------------------------------------------------- | -------- | ------------------ | ------------ |
104| 1 | Keeping devtools in prod without disabling stripping | HIGH | docs/production.md | β |
105| 2 | Not using /production sub-export | MEDIUM | docs/production.md | β |
106| 3 | Non-Vite projects not excluding devtools manually | HIGH | docs/production.md | β |
107β
108### marketplace-publishing (3 failure modes)
109β
110| # | Mistake | Priority | Source | Cross-skill? |
111| --- | ---------------------------------------------- | -------- | --------------------------- | ------------ |
112| 1 | Missing pluginImport metadata for auto-install | HIGH | docs/third-party-plugins.md | β |
113| 2 | Not specifying requires.minVersion | MEDIUM | docs/third-party-plugins.md | β |
114| 3 | Submitting without framework field | MEDIUM | docs/third-party-plugins.md | β |
115β
116## Tensions
117β
118| Tension | Skills | Agent implication |
119| ----------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
120| Instrumentation completeness vs performance | strategic-instrumentation β event-client-creation | Agent optimizing for debugging coverage emits in hot paths; agent optimizing for performance skips critical points |
121| Development convenience vs production safety | app-setup β production-setup | Agent installs as devDep with stripping; later production usage requires undoing those decisions |
122| Framework-agnostic core vs framework ergonomics | framework-adapters β plugin-panel-development | Agent trained on React uses render/JSX everywhere; Vue and Solid have different plugin definitions |
123β
124## Cross-References
125β
126| From | To | Reason |
127| --------------------------- | --------------------------- | ---------------------------------------------------- |
128| app-setup | vite-plugin | Vite plugin adds enhanced features after basic setup |
129| event-client-creation | strategic-instrumentation | Understanding event system informs where to emit |
130| event-client-creation | plugin-panel-development | Client emits, panel listens β same event map |
131| plugin-panel-development | framework-adapters | After building panel, wrap in framework adapters |
132| framework-adapters | production-setup | NoOp variants are the primary tree-shaking mechanism |
133| bidirectional-communication | event-client-creation | Bidirectional extends the base event system |
134| vite-plugin | production-setup | Vite plugin handles production stripping defaults |
135| plugin-panel-development | marketplace-publishing | After building plugin, publish to marketplace |
136| strategic-instrumentation | bidirectional-communication | Emission points benefit from bidirectional patterns |
137β
138## Subsystems & Reference Candidates
139β
140| Skill | Subsystems | Reference candidates |
141| --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
142| vite-plugin | Source injection, Console piping, Enhanced logging, Production stripping, Server event bus, Editor integration | Vite plugin options reference |
143| framework-adapters | React adapter, Solid adapter, Vue adapter, Preact adapter | β |
144| app-setup | β | Config options (position, hotkeys, theme, eventBus) |
145| event-client-creation | β | EventClient constructor options, connection lifecycle states |
146β
147## Remaining Gaps
148β
149All gaps resolved during maintainer interview:
150β
151- PiP window mode has zero impact on plugin development
152- No formal testing patterns exist; EventClient works standalone for same-page communication
153- No performance benchmarks; guidance is to prototype freely, reduce for production
154- Telemetry patterns to be derived from source code analysis
155β
156## Recommended Skill File Structure
157β
158- **Core skills:** app-setup, event-client-creation, strategic-instrumentation, plugin-panel-development, bidirectional-communication
159- **Framework skills:** framework-adapters (covers all four frameworks with subsystem files)
160- **Lifecycle skills:** production-setup, marketplace-publishing
161- **Composition skills:** none needed (devtools is the composition primitive itself)
162- **Reference files:** vite-plugin (6 subsystems with distinct config surfaces)
163β
164## Composition Opportunities
165β
166| Library | Integration points | Composition skill needed? |
167| ---------------------- | ---------------------------- | ------------------------------------------------- |
168| TanStack Query | Query devtools panel plugin | No β TanStack Query ships its own devtools panel |
169| TanStack Router | Router devtools panel plugin | No β TanStack Router ships its own devtools panel |
170| TanStack Form | Form devtools panel plugin | No β TanStack Form ships its own devtools panel |
171| Vite | Build tooling integration | No β covered by vite-plugin skill |
172| Any state/data library | EventClient instrumentation | Yes β strategic-instrumentation skill |