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
```