Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

skill_spec.md

172 lines16.5 KB

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 |