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

skill_spec.md

172 lines16.5 KB

TanStack Devtools β€” Skill Spec

TanStack 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.

Domains

DomainDescriptionSkills
Setting up devtoolsInstalling, configuring, and mounting devtools in an appapp-setup
Building pluginsCreating custom plugins: event clients, panels, marketplaceplugin-panel-development, marketplace-publishing
Event communicationTyped event system for plugin data flowevent-client-creation, bidirectional-communication
Framework adaptationPer-framework adapters using factory functionsframework-adapters
Build and productionVite plugin features and production concernsvite-plugin, production-setup
Library instrumentationStrategic event emission placement in codebasesstrategic-instrumentation

Skill Inventory

SkillTypeDomainWhat it coversFailure modes
app-setupcoresetupTanStackDevtools component, plugins prop, config, framework adapters4
vite-plugincorebuild-productionSource injection, console piping, enhanced logs, production stripping, server bus5
event-client-creationcoreevent-communicationEventClient class, event maps, connection lifecycle, namespacing7
strategic-instrumentationcoreinstrumentationFinding critical emission points, consolidation, performance3
plugin-panel-developmentcoreplugin-developmentPanel components, event listening, theming, devtools-ui7
framework-adaptersframeworkframework-adaptationcreateReactPlugin, createSolidPlugin, createVuePlugin, NoOp variants4
bidirectional-communicationcoreevent-communicationCommands, state editing, time-travel, structuredClone3
production-setuplifecyclebuild-productionremoveDevtoolsOnBuild, conditional imports, NoOp patterns3
marketplace-publishinglifecycleplugin-developmentPluginMetadata, registry format, auto-install config3

Failure Mode Inventory

app-setup (4 failure modes)

#MistakePrioritySourceCross-skill?
1Vite plugin not placed first in plugins arrayHIGHdocs/vite-plugin.mdvite-plugin
2Vue plugin uses render instead of componentCRITICALdocs/framework/vue/adapter.mdframework-adapters
3Installing as regular dep for dev-only useMEDIUMdocs/installation.mdβ€”
4Mounting TanStackDevtools in SSR without client guardHIGHpackages/devtools/src/core.tsβ€”

vite-plugin (5 failure modes)

#MistakePrioritySourceCross-skill?
1Expecting Vite plugin features in productionMEDIUMpackages/devtools-vite/src/plugin.tsβ€”
2Not placing devtools() first in Vite pluginsHIGHdocs/vite-plugin.mdapp-setup
3Source injection on spread props elementsMEDIUMpackages/devtools-vite/src/inject-source.tsβ€”
4Using devtools-vite with non-Vite bundlersHIGHpackages/devtools-vite/package.jsonβ€”
5Event bus port conflict in multi-project setupsMEDIUMpackages/event-bus/src/server/server.tsβ€”

event-client-creation (7 failure modes)

#MistakePrioritySourceCross-skill?
1Including pluginId prefix in event namesCRITICALpackages/event-bus-client/src/plugin.tsβ€”
2Creating multiple EventClient instances per pluginCRITICALdocs/building-custom-plugins.mdβ€”
3Non-unique pluginId causing event collisionsCRITICALmaintainer interviewβ€”
4Not realizing events drop after 5 failed retriesHIGHpackages/event-bus-client/src/plugin.tsβ€”
5Listening before emitting and expecting connectionHIGHpackages/event-bus-client/src/plugin.tsβ€”
6Using non-serializable payloadsHIGHpackages/event-bus/src/utils/json.tsbidirectional-communication
7Not stripping EventClient emit calls for productionHIGHmaintainer interviewproduction-setup

strategic-instrumentation (3 failure modes)

#MistakePrioritySourceCross-skill?
1Emitting too many granular eventsHIGHmaintainer interviewβ€”
2Emitting in hot loops without debouncingHIGHdocs/bidirectional-communication.mdβ€”
3Not emitting at architecture boundariesMEDIUMmaintainer interviewβ€”

plugin-panel-development (7 failure modes)

#MistakePrioritySourceCross-skill?
1Not cleaning up event listenersCRITICALdocs/building-custom-plugins.mdβ€”
2Oversubscribing to events in multiple placesHIGHmaintainer interviewβ€”
3Hardcoding repeated event payload fieldsMEDIUMmaintainer interviewstrategic-instrumentation
4Ignoring theme prop in panel componentMEDIUMdocs/plugin-lifecycle.mdβ€”
5Not knowing max 3 active plugins limitMEDIUMpackages/devtools/src/utils/get-default-active-plugins.tsβ€”
6Using raw DOM manipulation instead of framework portalsMEDIUMdocs/plugin-lifecycle.mdβ€”
7Not keeping devtools packages at latest versionsMEDIUMmaintainer interviewapp-setup

framework-adapters (4 failure modes)

#MistakePrioritySourceCross-skill?
1Using React JSX pattern in Vue adapterCRITICALpackages/devtools-utils/src/vue/plugin.tsapp-setup
2Solid render prop not wrapped in functionCRITICALdocs/framework/solid/adapter.mdβ€”
3Ignoring NoOp variant for productionHIGHdocs/devtools-utils.mdproduction-setup
4Not passing theme prop to panel componentMEDIUMpackages/devtools-utils/src/react/plugin.tsxβ€”

bidirectional-communication (3 failure modes)

#MistakePrioritySourceCross-skill?
1Not using structuredClone for snapshotsHIGHdocs/bidirectional-communication.mdβ€”
2Not distinguishing observation from command eventsMEDIUMdocs/bidirectional-communication.mdβ€”
3Non-serializable payloads in cross-tab scenariosHIGHpackages/event-bus/src/utils/json.tsevent-client-creation

production-setup (3 failure modes)

#MistakePrioritySourceCross-skill?
1Keeping devtools in prod without disabling strippingHIGHdocs/production.mdβ€”
2Not using /production sub-exportMEDIUMdocs/production.mdβ€”
3Non-Vite projects not excluding devtools manuallyHIGHdocs/production.mdβ€”

marketplace-publishing (3 failure modes)

#MistakePrioritySourceCross-skill?
1Missing pluginImport metadata for auto-installHIGHdocs/third-party-plugins.mdβ€”
2Not specifying requires.minVersionMEDIUMdocs/third-party-plugins.mdβ€”
3Submitting without framework fieldMEDIUMdocs/third-party-plugins.mdβ€”

Tensions

TensionSkillsAgent implication
Instrumentation completeness vs performancestrategic-instrumentation ↔ event-client-creationAgent optimizing for debugging coverage emits in hot paths; agent optimizing for performance skips critical points
Development convenience vs production safetyapp-setup ↔ production-setupAgent installs as devDep with stripping; later production usage requires undoing those decisions
Framework-agnostic core vs framework ergonomicsframework-adapters ↔ plugin-panel-developmentAgent trained on React uses render/JSX everywhere; Vue and Solid have different plugin definitions

Cross-References

FromToReason
app-setupvite-pluginVite plugin adds enhanced features after basic setup
event-client-creationstrategic-instrumentationUnderstanding event system informs where to emit
event-client-creationplugin-panel-developmentClient emits, panel listens β€” same event map
plugin-panel-developmentframework-adaptersAfter building panel, wrap in framework adapters
framework-adaptersproduction-setupNoOp variants are the primary tree-shaking mechanism
bidirectional-communicationevent-client-creationBidirectional extends the base event system
vite-pluginproduction-setupVite plugin handles production stripping defaults
plugin-panel-developmentmarketplace-publishingAfter building plugin, publish to marketplace
strategic-instrumentationbidirectional-communicationEmission points benefit from bidirectional patterns

Subsystems & Reference Candidates

SkillSubsystemsReference candidates
vite-pluginSource injection, Console piping, Enhanced logging, Production stripping, Server event bus, Editor integrationVite plugin options reference
framework-adaptersReact adapter, Solid adapter, Vue adapter, Preact adapterβ€”
app-setupβ€”Config options (position, hotkeys, theme, eventBus)
event-client-creationβ€”EventClient constructor options, connection lifecycle states

Remaining Gaps

All gaps resolved during maintainer interview:

  • PiP window mode has zero impact on plugin development
  • No formal testing patterns exist; EventClient works standalone for same-page communication
  • No performance benchmarks; guidance is to prototype freely, reduce for production
  • Telemetry patterns to be derived from source code analysis
  • Core skills: app-setup, event-client-creation, strategic-instrumentation, plugin-panel-development, bidirectional-communication
  • Framework skills: framework-adapters (covers all four frameworks with subsystem files)
  • Lifecycle skills: production-setup, marketplace-publishing
  • Composition skills: none needed (devtools is the composition primitive itself)
  • Reference files: vite-plugin (6 subsystems with distinct config surfaces)

Composition Opportunities

LibraryIntegration pointsComposition skill needed?
TanStack QueryQuery devtools panel pluginNo β€” TanStack Query ships its own devtools panel
TanStack RouterRouter devtools panel pluginNo β€” TanStack Router ships its own devtools panel
TanStack FormForm devtools panel pluginNo β€” TanStack Form ships its own devtools panel
ViteBuild tooling integrationNo β€” covered by vite-plugin skill
Any state/data libraryEventClient instrumentationYes β€” strategic-instrumentation skill