0
# Storybook Vue 3 Renderer
1
2
Storybook Vue 3 renderer enables Vue 3 developers to create, document, and test UI components in isolation. It provides seamless integration between Storybook's component story framework and Vue 3's composition API and component architecture, offering comprehensive TypeScript support and portable story functionality.
3
4
## Package Information
5
6
- **Package Name**: @storybook/vue3
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/vue3`
10
11
## Core Imports
12
13
```typescript
14
import { Meta, StoryObj, setup } from "@storybook/vue3";
15
import { composeStory, composeStories, setProjectAnnotations } from "@storybook/vue3";
16
import { createTest } from "@storybook/vue3/experimental-playwright";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { Meta, StoryObj, setup, composeStory, composeStories, setProjectAnnotations } = require("@storybook/vue3");
23
const { createTest } = require("@storybook/vue3/experimental-playwright");
24
```
25
26
## Basic Usage
27
28
```typescript
29
import type { Meta, StoryObj } from "@storybook/vue3";
30
import MyButton from "./MyButton.vue";
31
32
// Component metadata
33
const meta: Meta<typeof MyButton> = {
34
title: "Example/Button",
35
component: MyButton,
36
parameters: {
37
layout: "centered",
38
},
39
argTypes: {
40
size: { control: "select", options: ["small", "medium", "large"] },
41
},
42
};
43
44
export default meta;
45
type Story = StoryObj<typeof meta>;
46
47
// Story definitions
48
export const Primary: Story = {
49
args: {
50
primary: true,
51
label: "Button",
52
},
53
};
54
55
export const Secondary: Story = {
56
args: {
57
label: "Button",
58
},
59
};
60
```
61
62
## Architecture
63
64
The Storybook Vue 3 renderer is built around several key systems:
65
66
- **Story Rendering Engine**: Core Vue 3 component rendering within Storybook's canvas environment
67
- **Type System**: Comprehensive TypeScript integration preserving Vue 3 component types and props
68
- **Portable Stories**: Ability to reuse stories outside Storybook for testing and documentation
69
- **Testing Integration**: Playwright component testing support and story composition utilities
70
- **Argument System**: Automatic prop extraction and reactive argument handling for Vue components
71
- **Plugin Architecture**: Vue app configuration and plugin setup system
72
73
## Capabilities
74
75
### Story Type Definitions
76
77
Complete TypeScript type system for Vue 3 component stories, including component metadata, story functions, and story objects with full type safety.
78
79
```typescript { .api }
80
type Meta<TCmpOrArgs = Args> = ComponentAnnotations<VueRenderer, ComponentPropsOrProps<TCmpOrArgs>>;
81
82
type StoryFn<TCmpOrArgs = Args> = AnnotatedStoryFn<VueRenderer, ComponentPropsOrProps<TCmpOrArgs>>;
83
84
type StoryObj<TMetaOrCmpOrArgs = Args> = StoryAnnotations<VueRenderer, ComponentPropsOrProps<TMetaOrCmpOrArgs>>;
85
86
type ComponentPropsAndSlots<C> = ComponentProps<C> & ExtractSlots<C>;
87
88
type VueRenderer = {
89
component: Component;
90
storyResult: StoryFnVueReturnType;
91
};
92
```
93
94
[Story Types](./story-types.md)
95
96
### Portable Story Composition
97
98
Create reusable story components for testing and external usage, allowing stories to be composed and rendered outside of Storybook environment.
99
100
```typescript { .api }
101
function setProjectAnnotations(
102
projectAnnotations: NamedOrDefaultProjectAnnotations<any> | NamedOrDefaultProjectAnnotations<any>[]
103
): NormalizedProjectAnnotations<VueRenderer>;
104
105
function composeStory<TArgs extends Args = Args>(
106
story: StoryAnnotationsOrFn<VueRenderer, TArgs>,
107
componentAnnotations: Meta<TArgs | any>,
108
projectAnnotations?: ProjectAnnotations<VueRenderer>,
109
exportsName?: string
110
): JSXAble<ComposedStoryFn<VueRenderer, Partial<TArgs>>>;
111
112
function composeStories<TModule extends Store_CSFExports<VueRenderer, any>>(
113
csfExports: TModule,
114
projectAnnotations?: ProjectAnnotations<VueRenderer>
115
): MapToJSXAble<Omit<StoriesWithPartialProps<VueRenderer, TModule>, keyof Store_CSFExports>>;
116
```
117
118
[Portable Stories](./portable-stories.md)
119
120
### Vue App Setup and Configuration
121
122
Configure Vue application plugins and initialization functions for Storybook stories, enabling proper Vue 3 app context and plugin integration.
123
124
```typescript { .api }
125
function setup(fn: (app: App, storyContext?: StoryContext<VueRenderer>) => unknown): void;
126
```
127
128
[App Setup](./app-setup.md)
129
130
### Component Testing with Playwright
131
132
Integration with Playwright for component testing, providing utilities to create test functions for Vue components within Storybook environment.
133
134
```typescript { .api }
135
function createTest(options?: any): any;
136
```
137
138
Available from the experimental Playwright submodule:
139
140
```typescript
141
import { createTest } from "@storybook/vue3/experimental-playwright";
142
```
143
144
[Component Testing](./component-testing.md)
145
146
## Core Types
147
148
```typescript { .api }
149
import type { WebRenderer, Canvas } from 'storybook/internal/types';
150
import type { ConcreteComponent, Component } from 'vue';
151
152
interface VueRenderer extends WebRenderer {
153
component: Omit<ConcreteComponent<any>, 'props'>;
154
storyResult: StoryFnVueReturnType;
155
mount: (
156
Component?: StoryFnVueReturnType,
157
options?: { props?: Record<string, any>; slots?: Record<string, any> }
158
) => Promise<Canvas>;
159
}
160
161
type Args = Record<string, any>;
162
type ArgTypes = Record<string, any>;
163
type Parameters = Record<string, any>;
164
type StrictArgs = Record<string, unknown>;
165
type StoryFnVueReturnType = ConcreteComponent<any>;
166
167
interface StoryContext<TArgs = StrictArgs> extends GenericStoryContext<VueRenderer, TArgs> {
168
component: Component;
169
}
170
171
type Decorator<TArgs = StrictArgs> = DecoratorFunction<VueRenderer, TArgs>;
172
173
type Loader<TArgs = StrictArgs> = LoaderFunction<VueRenderer, TArgs>;
174
175
type Preview = ProjectAnnotations<VueRenderer>;
176
```