Open History to see the last commit
1# domain_map.yaml
2# Generated by skill-domain-discovery
3# Library: @tanstack/devtools
4# Version: 0.10.12
5# Date: 2026-03-11
6# Status: reviewed
7β
8library:
9 name: '@tanstack/devtools'
10 version: '0.10.12'
11 repository: 'https://github.com/TanStack/devtools'
12 description: >
13 Framework-agnostic toolkit for building, composing, and debugging custom
14 devtools panels via a plugin system with typed event communication.
15 Supports React, Vue, Solid, and Preact.
16 primary_framework: 'framework-agnostic'
17β
18domains:
19 - name: 'Setting up devtools'
20 slug: 'setup'
21 description: >
22 Installing, configuring, and mounting TanStack Devtools in an application.
23 Covers framework adapter selection, plugin registration, shell configuration,
24 and Vite plugin integration.
25β
26 - name: 'Building plugins'
27 slug: 'plugin-development'
28 description: >
29 Creating custom devtools plugins end-to-end: defining event clients,
30 building panel components, registering plugins, and publishing to
31 the marketplace.
32β
33 - name: 'Event communication'
34 slug: 'event-communication'
35 description: >
36 The typed event system that plugins use to send and receive data.
37 Covers EventClient creation, event maps, connection lifecycle,
38 bidirectional patterns, and cross-tab synchronization.
39β
40 - name: 'Framework adaptation'
41 slug: 'framework-adaptation'
42 description: >
43 Creating per-framework plugin adapters using devtools-utils factory
44 functions. Covers React, Vue, Solid, and Preact differences,
45 portal/teleport mechanisms, and NoOp variants for tree-shaking.
46β
47 - name: 'Build and production'
48 slug: 'build-production'
49 description: >
50 Vite plugin features and production build concerns. Covers source
51 injection, console piping, production stripping, enhanced logging,
52 and conditional devtools inclusion.
53β
54 - name: 'Library instrumentation'
55 slug: 'instrumentation'
56 description: >
57 Strategically adding event emissions to a library codebase at critical
58 architecture and debugging points without overdoing it.
59β
60skills:
61 - name: 'App setup'
62 slug: 'app-setup'
63 domain: 'setup'
64 description: >
65 End-app developer installs TanStack Devtools, picks the right framework
66 adapter, registers plugins, and configures the shell.
67 type: 'core'
68 packages:
69 - '@tanstack/react-devtools'
70 - '@tanstack/vue-devtools'
71 - '@tanstack/solid-devtools'
72 - '@tanstack/preact-devtools'
73 - '@tanstack/devtools'
74 - '@tanstack/devtools-vite'
75 covers:
76 - 'TanStackDevtools component'
77 - 'plugins prop'
78 - 'config prop (position, hotkeys, theme, hideUntilHover, requireUrlFlag)'
79 - 'eventBusConfig prop'
80 - 'Framework-specific plugin types'
81 - 'defaultOpen behavior'
82 - 'localStorage persistence'
83 tasks:
84 - 'Install devtools for my React/Vue/Solid/Preact app'
85 - 'Add TanStack Query and Router devtools to my app'
86 - 'Configure devtools position, hotkeys, and theme'
87 - 'Set up devtools with Vite plugin for enhanced features'
88 - 'Hide devtools trigger until hover'
89 - 'Require URL flag to enable devtools'
90 failure_modes:
91 - mistake: 'Vite plugin not placed first in plugins array'
92 mechanism: >
93 Source injection and other transforms must run before framework
94 plugins. Placing devtools() after other plugins causes source
95 inspector to not work.
96 wrong_pattern: |
97 export default {
98 plugins: [
99 react(),
100 devtools(),
101 ],
102 }
103 correct_pattern: |
104 export default {
105 plugins: [
106 devtools(),
107 react(),
108 ],
109 }
110 source: 'docs/quick-start.md, docs/vite-plugin.md'
111 priority: 'HIGH'
112 status: 'active'
113β
114 - mistake: 'Vue plugin uses render instead of component'
115 mechanism: >
116 Vue adapter uses component reference + props pattern, not JSX render.
117 Using render field produces silent failure β no panel renders.
118 wrong_pattern: |
119 const plugins = [
120 { name: 'My Plugin', render: <MyComponent /> }
121 ]
122 correct_pattern: |
123 const plugins: TanStackDevtoolsVuePlugin[] = [
124 { name: 'My Plugin', component: MyComponent }
125 ]
126 source: 'docs/framework/vue/adapter.md, packages/vue-devtools/src/vue-devtools.vue'
127 priority: 'CRITICAL'
128 status: 'active'
129 skills: ['app-setup', 'framework-adapters']
130β
131 - mistake: 'Installing as regular dependency for dev-only use'
132 mechanism: >
133 Devtools should be devDependencies when using Vite plugin stripping.
134 Installing as regular deps bloats production node_modules.
135 wrong_pattern: |
136 npm install @tanstack/react-devtools @tanstack/devtools-vite
137 correct_pattern: |
138 npm install -D @tanstack/react-devtools @tanstack/devtools-vite
139 source: 'docs/installation.md'
140 priority: 'MEDIUM'
141 status: 'active'
142β
143 - mistake: 'Mounting TanStackDevtools in SSR without client guard'
144 mechanism: >
145 The core shell requires DOM APIs. Mounting during SSR causes errors.
146 React adapter has use client directive, but custom setups need guards.
147 wrong_pattern: |
148 // In an SSR-rendered component without client guard
149 function App() {
150 return <TanStackDevtools />
151 }
152 correct_pattern: |
153 // React adapter already has 'use client' directive
154 // For custom setups, guard with typeof document check
155 import { TanStackDevtools } from '@tanstack/react-devtools'
156 function App() {
157 return <TanStackDevtools />
158 }
159 source: 'packages/devtools/src/core.ts, packages/react-devtools/src/devtools.tsx'
160 priority: 'HIGH'
161 status: 'active'
162β
163 - name: 'Vite plugin setup'
164 slug: 'vite-plugin'
165 domain: 'build-production'
166 description: >
167 Configure the Vite plugin for source inspection, console piping,
168 enhanced logging, server event bus, and production stripping.
169 type: 'core'
170 packages:
171 - '@tanstack/devtools-vite'
172 covers:
173 - 'devtools() function and options'
174 - 'Source injection (data-tsd-source attributes)'
175 - 'Source inspector activation and hotkeys'
176 - 'Console piping (client-to-server and server-to-client)'
177 - 'Enhanced console logs with source locations'
178 - 'Production build stripping'
179 - 'Server event bus configuration'
180 - 'Editor integration (launch-editor)'
181 - 'Plugin marketplace support'
182 - 'Connection injection placeholders'
183 tasks:
184 - 'Add Vite plugin to my project'
185 - 'Configure source inspector for click-to-open-in-editor'
186 - 'Set up console piping between browser and terminal'
187 - 'Configure custom editor for go-to-source'
188 - 'Disable specific Vite plugin features'
189 - 'Configure event bus port and host'
190 subsystems:
191 - name: 'Source injection'
192 package: '@tanstack/devtools-vite'
193 config_surface: 'injectSource.enabled, injectSource.ignore (files, components)'
194 - name: 'Console piping'
195 package: '@tanstack/devtools-vite'
196 config_surface: 'consolePiping.enabled, consolePiping.levels'
197 - name: 'Enhanced logging'
198 package: '@tanstack/devtools-vite'
199 config_surface: 'enhancedLogs.enabled'
200 - name: 'Production stripping'
201 package: '@tanstack/devtools-vite'
202 config_surface: 'removeDevtoolsOnBuild'
203 - name: 'Server event bus'
204 package: '@tanstack/devtools-vite'
205 config_surface: 'eventBusConfig.port, eventBusConfig.enabled, eventBusConfig.debug'
206 - name: 'Editor integration'
207 package: '@tanstack/devtools-vite'
208 config_surface: 'editor.name, editor.open'
209 failure_modes:
210 - mistake: 'Expecting Vite plugin features in production'
211 mechanism: >
212 Source injection, console piping, enhanced logging, and the server
213 event bus only work during development with Vite dev server.
214 Production builds strip all of this.
215 source: 'packages/devtools-vite/src/plugin.ts'
216 priority: 'MEDIUM'
217 status: 'active'
218β
219 - mistake: 'Not placing devtools() first in Vite plugins'
220 mechanism: >
221 All devtools sub-plugins use enforce:pre. They must transform code
222 before framework plugins (React, Vue, etc.) process it.
223 wrong_pattern: |
224 plugins: [react(), devtools()]
225 correct_pattern: |
226 plugins: [devtools(), react()]
227 source: 'docs/vite-plugin.md'
228 priority: 'HIGH'
229 status: 'active'
230 skills: ['vite-plugin', 'app-setup']
231β
232 - mistake: 'Source injection on spread props elements'
233 mechanism: >
234 The AST transform skips elements with {...props} spread to avoid
235 overwriting dynamic attributes. Agent might not realize source
236 inspector wont work on those elements.
237 source: 'packages/devtools-vite/src/inject-source.ts'
238 priority: 'MEDIUM'
239 status: 'active'
240β
241 - mistake: 'Using devtools-vite with non-Vite bundlers'
242 mechanism: >
243 The package is Vite-specific (peer dep vite ^6 || ^7). It will not
244 work with webpack, rspack, or other bundlers. EventClient still works
245 without it for same-page communication.
246 source: 'packages/devtools-vite/package.json'
247 priority: 'HIGH'
248 status: 'active'
249β
250 - mistake: 'Event bus port conflict in multi-project setups'
251 mechanism: >
252 Default port 4206 may conflict when running multiple Vite dev servers.
253 ServerEventBus falls back to OS-assigned port on EADDRINUSE, but
254 clients may not discover the new port without Vite injection.
255 source: 'packages/event-bus/src/server/server.ts lines 313-336'
256 priority: 'MEDIUM'
257 status: 'active'
258β
259 - name: 'Event client creation'
260 slug: 'event-client-creation'
261 domain: 'event-communication'
262 description: >
263 Create a typed EventClient for a library, define event maps, understand
264 the connection lifecycle, event namespacing, and queuing behavior.
265 type: 'core'
266 packages:
267 - '@tanstack/devtools-event-client'
268 covers:
269 - 'EventClient class and constructor options'
270 - 'Event map type definitions'
271 - 'pluginId namespacing (auto-prepend)'
272 - 'emit() and event queuing'
273 - 'on(), onAll(), onAllPluginEvents() listeners'
274 - 'Connection lifecycle (5 retries, 300ms interval)'
275 - 'enabled/disabled state'
276 - 'SSR/non-web environment fallbacks'
277 - 'Internal EventTarget (withEventTarget option)'
278 tasks:
279 - 'Create a typed EventClient for my library'
280 - 'Define an event map with typed payloads'
281 - 'Emit events from my library code'
282 - 'Listen for events in my devtools panel'
283 - 'Handle connection failures gracefully'
284 failure_modes:
285 - mistake: 'Including pluginId prefix in event names'
286 mechanism: >
287 EventClient auto-prepends pluginId to event names. Writing
288 emit('my-plugin:state-update') produces the event name
289 'my-plugin:my-plugin:state-update' on the bus.
290 wrong_pattern: |
291 myClient.emit('my-plugin:state-update', data)
292 correct_pattern: |
293 myClient.emit('state-update', data)
294 source: 'packages/event-bus-client/src/plugin.ts lines 190-199'
295 priority: 'CRITICAL'
296 status: 'active'
297β
298 - mistake: 'Creating multiple EventClient instances per plugin'
299 mechanism: >
300 EventClient should be a singleton per plugin. Multiple instances
301 with the same pluginId create duplicate event handlers and
302 multiple connection attempts to the bus.
303 wrong_pattern: |
304 function MyPanel() {
305 const client = new MyEventClient() // new instance per render
306 client.on('state', cb)
307 }
308 correct_pattern: |
309 // Module-level singleton
310 export const myClient = new MyEventClient()
311β
312 function MyPanel() {
313 myClient.on('state', cb)
314 }
315 source: 'docs/building-custom-plugins.md, packages/event-bus-client/src/plugin.ts'
316 priority: 'CRITICAL'
317 status: 'active'
318β
319 - mistake: 'Not realizing events drop after 5 failed retries'
320 mechanism: >
321 After 5 connection retries (1.5s total), failedToConnect is set
322 permanently. All subsequent emit() calls are silently dropped.
323 No error is thrown.
324 source: 'packages/event-bus-client/src/plugin.ts lines 44-56'
325 priority: 'HIGH'
326 status: 'active'
327β
328 - mistake: 'Listening before emitting and expecting connection'
329 mechanism: >
330 Connection is lazily initiated on first emit(), not on construction
331 or on(). If you only call on() without ever emitting, the client
332 never connects to the bus.
333 source: 'packages/event-bus-client/src/plugin.ts'
334 priority: 'HIGH'
335 status: 'active'
336β
337 - mistake: 'Using non-serializable payloads in events'
338 mechanism: >
339 Events are serialized via JSON when crossing process/tab boundaries
340 (WebSocket, SSE, BroadcastChannel). Functions, DOM nodes, and
341 circular references will fail silently or produce empty payloads.
342 wrong_pattern: |
343 client.emit('update', {
344 callback: () => {}, // function - not serializable
345 element: document.body, // DOM node
346 })
347 correct_pattern: |
348 client.emit('update', {
349 count: 42,
350 label: 'my-update',
351 timestamp: Date.now(),
352 })
353 source: 'packages/event-bus/src/utils/json.ts, docs/bidirectional-communication.md'
354 priority: 'HIGH'
355 status: 'active'
356 skills: ['event-client-creation', 'bidirectional-communication']
357β
358 - mistake: 'Non-unique pluginId causing event collisions'
359 mechanism: >
360 If two plugins use the same pluginId, their events collide on
361 the bus. One plugin receives events intended for the other,
362 causing incorrect state and hard-to-debug behavior.
363 wrong_pattern: |
364 // Plugin A
365 class PluginA extends EventClient<AEvents> {
366 constructor() { super({ pluginId: 'my-plugin' }) }
367 }
368 // Plugin B β same pluginId!
369 class PluginB extends EventClient<BEvents> {
370 constructor() { super({ pluginId: 'my-plugin' }) }
371 }
372 correct_pattern: |
373 // Plugin A
374 class PluginA extends EventClient<AEvents> {
375 constructor() { super({ pluginId: 'query-inspector' }) }
376 }
377 // Plugin B β unique pluginId
378 class PluginB extends EventClient<BEvents> {
379 constructor() { super({ pluginId: 'router-inspector' }) }
380 }
381 source: 'maintainer interview'
382 priority: 'CRITICAL'
383 status: 'active'
384β
385 - mistake: 'Not stripping EventClient emit calls for production'
386 mechanism: >
387 The Vite plugin strips framework adapter imports but NOT
388 @tanstack/devtools-event-client imports. Library authors must
389 decide whether to keep or guard emit() calls in production.
390 The enabled:false option or conditional guards are needed.
391 wrong_pattern: |
392 // Library code β emits in production with no guard
393 export function updateState(state) {
394 myClient.emit('state-changed', state)
395 }
396 correct_pattern: |
397 // Option 1: Use enabled flag
398 const myClient = new MyClient({
399 pluginId: 'my-lib',
400 enabled: process.env.NODE_ENV === 'development',
401 })
402β
403 // Option 2: Conditional guard
404 export function updateState(state) {
405 if (__DEV__) myClient.emit('state-changed', state)
406 }
407 source: 'maintainer interview'
408 priority: 'HIGH'
409 status: 'active'
410β
411 - name: 'Strategic instrumentation'
412 slug: 'strategic-instrumentation'
413 domain: 'instrumentation'
414 description: >
415 Analyze a library codebase to find critical architecture and debugging
416 points, then add strategic event emissions that provide maximum debugging
417 value with minimum noise.
418 type: 'core'
419 packages:
420 - '@tanstack/devtools-event-client'
421 covers:
422 - 'Identifying critical architecture points (middleware, state transitions, lifecycle hooks)'
423 - 'Choosing what to emit vs what to skip'
424 - 'Consolidating multiple events into single meaningful emissions'
425 - 'Performance-aware emission patterns'
426 - 'Middleware/interceptor integration patterns'
427 - 'Observer/subscription emission patterns'
428 tasks:
429 - 'Instrument my library with devtools events'
430 - 'Find the right places to emit events in my codebase'
431 - 'Emit one meaningful event instead of many noisy ones'
432 - 'Add devtools support to my state management library'
433 - 'Instrument middleware pipelines for debugging'
434 failure_modes:
435 - mistake: 'Emitting too many granular events'
436 mechanism: >
437 Emitting 15 events for what could be 1 consolidated event creates
438 noise in the devtools panel and performance overhead. Consolidate
439 related state changes into single emissions.
440 wrong_pattern: |
441 function processRequest(req) {
442 client.emit('request-start', { id: req.id })
443 client.emit('request-parsed', { body: req.body })
444 client.emit('request-validated', { valid: true })
445 client.emit('middleware-1-start', {})
446 client.emit('middleware-1-end', {})
447 // ... 10 more events
448 }
449 correct_pattern: |
450 function processRequest(req) {
451 const result = runPipeline(req)
452 client.emit('request-processed', {
453 id: req.id,
454 duration: result.duration,
455 middlewareChain: result.middlewareNames,
456 status: result.status,
457 })
458 }
459 source: 'maintainer interview'
460 priority: 'HIGH'
461 status: 'active'
462β
463 - mistake: 'Emitting in hot loops without debouncing'
464 mechanism: >
465 Emitting events inside tight loops or rapid state updates causes
466 performance degradation. Events should be debounced or batched
467 for high-frequency operations.
468 source: 'docs/bidirectional-communication.md'
469 priority: 'HIGH'
470 status: 'active'
471β
472 - mistake: 'Not emitting at architecture boundaries'
473 mechanism: >
474 The highest-value emission points are architecture boundaries:
475 before/after middleware, on state transitions, at lifecycle hooks.
476 Emitting inside implementation details misses the forest for trees.
477 source: 'maintainer interview'
478 priority: 'MEDIUM'
479 status: 'active'
480β
481 - name: 'Plugin panel development'
482 slug: 'plugin-panel-development'
483 domain: 'plugin-development'
484 description: >
485 Build the devtools panel component that displays data emitted by
486 your library. Use devtools-ui components, handle theming, and
487 manage event listener lifecycle.
488 type: 'core'
489 packages:
490 - '@tanstack/devtools-ui'
491 - '@tanstack/devtools-event-client'
492 covers:
493 - 'Panel component structure'
494 - 'Listening to events via on()'
495 - 'Theme handling (light/dark)'
496 - 'devtools-ui components (JSONTree, buttons, inputs, sections)'
497 - 'Plugin registration (name, render, id, defaultOpen)'
498 - 'Plugin lifecycle (mount, activate, destroy)'
499 - 'Max 3 concurrent active plugins'
500 - 'localStorage state persistence'
501 - 'Two paths: Solid.js core with devtools-ui for multi-framework, or framework-specific panels directly'
502 - 'Transparent server/client event bridging (emit on server, receive on client and vice versa)'
503 tasks:
504 - 'Build a panel that displays my library state'
505 - 'Use devtools-ui JSON viewer to show data'
506 - 'Handle dark/light theme in my panel'
507 - 'Register my panel as a devtools plugin'
508 - 'Set my plugin to open by default'
509 failure_modes:
510 - mistake: 'Not cleaning up event listeners'
511 mechanism: >
512 Each on() call returns a cleanup function. Forgetting to call it
513 in useEffect cleanup (React), onCleanup (Solid), or onUnmounted
514 (Vue) causes memory leaks and duplicate handlers on re-render.
515 wrong_pattern: |
516 useEffect(() => {
517 client.on('state', (e) => setState(e.payload))
518 // Missing cleanup!
519 }, [])
520 correct_pattern: |
521 useEffect(() => {
522 const cleanup = client.on('state', (e) => setState(e.payload))
523 return cleanup
524 }, [])
525 source: 'docs/building-custom-plugins.md, docs/event-system.md'
526 priority: 'CRITICAL'
527 status: 'active'
528β
529 - mistake: 'Ignoring theme prop in panel component'
530 mechanism: >
531 The render function receives theme as second argument. Panel
532 components should adapt their styling. Agents often hardcode
533 light or dark styles.
534 source: 'docs/plugin-lifecycle.md'
535 priority: 'MEDIUM'
536 status: 'active'
537β
538 - mistake: 'Not knowing max 3 active plugins limit'
539 mechanism: >
540 At most 3 plugin panels can be displayed simultaneously
541 (MAX_ACTIVE_PLUGINS constant). Setting more than 3 plugins
542 to defaultOpen:true only opens the first 3.
543 source: 'packages/devtools/src/utils/get-default-active-plugins.ts'
544 priority: 'MEDIUM'
545 status: 'active'
546β
547 - mistake: 'Using raw DOM manipulation instead of framework portals'
548 mechanism: >
549 Plugin render() receives a DOM element, but framework adapters
550 handle portaling automatically. Agents might try to manually
551 manipulate the DOM instead of using the adapter pattern.
552 source: 'docs/plugin-lifecycle.md'
553 priority: 'MEDIUM'
554 status: 'active'
555β
556 - mistake: 'Oversubscribing to events in multiple places'
557 mechanism: >
558 AI agents subscribe to the same event in 5 different components
559 instead of subscribing once and sharing state. This creates
560 duplicate handlers, wasted memory, and inconsistent state.
561 wrong_pattern: |
562 // Component A subscribes
563 client.on('state', (e) => setStateA(e.payload))
564 // Component B also subscribes to same event
565 client.on('state', (e) => setStateB(e.payload))
566 // Component C also subscribes...
567 client.on('state', (e) => setStateC(e.payload))
568 correct_pattern: |
569 // Subscribe once in a shared store/context
570 const cleanup = client.on('state', (e) => {
571 sharedStore.setState(e.payload)
572 })
573 // Components read from the shared store
574 source: 'maintainer interview'
575 priority: 'HIGH'
576 status: 'active'
577β
578 - mistake: 'Hardcoding repeated event payload fields'
579 mechanism: >
580 When multiple events share common fields (name, type, version),
581 agents hardcode each field separately instead of creating a shared
582 object and spreading it. Makes code harder to maintain.
583 wrong_pattern: |
584 client.emit('created', { name: lib.name, type: lib.type, version: lib.version, action: 'create' })
585 client.emit('updated', { name: lib.name, type: lib.type, version: lib.version, action: 'update' })
586 client.emit('deleted', { name: lib.name, type: lib.type, version: lib.version, action: 'delete' })
587 correct_pattern: |
588 const baseInfo = { name: lib.name, type: lib.type, version: lib.version }
589 client.emit('created', { ...baseInfo, action: 'create' })
590 client.emit('updated', { ...baseInfo, action: 'update' })
591 client.emit('deleted', { ...baseInfo, action: 'delete' })
592 source: 'maintainer interview'
593 priority: 'MEDIUM'
594 status: 'active'
595 skills: ['plugin-panel-development', 'strategic-instrumentation']
596β
597 - mistake: 'Not keeping devtools packages at latest versions'
598 mechanism: >
599 Agents pin or use old versions of devtools packages. While exact
600 version sync is not required, using latest versions across all
601 devtools packages increases stability and compatibility.
602 source: 'maintainer interview'
603 priority: 'MEDIUM'
604 status: 'active'
605 skills: ['app-setup', 'plugin-panel-development']
606β
607 - name: 'Framework adapters'
608 slug: 'framework-adapters'
609 domain: 'framework-adaptation'
610 description: >
611 Use devtools-utils factory functions to create per-framework plugin
612 adapters with NoOp variants for production tree-shaking.
613 type: 'framework'
614 packages:
615 - '@tanstack/devtools-utils'
616 covers:
617 - 'createReactPlugin() / createReactPanel()'
618 - 'createSolidPlugin() / createSolidPanel()'
619 - 'createVuePlugin() / createVuePanel()'
620 - 'createPreactPlugin() / createPreactPanel()'
621 - '[Plugin, NoOpPlugin] tuple pattern'
622 - 'DevtoolsPanelProps (theme prop)'
623 - 'Class-based panel factories'
624 - 'Framework-specific portal/teleport mechanisms'
625 tasks:
626 - 'Create React and Solid adapters for my plugin'
627 - 'Use factory functions to build framework adapters'
628 - 'Set up production tree-shaking with NoOp variants'
629 - 'Build a class-based devtools core with panel wrappers'
630 subsystems:
631 - name: 'React adapter'
632 package: '@tanstack/devtools-utils'
633 config_surface: 'createReactPlugin({name, id, defaultOpen, Component})'
634 - name: 'Solid adapter'
635 package: '@tanstack/devtools-utils'
636 config_surface: 'createSolidPlugin({name, id, defaultOpen, Component})'
637 - name: 'Vue adapter'
638 package: '@tanstack/devtools-utils'
639 config_surface: 'createVuePlugin(name, component)'
640 - name: 'Preact adapter'
641 package: '@tanstack/devtools-utils'
642 config_surface: 'createPreactPlugin({name, id, defaultOpen, Component})'
643 failure_modes:
644 - mistake: 'Using React JSX pattern in Vue adapter'
645 mechanism: >
646 Vue uses component reference + props, not JSX render elements.
647 createVuePlugin takes (name, component) not an options object.
648 wrong_pattern: |
649 const [Plugin] = createVuePlugin({
650 name: 'My Plugin',
651 Component: MyPanel,
652 })
653 correct_pattern: |
654 const [Plugin] = createVuePlugin('My Plugin', MyPanel)
655 source: 'packages/devtools-utils/src/vue/plugin.ts'
656 priority: 'CRITICAL'
657 status: 'active'
658β
659 - mistake: 'Solid render prop not wrapped in function'
660 mechanism: >
661 Solid requires render to be a function returning JSX, not raw JSX.
662 Passing raw JSX causes it to evaluate immediately and not react
663 to signal changes.
664 wrong_pattern: |
665 <TanStackDevtools
666 plugins={[{
667 name: 'My Plugin',
668 render: <MyPanel />,
669 }]}
670 />
671 correct_pattern: |
672 <TanStackDevtools
673 plugins={[{
674 name: 'My Plugin',
675 render: () => <MyPanel />,
676 }]}
677 />
678 source: 'docs/framework/solid/adapter.md'
679 priority: 'CRITICAL'
680 status: 'active'
681β
682 - mistake: 'Ignoring NoOp variant for production'
683 mechanism: >
684 Factory functions return [Plugin, NoOpPlugin] tuple. The NoOp
685 variant renders nothing and is meant for production builds.
686 Ignoring it means devtools code ships to production.
687 wrong_pattern: |
688 const [MyPlugin] = createReactPlugin({ ... })
689 // Always uses MyPlugin, even in production
690 correct_pattern: |
691 const [MyPlugin, NoOpPlugin] = createReactPlugin({ ... })
692 const ActivePlugin = process.env.NODE_ENV === 'development'
693 ? MyPlugin
694 : NoOpPlugin
695 source: 'docs/devtools-utils.md'
696 priority: 'HIGH'
697 status: 'active'
698β
699 - mistake: 'Not passing theme prop to panel component'
700 mechanism: >
701 Factory-created plugins receive DevtoolsPanelProps with theme.
702 Agent might destructure props but not use theme, resulting in
703 panel that doesnt match devtools dark/light mode.
704 source: 'packages/devtools-utils/src/react/plugin.tsx'
705 priority: 'MEDIUM'
706 status: 'active'
707β
708 - name: 'Bidirectional communication'
709 slug: 'bidirectional-communication'
710 domain: 'event-communication'
711 description: >
712 Implement two-way event patterns between the devtools panel and
713 application: commands, state editing, and time-travel debugging.
714 type: 'core'
715 packages:
716 - '@tanstack/devtools-event-client'
717 covers:
718 - 'App-to-devtools observation pattern'
719 - 'Devtools-to-app command pattern'
720 - 'Time-travel debugging with snapshots and revert'
721 - 'Bidirectional event map design'
722 - 'structuredClone for snapshot safety'
723 - 'Debouncing frequent emissions'
724 tasks:
725 - 'Add a reset button to my devtools panel'
726 - 'Implement state editing from devtools'
727 - 'Build time-travel debugging for my state library'
728 - 'Send commands from devtools panel back to app'
729 failure_modes:
730 - mistake: 'Not using structuredClone for snapshots'
731 mechanism: >
732 Passing state object references directly means future mutations
733 corrupt historical snapshots. Must deep-clone before emitting.
734 wrong_pattern: |
735 client.emit('snapshot', { state, timestamp: Date.now() })
736 correct_pattern: |
737 client.emit('snapshot', {
738 state: structuredClone(state),
739 timestamp: Date.now(),
740 })
741 source: 'docs/bidirectional-communication.md'
742 priority: 'HIGH'
743 status: 'active'
744β
745 - mistake: 'Not distinguishing observation from command events'
746 mechanism: >
747 Mixing observation and command events in the same namespace causes
748 confusion. Use distinct suffixes like state-update (observation)
749 vs set-state (command).
750 source: 'docs/bidirectional-communication.md'
751 priority: 'MEDIUM'
752 status: 'active'
753β
754 - mistake: 'Non-serializable payloads in cross-tab scenarios'
755 mechanism: >
756 Events crossing tab/process boundaries are JSON-serialized.
757 Functions, DOM nodes, and circular references silently fail.
758 source: 'packages/event-bus/src/utils/json.ts'
759 priority: 'HIGH'
760 status: 'active'
761 skills: ['event-client-creation', 'bidirectional-communication']
762β
763 - name: 'Production setup'
764 slug: 'production-setup'
765 domain: 'build-production'
766 description: >
767 Handle devtools in production vs development: tree-shaking,
768 conditional imports, Vite stripping, and dev-only dependencies.
769 type: 'lifecycle'
770 packages:
771 - '@tanstack/devtools-vite'
772 - '@tanstack/devtools'
773 covers:
774 - 'removeDevtoolsOnBuild option'
775 - 'Dev dependency vs regular dependency'
776 - '/production sub-export'
777 - 'Conditional imports with environment variables'
778 - 'NoOp plugin variants for tree-shaking'
779 - 'Non-Vite production exclusion patterns'
780 tasks:
781 - 'Strip devtools from production build'
782 - 'Keep devtools in production intentionally'
783 - 'Set up conditional devtools loading'
784 - 'Handle production builds without Vite'
785 failure_modes:
786 - mistake: 'Keeping devtools in production without disabling stripping'
787 mechanism: >
788 Setting removeDevtoolsOnBuild defaults to true. If you want
789 devtools in production, you must explicitly set it to false AND
790 install as regular dependency.
791 wrong_pattern: |
792 // vite.config.ts - devtools stripped silently
793 devtools()
794 // package.json - devDependency won't be available
795 "devDependencies": { "@tanstack/react-devtools": "..." }
796 correct_pattern: |
797 // vite.config.ts
798 devtools({ removeDevtoolsOnBuild: false })
799 // package.json - regular dependency
800 "dependencies": { "@tanstack/react-devtools": "..." }
801 source: 'docs/production.md'
802 priority: 'HIGH'
803 status: 'active'
804β
805 - mistake: 'Not using /production sub-export for production builds'
806 mechanism: >
807 Production builds should use the /production sub-export which
808 includes only production-safe code without dev-only features.
809 source: 'docs/production.md'
810 priority: 'MEDIUM'
811 status: 'active'
812β
813 - mistake: 'Non-Vite projects not excluding devtools manually'
814 mechanism: >
815 Without the Vite plugin, devtools are not automatically stripped.
816 Non-Vite projects must manually exclude via environment variables
817 or conditional imports.
818 wrong_pattern: |
819 // Always imports devtools regardless of environment
820 import { TanStackDevtools } from '@tanstack/react-devtools'
821 correct_pattern: |
822 const Devtools = process.env.NODE_ENV === 'development'
823 ? await import('./devtools-setup')
824 : () => null
825 source: 'docs/production.md'
826 priority: 'HIGH'
827 status: 'active'
828β
829 - name: 'Marketplace publishing'
830 slug: 'marketplace-publishing'
831 domain: 'plugin-development'
832 description: >
833 Publish a devtools plugin to npm and submit it to the TanStack
834 Devtools Marketplace registry for discovery and one-click install.
835 type: 'lifecycle'
836 packages:
837 - '@tanstack/devtools'
838 covers:
839 - 'PluginMetadata registry format'
840 - 'plugin-registry.ts submission'
841 - 'pluginImport configuration (importName, type)'
842 - 'requires field (packageName, minVersion, maxVersion)'
843 - 'Framework tagging'
844 - 'Multi-framework submissions'
845 - 'Featured plugins'
846 tasks:
847 - 'Submit my plugin to the TanStack Marketplace'
848 - 'Configure plugin metadata for auto-install'
849 - 'Submit plugins for multiple frameworks'
850 failure_modes:
851 - mistake: 'Missing pluginImport metadata for auto-install'
852 mechanism: >
853 Without pluginImport.importName and pluginImport.type, the
854 marketplace cant auto-inject the plugin into user code.
855 The install button will add the package but not wire it up.
856 source: 'docs/third-party-plugins.md, packages/devtools-vite/src/inject-plugin.ts'
857 priority: 'HIGH'
858 status: 'active'
859β
860 - mistake: 'Not specifying requires.minVersion'
861 mechanism: >
862 If your plugin depends on a minimum version of another library,
863 omitting minVersion means users with older versions will get
864 runtime errors.
865 source: 'docs/third-party-plugins.md'
866 priority: 'MEDIUM'
867 status: 'active'
868β
869 - mistake: 'Submitting without framework field'
870 mechanism: >
871 The framework field enables filtering in the marketplace UI.
872 Without it, users cant find framework-specific plugins.
873 source: 'docs/third-party-plugins.md'
874 priority: 'MEDIUM'
875 status: 'active'
876β
877tensions:
878 - name: 'Instrumentation completeness vs performance'
879 skills: ['strategic-instrumentation', 'event-client-creation']
880 description: >
881 Strategic instrumentation wants comprehensive debugging data, but
882 emitting too many events degrades application performance. Events
883 crossing WebSocket/SSE boundaries add latency.
884 implication: >
885 An agent optimizing for debugging coverage will emit events in hot
886 paths and tight loops. An agent optimizing for performance will skip
887 critical debugging points. The right balance is architecture-boundary
888 emissions with debouncing for high-frequency updates.
889β
890 - name: 'Development convenience vs production safety'
891 skills: ['app-setup', 'production-setup']
892 description: >
893 Easy dev setup (devDependencies, auto-stripping) conflicts with
894 production usage where you need regular deps and explicit opt-in.
895 implication: >
896 An agent setting up devtools will install as devDependency and rely
897 on Vite stripping. If the user later wants production devtools, the
898 agent needs to undo those decisions β change to regular dep, disable
899 stripping, use production sub-export.
900β
901 - name: 'Framework-agnostic core vs framework ergonomics'
902 skills: ['framework-adapters', 'plugin-panel-development']
903 description: >
904 The Solid.js core provides consistency but framework adapters have
905 different patterns. Vue uses component not render, Solid requires
906 function wrappers, React uses JSX directly.
907 implication: >
908 An agent trained on React patterns will use render/JSX everywhere.
909 Vue and Solid have fundamentally different plugin definitions that
910 agents consistently get wrong without framework-specific guidance.
911β
912cross_references:
913 - from: 'app-setup'
914 to: 'vite-plugin'
915 reason: >
916 After basic setup, Vite plugin adds enhanced features. Agent should
917 know Vite plugin is optional but recommended.
918β
919 - from: 'event-client-creation'
920 to: 'strategic-instrumentation'
921 reason: >
922 After creating an EventClient, the next step is instrumenting code.
923 Understanding the event system informs where to emit.
924β
925 - from: 'event-client-creation'
926 to: 'plugin-panel-development'
927 reason: >
928 The EventClient emits events that the panel listens to. Both sides
929 must use the same event map and understand the pluginId namespacing.
930β
931 - from: 'plugin-panel-development'
932 to: 'framework-adapters'
933 reason: >
934 After building a panel, wrapping it in framework adapters makes it
935 usable across React, Vue, Solid, and Preact.
936β
937 - from: 'framework-adapters'
938 to: 'production-setup'
939 reason: >
940 NoOp variants from factory functions are the primary mechanism for
941 production tree-shaking.
942β
943 - from: 'bidirectional-communication'
944 to: 'event-client-creation'
945 reason: >
946 Bidirectional patterns extend the event client with command events.
947 Understanding the base event system is prerequisite.
948β
949 - from: 'vite-plugin'
950 to: 'production-setup'
951 reason: >
952 The Vite plugin handles production stripping. Understanding its
953 defaults informs production configuration decisions.
954β
955 - from: 'plugin-panel-development'
956 to: 'marketplace-publishing'
957 reason: >
958 After building a working plugin, publishing to the marketplace is
959 the distribution step. Plugin metadata must match the code.
960β
961 - from: 'strategic-instrumentation'
962 to: 'bidirectional-communication'
963 reason: >
964 Strategic emission points often benefit from bidirectional patterns β
965 not just showing state but allowing developers to interact with it.
966β
967gaps:
968 - skill: 'strategic-instrumentation'
969 question: >
970 What are the specific telemetry/instrumentation patterns built into
971 TanStack Devtools that the maintainer mentioned are undocumented?
972 context: >
973 Maintainer said telemetry support details are missing from docs.
974 To be investigated from source code.
975 status: 'resolved'
976β
977 - skill: 'plugin-panel-development'
978 question: >
979 How does the Picture-in-Picture (PiP) window mode affect plugin
980 rendering? Do plugins need to handle PiP-specific concerns?
981 context: >
982 PiP opens a new browser window and renders devtools there. Has zero
983 impact on plugin development β works seamlessly with no special handling.
984 status: 'resolved'
985β
986 - skill: 'event-client-creation'
987 question: >
988 Are there recommended patterns for testing EventClient instances
989 and plugin panels in isolation (unit tests, integration tests)?
990 context: >
991 No recommended testing patterns exist currently. EventClient works
992 for same-page communication without the full devtools shell.
993 status: 'resolved'
994β
995 - skill: 'strategic-instrumentation'
996 question: >
997 What are the performance benchmarks for event emission? How many
998 events per second can the bus handle before degradation?
999 context: >
1000 No formal benchmarks exist. General guidance: prototype freely with
1001 many events, then reduce emission count for production. Debounce
1002 high-frequency updates.
1003 status: 'resolved'