0
# Storybook Builder Vite
1

2
Storybook Builder Vite is a modern Storybook builder that integrates with Vite for fast development server startup times and near-instant hot module replacement (HMR) during component development. It serves as a drop-in replacement for webpack-based builders, providing significantly improved performance while maintaining full compatibility with Storybook's ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @storybook/builder-vite
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: Typically installed automatically when using Storybook with Vite framework packages
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  start, 
16
  build, 
17
  bail, 
18
  withoutVitePlugins, 
19
  hasVitePlugins 
20
} from "@storybook/builder-vite";
21
```
22

23
For type imports:
24

25
```typescript
26
import type { 
27
  ViteBuilder, 
28
  ViteFinal, 
29
  StorybookConfigVite, 
30
  BuilderOptions 
31
} from "@storybook/builder-vite";
32
```
33

34
## Basic Usage
35

36
This package is typically not used directly by end users but is configured through Storybook's main configuration:
37

38
```javascript
39
// .storybook/main.js
40
export default {
41
  framework: {
42
    name: '@storybook/react-vite', // or another Vite-based framework
43
    options: {
44
      builder: {
45
        viteConfigPath: '.storybook/customViteConfig.js', // optional
46
      },
47
    },
48
  },
49
  async viteFinal(config, { configType }) {
50
    // Customize Vite config for Storybook
51
    return mergeConfig(config, {
52
      resolve: {
53
        alias: { foo: 'bar' },
54
      },
55
    });
56
  },
57
};
58
```
59

60
## Architecture
61

62
The Storybook Builder Vite integrates Vite's build system into Storybook's framework architecture:
63

64
- **Builder Interface**: Implements Storybook's standardized `Builder` interface with `start`, `build`, and `bail` methods
65
- **Development Server**: Uses Vite's dev server with HMR for fast component development and story updates
66
- **Production Build**: Leverages Vite's optimized build process with Rollup for efficient static asset generation
67
- **Plugin System**: Provides utilities for managing Vite plugins within Storybook's configuration system
68
- **Virtual File System**: Handles Storybook's virtual modules and iframe HTML transformation through Vite's plugin API
69
- **Configuration Management**: Supports custom Vite configurations through `viteFinal` hooks and external config files
70

71
The builder serves as the bridge between Storybook's component development workflow and Vite's modern build tooling, enabling fast startup times and near-instant hot reloading for an improved developer experience.
72

73
## Capabilities
74

75
### Builder Core Functions
76

77
Primary functions that implement the Storybook builder interface for development and production builds.
78

79
```typescript { .api }
80
/**
81
 * Starts the Vite development server for Storybook
82
 * @param args - Configuration object with options, startTime, router, server, and channel
83
 * @returns Promise resolving to development server info with bail function and stats
84
 */
85
const start: (args: {
86
  options: Options;
87
  startTime: ReturnType<typeof process.hrtime>;
88
  router: ServerApp;
89
  server: HttpServer;
90
  channel: ServerChannel;
91
}) => Promise<void | {
92
  stats?: ViteStats;
93
  totalTime: ReturnType<typeof process.hrtime>;
94
  bail: (e?: Error) => Promise<void>;
95
}>;
96

97
/**
98
 * Builds Storybook for production using Vite
99
 * @param arg - Configuration object with options and startTime
100
 * @returns Promise resolving to build statistics
101
 */
102
const build: (arg: {
103
  options: Options;
104
  startTime: ReturnType<typeof process.hrtime>;
105
}) => Promise<void | ViteStats>;
106

107
/**
108
 * Gracefully shuts down the Vite development server
109
 * @param e - Optional error parameter
110
 * @returns Promise that resolves when server is closed
111
 */
112
function bail(e?: Error): Promise<void>;
113
```
114

115
### Plugin Management Utilities
116

117
Utilities for managing Vite plugins in Storybook configurations, allowing developers to programmatically filter and check for specific plugins.
118

119
```typescript { .api }
120
/**
121
 * Recursively removes all plugins with the specified names from a Vite plugins array
122
 * Resolves async plugins and handles nested plugin arrays
123
 * @param plugins - Array of Vite plugins (may include promises and nested arrays), defaults to empty array
124
 * @param namesToRemove - Array of plugin names to remove
125
 * @returns Promise resolving to filtered plugins array
126
 */
127
function withoutVitePlugins<TPlugin>(
128
  plugins?: TPlugin[],
129
  namesToRemove: string[]
130
): Promise<TPlugin[]>;
131

132
/**
133
 * Checks if any plugins in the array have names matching the provided names
134
 * Will resolve any promises in the plugins array and check nested arrays recursively
135
 * @param plugins - Array of Vite plugin options
136
 * @param names - Array of plugin names to check for
137
 * @returns Promise resolving to true if any matching plugins are found
138
 */
139
function hasVitePlugins(
140
  plugins: PluginOption[], 
141
  names: string[]
142
): Promise<boolean>;
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { withoutVitePlugins, hasVitePlugins } from '@storybook/builder-vite';
149
import type { PluginOption } from 'vite';
150

151
// Remove specific plugins from a Vite config
152
const cleanedPlugins = await withoutVitePlugins(
153
  viteConfig.plugins, 
154
  ['rollup-plugin-turbosnap']
155
);
156

157
// Check if certain plugins are present
158
const hasTurbosnap = await hasVitePlugins(
159
  viteConfig.plugins, 
160
  ['rollup-plugin-turbosnap']
161
);
162
```
163

164
### Configuration Management
165

166
Types and interfaces for customizing Vite configuration within Storybook.
167

168
```typescript { .api }
169
/**
170
 * Function type for customizing Vite configuration in Storybook
171
 * Called during Storybook's configuration phase to allow Vite config modifications
172
 * @param config - Current Vite InlineConfig object
173
 * @param options - Storybook options object
174
 * @returns Modified Vite configuration (sync or async)
175
 */
176
type ViteFinal = (
177
  config: InlineConfig,
178
  options: Options
179
) => InlineConfig | Promise<InlineConfig>;
180

181
/**
182
 * Storybook configuration interface with Vite-specific options
183
 * Used in .storybook/main.js configuration files
184
 */
185
interface StorybookConfigVite {
186
  /** Optional function to customize Vite configuration */
187
  viteFinal?: ViteFinal;
188
}
189

190
/**
191
 * Configuration options for the Vite builder
192
 * Used in framework.options.builder configuration
193
 */
194
interface BuilderOptions {
195
  /** Path to vite.config file, relative to process.cwd() */
196
  viteConfigPath?: string;
197
}
198
```
199

200

201
## Types
202

203
Core type definitions for the builder interface and configuration.
204

205
```typescript { .api }
206
/**
207
 * Main builder interface extending Storybook's Builder type with Vite-specific configuration
208
 * Generic parameters: Vite's UserConfig for configuration, ViteStats for build statistics
209
 */
210
type ViteBuilder = Builder<UserConfig, ViteStats>;
211

212
/**
213
 * Vite-specific stats object that replaces Webpack stats in Storybook
214
 * Provides JSON serialization method for build information
215
 */
216
interface ViteStats {
217
  /** Serializes build statistics to JSON format */
218
  toJson(): any;
219
}
220

221
/**
222
 * Storybook options interface from internal types
223
 * Contains configuration options passed to builders
224
 */
225
interface Options {
226
  // Storybook internal options type
227
  [key: string]: any;
228
}
229

230
/**
231
 * Server application interface for routing
232
 * Express-like server interface for middleware registration
233
 */
234
interface ServerApp {
235
  // Express-like server application
236
  [key: string]: any;
237
}
238

239
/**
240
 * HTTP server interface from Node.js
241
 * Standard Node.js HTTP server interface
242
 */
243
interface HttpServer {
244
  // Node.js HTTP server
245
  [key: string]: any;
246
}
247

248
/**
249
 * Server channel interface for Storybook communication
250
 * Used for communication between Storybook manager and preview
251
 */
252
interface ServerChannel {
253
  // Storybook server channel
254
  [key: string]: any;
255
}
256

257
/**
258
 * Vite user configuration interface from Vite
259
 * Standard Vite configuration object
260
 */
261
interface UserConfig {
262
  // Vite user configuration
263
  [key: string]: any;
264
}
265

266
/**
267
 * Vite inline configuration interface from Vite
268
 * Extended Vite configuration for programmatic usage
269
 */
270
interface InlineConfig {
271
  // Vite inline configuration
272
  [key: string]: any;
273
}
274

275
/**
276
 * Vite plugin option type from Vite
277
 * Represents various forms of Vite plugins (objects, functions, promises, arrays)
278
 */
279
type PluginOption = any;
280
```
281

282
## Dependencies
283

284
### Runtime Dependencies
285
- `@storybook/csf-plugin`: Component Story Format plugin support
286
- `ts-dedent`: Template string dedenting utility
287

288
### Peer Dependencies  
289
- `storybook`: Main Storybook framework (required)
290
- `vite`: Vite bundler (^5.0.0 || ^6.0.0 || ^7.0.0)
291

292
## Common Usage Patterns
293

294
### Custom Vite Configuration
295

296
```typescript
297
// .storybook/main.ts
298
import type { StorybookConfig } from '@storybook/react-vite';
299
import { mergeConfig } from 'vite';
300

301
const config: StorybookConfig = {
302
  // ... other config
303
  async viteFinal(config, { configType }) {
304
    return mergeConfig(config, {
305
      define: {
306
        'process.env.NODE_ENV': JSON.stringify(
307
          configType === 'DEVELOPMENT' ? 'development' : 'production'
308
        ),
309
      },
310
      resolve: {
311
        alias: {
312
          '@': path.resolve(__dirname, '../src'),
313
        },
314
      },
315
    });
316
  },
317
};
318

319
export default config;
320
```
321

322
### Plugin Management
323

324
```typescript
325
// Remove problematic plugins in viteFinal
326
import { withoutVitePlugins } from '@storybook/builder-vite';
327

328
export default {
329
  async viteFinal(config) {
330
    // Remove specific plugins that conflict with Storybook
331
    config.plugins = await withoutVitePlugins(config.plugins || [], [
332
      'rollup-plugin-turbosnap'
333
    ]);
334
    return config;
335
  },
336
};
337
```
338

339
### Builder Options Configuration
340

341
```typescript
342
// .storybook/main.js - Custom Vite config path
343
export default {
344
  framework: {
345
    name: '@storybook/react-vite',
346
    options: {
347
      builder: {
348
        viteConfigPath: '.storybook/custom-vite.config.js',
349
      },
350
    },
351
  },
352
};
353
```