@u-devtools/plugin-componentsbook

Interactive component development and documentation plugin for Universal DevTools. Create component stories alongside your Vue components and interact with them directly in the DevTools panel.

Features

- Zero Configuration: No need to register stories in config files. Just create .stories.vue files next to your components
- Auto Analysis: Automatically extracts props, events, and slots from your components using vue-docgen-api
- Interactive Controls: Live prop editing with automatic UI generation based on prop types (text, number, checkbox, select, JSON)
- Three Preview Modes: Stories, Playground, and Matrix views for different use cases
- Real-time Updates: Hot Module Replacement (HMR) support - changes to story files update instantly
- Isolated Rendering: Stories render in an isolated overlay layer, but have access to your app's context (Pinia, Router, etc.)
- Full Documentation: View comprehensive documentation tables for props, events, and slots
- Code Generation: See generated Vue code for your component usage with freeze/copy functionality
- Canvas Tools: Viewport controls, zoom, background options (grid, light, dark, transparent)

Installation

``bash
pnpm add -D @u-devtools/plugin-componentsbook
`

Setup

Add the plugin to your vite.config.ts:

`typescript
import { defineConfig } from 'vite';
import { componentsbookPlugin } from '@u-devtools/plugin-componentsbook';

export default defineConfig({
plugins: [
componentsbookPlugin(),
// ... other plugins
],
});
`

File Structure

The plugin works on the principle of co-location. Story files should be placed next to their components with the .stories.vue suffix.

`
src/
components/
Button/
Button.vue ← Your component
Button.stories.vue ← Story for DevTools
Card.vue
Card.stories.vue
`

Creating Stories

$3

A story file is a regular Vue component that exports your component as the default export:

`vue



`

$3

For better experience in Playground and Matrix modes, you can export the clean component separately:

`vue



`

$3

Use the block to add markdown documentation that will be displayed in the DevTools panel:

`vue



Button Component

Button is the primary interaction element in the interface.

Usage

Use variant="primary" for primary actions.

Usage example:


`

Preview Modes

The plugin provides three different preview modes, each optimized for different use cases:

$3

Purpose: View your story file exactly as written, with all variants and examples.

- Renders the entire story component as-is
- Shows multiple component variants in one view
- Perfect for documentation and showcasing different use cases
- No interactive controls - pure presentation

Use when: You want to see all your examples together, like a showcase page.

$3

Purpose: Interactive component testing with live prop editing.

- Left Panel: Control panel with three tabs:
- Controls: Edit props with auto-generated UI (text inputs, checkboxes, selects, JSON editors)
- Events: View and log component events in real-time
- Code: See generated Vue code for current component usage
- Right Panel: Live preview of the component
- Uses the clean component (if exported) or falls back to story wrapper
- Canvas tools available: viewport sizes, zoom, background options

Use when: You want to test different prop combinations interactively.

$3

Purpose: View all possible prop combinations in a grid layout.

- Automatically generates combinations of all props
- Shows component variations in a matrix/grid
- Great for visual regression testing
- Uses the clean component (if exported) for better results

Use when: You want to see all possible states of your component at once.

Usage Examples

$3

The plugin automatically analyzes your component and creates controls. Props from the panel will automatically fall through to your component.

src/components/Button.vue (Source component)

`vue



`

src/components/Button.stories.vue (Story)

`vue



`

$3

If your component needs specific context (background, container, etc.), add it in the story:

src/components/Header.stories.vue

`vue



`

$3

You can use the story as a regular Vue component to show complex use cases:

src/components/Card.stories.vue

`vue



Card Component

Card is a universal container for grouping related content.



`

How It Works

$3

The plugin automatically scans your project for .stories.vue files and displays them in a file tree in the DevTools panel.

$3

When you select a story:
1. The plugin analyzes the source component (e.g., Button.vue) using vue-docgen-api
2. Extracts props, events, slots, and their types
3. Generates appropriate UI controls based on prop types:
- string → Text input
- number → Number input
- boolean → Checkbox (toggle switch)
- Union types ('primary' | 'secondary') → Select dropdown
- Objects/Arrays → JSON editor
- Smart detection for common boolean props (disabled, loading, is, has)

$3

In Playground mode:
- Controls Tab: Edit props with auto-generated UI. Changes update the preview in real-time
- Events Tab: View all events emitted by the component with timestamps and payloads
- Code Tab: See the generated Vue code for the current component usage. Freeze to copy code snippets

$3

Available in Stories and Playground modes:
- Viewport: Switch between responsive, mobile (375px), tablet (768px), desktop (1280px)
- Rotate: Rotate mobile/tablet viewports
- Zoom: Zoom in/out (0.2x - 3x)
- Background: Grid, light, dark, or transparent

Prop Type Detection

The plugin uses intelligent type detection:

1. Explicit Configuration: If you provide componentPropsMeta, it uses that
2. Value Type: Checks the current prop value type
3. Metadata Analysis: Uses vue-docgen-api type information
4. Heuristic Detection:
- Boolean keywords: disabled, loading, active, checked, selected, readonly, required, visible, open, show, hide, dense, outline, rounded, border, flat, solid, ghost
- Pattern matching: Props starting with is or has (e.g., isEnabled, hasError)

Key Features

- No Config: No need to register stories in config files. Just create a .stories.vue file
- Isolation: Stories render in an isolated overlay layer, but have access to Pinia, Router, and global plugins
- Hot Module Replacement (HMR): Editing .stories.vue files instantly updates the overlay without page reload
- Type Safety: Full TypeScript support with automatic type inference
- Documentation: Markdown documentation blocks displayed in the panel
- Code Generation: Automatic Vue code generation for component usage examples

Tips & Best Practices

1. Export Clean Component: Always export export const component = YourComponent for better Playground and Matrix experience
2. Use Stories Mode for Showcases: Create multiple variants in your story template for documentation
3. Use Playground Mode for Testing: Test edge cases and prop combinations interactively
4. Use Matrix Mode for Visual Testing: See all prop combinations at once for visual regression
5. Document with : Add markdown documentation to explain component usage
6. Name Props Clearly: Use descriptive prop names - the plugin will auto-detect types better

Development

`bash


Build

pnpm build

Type check

pnpm typecheck
``

License

MIT