0
# Builder Operations
1

2
Core build functionality for development and production modes, providing webpack compilation with generator-based interruption support, progress reporting, and Express middleware integration.
3

4
## Capabilities
5

6
### Start Function
7

8
Starts a development server with hot module replacement and webpack dev middleware.
9

10
```typescript { .api }
11
/**
12
 * Starts development server with hot reloading and webpack dev middleware
13
 * @param options - Builder start options including router and Storybook options
14
 * @returns Promise resolving to build result with bail function and stats
15
 */
16
function start(options: BuilderStartOptions): Promise<BuilderStartResult>;
17

18
interface BuilderStartOptions {
19
  /** High-resolution time for performance tracking */
20
  startTime?: ReturnType<typeof process.hrtime>;
21
  /** Storybook configuration options */
22
  options: Options;
23
  /** Express router for middleware mounting */
24
  router: any;
25
}
26

27
interface BuilderStartResult {
28
  /** Function to stop the build process and clean up resources */
29
  bail: () => Promise<void>;
30
  /** Webpack compilation statistics */
31
  stats: Stats;
32
  /** Total build time measurement */
33
  totalTime: ReturnType<typeof process.hrtime>;
34
}
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { start } from "@storybook/builder-webpack4";
41
import express from "express";
42

43
const app = express();
44
const router = express.Router();
45

46
const startResult = await start({
47
  startTime: process.hrtime(),
48
  options: {
49
    configType: 'DEVELOPMENT',
50
    outputDir: './storybook-static',
51
    configDir: '.storybook',
52
    presets: presetManager,
53
    framework: 'react',
54
    // ... other options
55
  },
56
  router,
57
});
58

59
// Mount the router with webpack middleware
60
app.use(router);
61

62
// Later, stop the build process
63
await startResult.bail();
64
```
65

66
### Build Function
67

68
Builds production version with webpack compilation and optimization.
69

70
```typescript { .api }
71
/**
72
 * Builds production version with webpack compilation and optimization
73
 * @param options - Builder build options with Storybook configuration
74
 * @returns Promise resolving to webpack Stats object
75
 */
76
function build(options: BuilderBuildOptions): Promise<BuilderBuildResult>;
77

78
interface BuilderBuildOptions {
79
  /** High-resolution time for performance tracking */
80
  startTime?: ReturnType<typeof process.hrtime>;
81
  /** Storybook configuration options */
82
  options: Options;
83
}
84

85
interface BuilderBuildResult extends Stats {
86
  /** Webpack compilation statistics including errors and warnings */
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import { build } from "@storybook/builder-webpack4";
94

95
const buildResult = await build({
96
  startTime: process.hrtime(),
97
  options: {
98
    configType: 'PRODUCTION',
99
    outputDir: './storybook-static',
100
    configDir: '.storybook',
101
    presets: presetManager,
102
    framework: 'react',
103
    quiet: false,
104
    // ... other options
105
  },
106
});
107

108
if (buildResult.hasErrors()) {
109
  console.error('Build failed with errors:', buildResult.toJson().errors);
110
} else {
111
  console.log('Build completed successfully');
112
}
113
```
114

115
### Bail Function
116

117
Stops the build process and cleans up resources including webpack compilation and middleware.
118

119
```typescript { .api }
120
/**
121
 * Stops build process and cleans up resources
122
 * Forces termination of webpack compilation and dev middleware
123
 * @returns Promise that resolves when cleanup is complete
124
 */
125
function bail(): Promise<void>;
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
import { bail } from "@storybook/builder-webpack4";
132

133
// Stop any running build process
134
await bail();
135
console.log('Build process stopped and resources cleaned up');
136
```
137

138
### Executor System
139

140
Webpack instance executor providing access to webpack compiler with version checking.
141

142
```typescript { .api }
143
/**
144
 * Executor for obtaining webpack instance with version validation
145
 */
146
const executor: {
147
  /**
148
   * Gets webpack instance from presets or uses default webpack 4
149
   * @param options - Storybook options with presets
150
   * @returns Promise resolving to webpack instance
151
   */
152
  get(options: Options): Promise<typeof webpack>;
153
};
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { executor } from "@storybook/builder-webpack4";
160

161
const webpackInstance = await executor.get(storybookOptions);
162
const compiler = webpackInstance(webpackConfig);
163
```
164

165
### Utility Functions
166

167
Additional utility functions for error handling and stats generation.
168

169
```typescript { .api }
170
/**
171
 * Creates webpack Stats object from error string for consistent error handling
172
 * @param err - Error message string
173
 * @returns Stats object with error information
174
 */
175
function makeStatsFromError(err: string): Stats;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { makeStatsFromError } from "@storybook/builder-webpack4";
182

183
const errorStats = makeStatsFromError('Webpack compilation failed');
184
console.log(errorStats.toJson().errors); // ['Webpack compilation failed']
185
```
186

187
## Error Handling
188

189
The builder functions implement comprehensive error handling:
190

191
- **Compilation Errors**: Webpack compilation errors are captured and returned in Stats objects
192
- **Process Interruption**: Generator-based functions can be interrupted via the bail mechanism
193
- **Resource Cleanup**: The bail function ensures proper cleanup of webpack dev middleware and compilation processes
194
- **Debug Mode**: When `debugWebpack` option is enabled, full webpack stats are available for debugging