0
# Angular CLI Builders
1

2
Angular CLI builders for starting and building Storybook applications integrated with Angular's build system.
3

4
## Capabilities
5

6
### Start Storybook Builder
7

8
Angular CLI builder for starting Storybook in development mode with hot reloading and Angular build integration.
9

10
```typescript { .api }
11
/**
12
 * Angular CLI builder for starting Storybook in development mode
13
 * Builder name: @storybook/angular:start-storybook
14
 */
15
type StorybookStartBuilderOptions = JsonObject & {
16
  /** Angular browser target to use for build configuration */
17
  browserTarget?: string | null;
18
  /** Path to TypeScript configuration file */
19
  tsConfig?: string;
20
  /** Whether to run compodoc for documentation generation */
21
  compodoc: boolean;
22
  /** Arguments to pass to compodoc */
23
  compodocArgs: string[];
24
  /** Enable Angular production mode optimizations */
25
  enableProdMode?: boolean;
26
  /** Additional styles to include */
27
  styles?: StyleElement[];
28
  /** Style preprocessor options */
29
  stylePreprocessorOptions?: StylePreprocessorOptions;
30
  /** Additional assets to include */
31
  assets?: AssetPattern[];
32
  /** Preserve symlinks in module resolution */
33
  preserveSymlinks?: boolean;
34
  /** Enable source maps */
35
  sourceMap?: SourceMapUnion;
36
  /** Enable experimental zoneless change detection */
37
  experimentalZoneless?: boolean;
38
} & Pick<CLIOptions, 
39
  | 'port'
40
  | 'host' 
41
  | 'configDir'
42
  | 'https'
43
  | 'sslCa'
44
  | 'sslCert'
45
  | 'sslKey'
46
  | 'smokeTest'
47
  | 'ci'
48
  | 'quiet'
49
  | 'disableTelemetry'
50
  | 'initialPath'
51
  | 'open'
52
  | 'docs'
53
  | 'debugWebpack'
54
  | 'webpackStatsJson'
55
  | 'statsJson'
56
  | 'loglevel'
57
  | 'previewUrl'
58
>;
59
```
60

61
**Usage in angular.json:**
62

63
```json
64
{
65
  "projects": {
66
    "my-app": {
67
      "architect": {
68
        "storybook": {
69
          "builder": "@storybook/angular:start-storybook",
70
          "options": {
71
            "configDir": ".storybook",
72
            "browserTarget": "my-app:build",
73
            "port": 6006,
74
            "compodoc": true,
75
            "compodocArgs": [
76
              "-e", "json",
77
              "-d", "."
78
            ]
79
          },
80
          "configurations": {
81
            "ci": {
82
              "quiet": true,
83
              "ci": true
84
            }
85
          }
86
        }
87
      }
88
    }
89
  }
90
}
91
```
92

93
**CLI Usage:**
94

95
```bash
96
# Start Storybook with default options
97
ng run my-app:storybook
98

99
# Start with specific configuration
100
ng run my-app:storybook:ci
101

102
# Start with custom port and enable docs
103
ng run my-app:storybook --port=9009 --docs
104

105
# Start with debugging enabled
106
ng run my-app:storybook --debugWebpack
107
```
108

109
### Build Storybook Builder
110

111
Angular CLI builder for building static Storybook output for production deployment.
112

113
```typescript { .api }
114
/**
115
 * Angular CLI builder for building static Storybook for production
116
 * Builder name: @storybook/angular:build-storybook
117
 */
118
type StorybookBuildBuilderOptions = JsonObject & {
119
  /** Angular browser target to use for build configuration */
120
  browserTarget?: string | null;
121
  /** Path to TypeScript configuration file */
122
  tsConfig?: string;
123
  /** Enable test mode for CI environments */
124
  test: boolean;
125
  /** Enable docs generation */
126
  docs: boolean;
127
  /** Whether to run compodoc for documentation generation */
128
  compodoc: boolean;
129
  /** Arguments to pass to compodoc */
130
  compodocArgs: string[];
131
  /** Enable Angular production mode optimizations */
132
  enableProdMode?: boolean;
133
  /** Additional styles to include */
134
  styles?: StyleElement[];
135
  /** Style preprocessor options */
136
  stylePreprocessorOptions?: StylePreprocessorOptions;
137
  /** Preserve symlinks in module resolution */
138
  preserveSymlinks?: boolean;
139
  /** Additional assets to include */
140
  assets?: AssetPattern[];
141
  /** Enable source maps */
142
  sourceMap?: SourceMapUnion;
143
  /** Enable experimental zoneless change detection */
144
  experimentalZoneless?: boolean;
145
} & Pick<CLIOptions,
146
  | 'outputDir'
147
  | 'configDir'
148
  | 'loglevel'
149
  | 'quiet'
150
  | 'test'
151
  | 'webpackStatsJson'
152
  | 'statsJson'
153
  | 'disableTelemetry'
154
  | 'debugWebpack'
155
  | 'previewUrl'
156
>;
157
```
158

159
**Usage in angular.json:**
160

161
```json
162
{
163
  "projects": {
164
    "my-app": {
165
      "architect": {
166
        "build-storybook": {
167
          "builder": "@storybook/angular:build-storybook",
168
          "options": {
169
            "configDir": ".storybook",
170
            "browserTarget": "my-app:build:production",
171
            "outputDir": "dist/storybook",
172
            "compodoc": true,
173
            "compodocArgs": [
174
              "-e", "json",
175
              "-d", ".",
176
              "--silent"
177
            ]
178
          },
179
          "configurations": {
180
            "ci": {
181
              "test": true,
182
              "quiet": true,
183
              "disableTelemetry": true
184
            }
185
          }
186
        }
187
      }
188
    }
189
  }
190
}
191
```
192

193
**CLI Usage:**
194

195
```bash
196
# Build Storybook for production
197
ng run my-app:build-storybook
198

199
# Build with test mode for CI
200
ng run my-app:build-storybook:ci
201

202
# Build to custom output directory
203
ng run my-app:build-storybook --outputDir=dist/my-storybook
204

205
# Build with webpack stats for analysis
206
ng run my-app:build-storybook --webpackStatsJson
207
```
208

209
## Configuration Options
210

211
### Common Options
212

213
Options available for both start and build builders:
214

215
```typescript { .api }
216
interface CommonBuilderOptions {
217
  /** Angular browser target (e.g., "my-app:build" or "my-app:build:production") */
218
  browserTarget?: string | null;
219
  /** Path to TypeScript configuration file */
220
  tsConfig?: string;
221
  /** Whether to run compodoc for documentation generation */
222
  compodoc: boolean;
223
  /** Arguments to pass to compodoc command */
224
  compodocArgs: string[];
225
  /** Enable Angular production mode optimizations */
226
  enableProdMode?: boolean;
227
  /** Additional styles to include in the build */
228
  styles?: StyleElement[];
229
  /** Style preprocessor options (Sass, Less, etc.) */
230
  stylePreprocessorOptions?: StylePreprocessorOptions;
231
  /** Additional assets to copy to the output */
232
  assets?: AssetPattern[];
233
  /** Preserve symlinks during module resolution */
234
  preserveSymlinks?: boolean;
235
  /** Enable source map generation */
236
  sourceMap?: SourceMapUnion;
237
  /** Enable experimental zoneless change detection */
238
  experimentalZoneless?: boolean;
239
}
240
```
241

242
### Browser Target Integration
243

244
The `browserTarget` option allows Storybook to inherit configuration from existing Angular build targets:
245

246
```json
247
{
248
  "build": {
249
    "builder": "@angular-devkit/build-angular:browser",
250
    "options": {
251
      "outputPath": "dist/my-app",
252
      "index": "src/index.html",
253
      "main": "src/main.ts",
254
      "polyfills": "src/polyfills.ts",
255
      "tsConfig": "tsconfig.app.json",
256
      "assets": ["src/favicon.ico", "src/assets"],
257
      "styles": ["src/styles.scss"],
258
      "stylePreprocessorOptions": {
259
        "includePaths": ["src/styles"]
260
      }
261
    }
262
  },
263
  "storybook": {
264
    "builder": "@storybook/angular:start-storybook",
265
    "options": {
266
      "browserTarget": "my-app:build",
267
      // Inherits: tsConfig, assets, styles, stylePreprocessorOptions
268
      "configDir": ".storybook"
269
    }
270
  }
271
}
272
```
273

274
### Compodoc Integration
275

276
Compodoc generates documentation from Angular components for use in Storybook docs:
277

278
```json
279
{
280
  "build-storybook": {
281
    "builder": "@storybook/angular:build-storybook",
282
    "options": {
283
      "compodoc": true,
284
      "compodocArgs": [
285
        "-e", "json",
286
        "-d", ".",
287
        "--tsconfig", "tsconfig.doc.json",
288
        "--silent"
289
      ]
290
    }
291
  }
292
}
293
```
294

295
### Asset and Style Configuration
296

297
Include additional assets and styles specifically for Storybook:
298

299
```json
300
{
301
  "storybook": {
302
    "builder": "@storybook/angular:start-storybook",
303
    "options": {
304
      "assets": [
305
        "src/favicon.ico",
306
        "src/assets",
307
        {
308
          "glob": "**/*",
309
          "input": "src/storybook-assets",
310
          "output": "/storybook-assets"
311
        }
312
      ],
313
      "styles": [
314
        "src/styles.scss",
315
        "src/storybook-specific.scss"
316
      ],
317
      "stylePreprocessorOptions": {
318
        "includePaths": [
319
          "src/styles",
320
          "node_modules"
321
        ]
322
      }
323
    }
324
  }
325
}
326
```
327

328
## Builder Output Types
329

330
### Start Builder Output
331

332
```typescript { .api }
333
type StorybookStartBuilderOutput = JsonObject & BuilderOutput & {
334
  /** Whether the build was successful */
335
  success: boolean;
336
  /** Information about the running server */
337
  info: {
338
    /** Port number where Storybook is running */
339
    port: number;
340
  };
341
};
342
```
343

344
### Build Builder Output
345

346
```typescript { .api }
347
type StorybookBuildBuilderOutput = JsonObject & BuilderOutput & {
348
  /** Whether the build was successful */
349
  success: boolean;
350
  /** Additional build information */
351
  [key: string]: any;
352
};
353
```
354

355
## Environment Variables
356

357
Builders support environment variable configuration:
358

359
```bash
360
# Start builder environment variables
361
export SBCONFIG_PORT=9009
362
export SBCONFIG_HOSTNAME=0.0.0.0
363
export SBCONFIG_STATIC_DIR=./public
364
export SBCONFIG_CONFIG_DIR=./.storybook
365
export CI=true
366

367
# Build builder environment variables
368
export SBCONFIG_OUTPUT_DIR=./storybook-static
369
export SBCONFIG_CONFIG_DIR=./.storybook
370
export SBCONFIG_STATIC_DIR=./public
371
```
372

373
## Advanced Usage Examples
374

375
### Multi-Project Setup
376

377
For Angular workspaces with multiple projects:
378

379
```json
380
{
381
  "projects": {
382
    "shared-components": {
383
      "architect": {
384
        "storybook": {
385
          "builder": "@storybook/angular:start-storybook",
386
          "options": {
387
            "configDir": "projects/shared-components/.storybook",
388
            "browserTarget": "shared-components:build"
389
          }
390
        }
391
      }
392
    },
393
    "admin-app": {
394
      "architect": {
395
        "storybook": {
396
          "builder": "@storybook/angular:start-storybook",
397
          "options": {
398
            "configDir": "projects/admin-app/.storybook",
399
            "browserTarget": "admin-app:build",
400
            "port": 6007
401
          }
402
        }
403
      }
404
    }
405
  }
406
}
407
```
408

409
### CI/CD Integration
410

411
Optimized configuration for continuous integration:
412

413
```json
414
{
415
  "build-storybook": {
416
    "builder": "@storybook/angular:build-storybook",
417
    "configurations": {
418
      "ci": {
419
        "test": true,
420
        "quiet": true,
421
        "disableTelemetry": true,
422
        "enableProdMode": true,
423
        "sourceMap": false,
424
        "compodoc": true,
425
        "compodocArgs": ["--silent"]
426
      }
427
    }
428
  }
429
}
430
```
431

432
### Development vs Production
433

434
Different configurations for development and production builds:
435

436
```json
437
{
438
  "storybook": {
439
    "builder": "@storybook/angular:start-storybook",
440
    "options": {
441
      "browserTarget": "my-app:build",
442
      "enableProdMode": false,
443
      "sourceMap": true
444
    },
445
    "configurations": {
446
      "production": {
447
        "browserTarget": "my-app:build:production",
448
        "enableProdMode": true,
449
        "sourceMap": false
450
      }
451
    }
452
  }
453
}
454
```