0
# Component Documentation
1

2
Advanced component metadata extraction system supporting both modern and legacy documentation generation approaches for Vue 3 components.
3

4
## Capabilities
5

6
### Documentation Plugin Types
7

8
Available documentation generation plugins with different capabilities and use cases.
9

10
```typescript { .api }
11
/** Available docgen plugins for Vue components */
12
type VueDocgenPlugin = 'vue-docgen-api' | 'vue-component-meta';
13
```
14

15
### Documentation Info Types
16

17
Type definitions for component documentation information based on the chosen plugin.
18

19
```typescript { .api }
20
/**
21
 * Type of __docgenInfo depending on the used docgenPlugin
22
 */
23
type VueDocgenInfo<T extends VueDocgenPlugin> = T extends 'vue-component-meta'
24
  ? ComponentMeta
25
  : ComponentDoc;
26

27
/**
28
 * Single prop/event/slot/exposed entry of __docgenInfo depending on the used docgenPlugin
29
 * 
30
 * @example
31
 * type PropInfo = VueDocgenInfoEntry<'vue-component-meta', 'props'>;
32
 */
33
type VueDocgenInfoEntry<
34
  T extends VueDocgenPlugin,
35
  TKey extends 'props' | 'events' | 'slots' | 'exposed' | 'expose' = 
36
    | 'props' | 'events' | 'slots' | 'exposed' | 'expose'
37
> = ArrayElement<
38
  T extends 'vue-component-meta'
39
    ? VueDocgenInfo<'vue-component-meta'>[Exclude<TKey, 'expose'>]
40
    : VueDocgenInfo<'vue-docgen-api'>[Exclude<TKey, 'exposed'>]
41
>;
42
```
43

44
### Array Element Utility Type
45

46
Helper type for extracting single array element types.
47

48
```typescript { .api }
49
/** Gets the type of a single array element */
50
type ArrayElement<T> = T extends readonly (infer A)[] ? A : never;
51
```
52

53
## Documentation Plugins
54

55
### Vue Component Meta (Recommended)
56

57
Modern documentation plugin using Volar's vue-component-meta for advanced TypeScript support.
58

59
**Features:**
60
- **Advanced Type Support**: Handles complex TypeScript types and interfaces
61
- **Better Type Documentation**: Extracts detailed type information and JSDoc comments
62
- **JSX/TSX Support**: Works with JavaScript and TypeScript component files
63
- **Performance**: Optimized for large codebases
64
- **Future Default**: Will become the default plugin in future versions
65

66
**Configuration:**
67
```typescript
68
docgen: "vue-component-meta"
69
// OR with custom tsconfig
70
docgen: {
71
  plugin: "vue-component-meta",
72
  tsconfig: "tsconfig.app.json"
73
}
74
```
75

76
### Vue Docgen API (Legacy)
77

78
Legacy documentation plugin using vue-docgen-api for basic component documentation.
79

80
**Features:**
81
- **Vue File Support**: Processes `.vue` single-file components
82
- **Basic Metadata**: Extracts props, events, slots, and methods
83
- **Stable**: Well-established with consistent behavior
84
- **Current Default**: Default plugin in current version
85

86
**Configuration:**
87
```typescript
88
docgen: "vue-docgen-api"
89
// OR explicitly
90
docgen: {
91
  plugin: "vue-docgen-api"
92
}
93
```
94

95
## Component Metadata Structure
96

97
### Vue Component Meta Format
98

99
When using `vue-component-meta`, components receive detailed metadata:
100

101
```typescript
102
interface ComponentMeta {
103
  props: PropMeta[];
104
  events: EventMeta[];
105
  slots: SlotMeta[];
106
  exposed: ExposedMeta[];
107
  type: TypeMeta;
108
}
109

110
interface PropMeta {
111
  name: string;
112
  description?: string;
113
  type: string;
114
  schema: PropertyMetaSchema;
115
  required: boolean;
116
  default?: any;
117
}
118

119
interface EventMeta {
120
  name: string;
121
  description?: string;
122
  type: string;
123
  schema: PropertyMetaSchema | PropertyMetaSchema[];
124
}
125

126
interface MetaSource {
127
  exportName: string;
128
  displayName: string;
129
  sourceFiles: string;
130
  props: PropMeta[];
131
  events: EventMeta[];
132
  slots: SlotMeta[];
133
  exposed: ExposedMeta[];
134
}
135
```
136

137
### Vue Docgen API Format
138

139
When using `vue-docgen-api`, components receive basic documentation:
140

141
```typescript
142
interface ComponentDoc {
143
  displayName: string;
144
  description?: string;
145
  props?: PropDoc[];
146
  events?: EventDoc[];
147
  slots?: SlotDoc[];
148
  methods?: MethodDoc[];
149
}
150

151
interface PropDoc {
152
  name: string;
153
  type?: Type;
154
  description?: string;
155
  required?: boolean;
156
  defaultValue?: any;
157
}
158
```
159

160
## Usage Examples
161

162
### Accessing Component Documentation
163

164
Components processed by the documentation plugins receive a `__docgenInfo` property:
165

166
```typescript
167
// In your component
168
export default defineComponent({
169
  name: 'MyComponent',
170
  props: {
171
    title: String,
172
    count: Number,
173
  },
174
  emits: ['update', 'change'],
175
});
176

177
// After processing, the component will have:
178
MyComponent.__docgenInfo = {
179
  props: [
180
    { name: 'title', type: 'string', required: false },
181
    { name: 'count', type: 'number', required: false },
182
  ],
183
  events: [
184
    { name: 'update', type: 'void' },
185
    { name: 'change', type: 'void' },
186
  ],
187
  // ... other metadata
188
};
189
```
190

191
### TypeScript Configuration for vue-component-meta
192

193
When using TypeScript configurations with references:
194

195
```typescript
196
// .storybook/main.ts
197
import type { StorybookConfig } from "@storybook/vue3-vite";
198

199
const config: StorybookConfig = {
200
  framework: {
201
    name: "@storybook/vue3-vite",
202
    options: {
203
      docgen: {
204
        plugin: "vue-component-meta",
205
        tsconfig: "tsconfig.app.json", // References your app-specific config
206
      },
207
    },
208
  },
209
};
210
```
211

212
### Performance Optimization
213

214
For improved build performance, documentation generation can be disabled:
215

216
```typescript
217
// .storybook/main.ts
218
const config: StorybookConfig = {
219
  framework: {
220
    name: "@storybook/vue3-vite",
221
    options: {
222
      docgen: false, // Disables all documentation generation
223
    },
224
  },
225
};
226
```
227

228
### Migration from vue-docgen-api to vue-component-meta
229

230
To migrate to the modern plugin:
231

232
```typescript
233
// Before (vue-docgen-api)
234
docgen: "vue-docgen-api"
235

236
// After (vue-component-meta)
237
docgen: "vue-component-meta"
238

239
// Or with custom tsconfig
240
docgen: {
241
  plugin: "vue-component-meta",
242
  tsconfig: "tsconfig.app.json"
243
}
244
```
245

246
**Benefits of Migration:**
247
- Better TypeScript support
248
- More accurate type extraction
249
- Support for JSX/TSX components
250
- Improved performance
251
- Future-proof (will become default)
252

253
## Advanced Features
254

255
### Schema Optimization
256

257
The vue-component-meta plugin includes automatic schema optimization to prevent memory issues:
258

259
```typescript { .api }
260
/**
261
 * Removes nested schemas from component metadata to prevent memory issues
262
 * @param schema - Property metadata schema to optimize
263
 */
264
function removeNestedSchemas(schema: PropertyMetaSchema): void;
265
```
266

267
**Optimization Features:**
268
- **Memory Management**: Removes nested object schemas that can cause out-of-memory errors
269
- **Bundle Size Reduction**: Reduces build output size by eliminating complex schemas
270
- **Enum Preservation**: Maintains enum schemas while optimizing their nested structures
271
- **Control Generation**: Preserves essential schema information for Storybook controls
272

273
### File Filtering
274

275
Component analysis is filtered to include only relevant files:
276

277
```typescript
278
// Included files
279
const include = /\.(vue|ts|js|tsx|jsx)$/;
280

281
// Excluded patterns
282
const exclude = /\.stories\.(ts|tsx|js|jsx)$|^\0\/virtual:|^\/virtual:|\.storybook\/.*\.(ts|js)$/;
283
```
284

285
**Filter Logic:**
286
- **Include**: Vue SFC, TypeScript, JavaScript, and JSX files
287
- **Exclude**: Story files, virtual modules, and Storybook internal files
288
- **Performance**: Reduces processing overhead by focusing on component files only