tanstack-plugin-storybook-devtools

A TanStack Devtools plugin that brings Storybook's component highlighting and story generation into your running app.

Hover over components, inspect props, and generate .stories.tsx files — all from the TanStack Devtools panel.

---

How it works

Browser overlay (floating, over your app)
  ↓ user right-clicks → "Create Story"
  ↓ EventClient.emit('storybook-devtools:create-story', payload)
  ↓ ClientEventBus → WebSocket → ServerEventBus
  ↓ Vite plugin listener (writes .stories.tsx file)
  ↓ WebSocket broadcast back to browser
  ↓ EventClient.on('storybook-devtools:story-created') → overlay shows ✅

The overlay floats over your app (managed by the peer dependency vite-plugin-experimental-storybook-devtools). The TanStack Devtools panel tab provides the activate/deactivate button and last-created story confirmation.

---

Installation

pnpm add tanstack-plugin-storybook-devtools @tanstack/devtools-event-client
pnpm add -D @tanstack/react-devtools @tanstack/devtools-vite vite-plugin-experimental-storybook-devtools

---

Setup

1. Vite config

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tanstackDevtools from '@tanstack/devtools-vite'
import { storybookDevtoolsVitePlugin } from 'tanstack-plugin-storybook-devtools/vite'
import componentHighlighter from 'vite-plugin-experimental-storybook-devtools/react'

export default defineConfig({
  plugins: [
    react(),
    // TanStack Devtools must come before our plugin (starts the ServerEventBus)
    tanstackDevtools(),
    // Our Vite plugin listens on the ServerEventBus for create-story events
    storybookDevtoolsVitePlugin({ framework: 'react' }),
    // Component AST transform (injects registerComponentSource calls)
    componentHighlighter(),
  ],
})

2. App entry

// src/main.tsx (or App.tsx)
import { TanStackDevtools } from '@tanstack/react-devtools'
import { createStorybookDevtoolsPlugin } from 'tanstack-plugin-storybook-devtools/react'

const storybookPlugin = createStorybookDevtoolsPlugin()

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && (
        <TanStackDevtools plugins={[storybookPlugin]} />
      )}
    </>
  )
}

---

Usage

1. Open TanStack Devtools (bottom-right button).
2. Click the Storybook tab.
3. Click ▶ Start Highlighting.
4. Hover over components — they highlight with a pink border.
5. Hold Alt to highlight all visible components.
6. Right-click a component → Create Story.
7. A .stories.tsx file is created next to the component.
8. The panel shows ✅ confirmation with the file path.

Keyboard shortcuts

Key	Action
Alt (hold)	Highlight all components
Shift+H	Sticky highlight-all mode
Esc	Clear selection

---

Options

storybookDevtoolsVitePlugin(options)

Option	Type	Default	Description
writeStoryFiles	boolean	true	Automatically write story files
storiesDir	string	(none)	Subdirectory for stories (relative to component)
framework	'react' | 'vue'	'react'	Story generator to use

createStorybookDevtoolsPlugin(options)

Option	Type	Default	Description
transport	HighlighterTransport	TanStack EventClient	Custom transport adapter

---

Custom transport

If you want to use the highlighter without TanStack DevTools or with a different communication layer, implement HighlighterTransport:

import type { HighlighterTransport } from 'tanstack-plugin-storybook-devtools'

const myTransport: HighlighterTransport = {
  async createStory(data) {
    await fetch('/api/create-story', {
      method: 'POST',
      body: JSON.stringify(data),
    })
  },
  onStoryCreated(handler) {
    const listener = (e: MessageEvent) => {
      if (e.data.type === 'story-created') handler(e.data.payload)
    }
    window.addEventListener('message', listener)
    return () => window.removeEventListener('message', listener)
  },
}

---

Architecture

packages/
  src/
    types.ts          — shared types + HighlighterTransport interface
    transport.ts      — TanStack EventClient-backed transport
    highlighter.ts    — overlay activation (framework-agnostic)
    react/
      HighlighterPanel.tsx  — React panel UI component
      index.tsx             — createStorybookDevtoolsPlugin() factory
    vite/
      index.ts        — Vite plugin (server-side story file writer)

---

License

MIT