0
# Build Configuration
1

2
Configuration system for the Stencil compiler including output targets, dev server, build optimization, and project setup. Stencil provides extensive configuration options for different build scenarios.
3

4
## Capabilities
5

6
### Main Configuration
7

8
The primary configuration interface for Stencil projects.
9

10
```typescript { .api }
11
/**
12
 * Main Stencil configuration interface
13
 */
14
interface Config extends StencilConfig {
15
  buildAppCore?: boolean;
16
  buildDocs?: boolean;
17
  configPath?: string;
18
  writeLog?: boolean;
19
  devServer?: DevServerConfig;
20
  flags?: ConfigFlags;
21
  fsNamespace?: string;
22
  logLevel?: LogLevel;
23
  rootDir?: string;
24
  packageJsonFilePath?: string;
25
  suppressLogs?: boolean;
26
  profile?: boolean;
27
  tsCompilerOptions?: any;
28
  tsWatchOptions?: any;
29
  _isValidated?: boolean;
30
  _isTesting?: boolean;
31
}
32

33
interface StencilConfig {
34
  /** By default, Stencil will statically analyze the application and generate component bundles */
35
  bundles?: ConfigBundle[];
36
  /** Stencil will cache build results to speed up rebuilds */
37
  enableCache?: boolean;
38
  /** The directory where sub-directories will be created for caching */
39
  cacheDir?: string;
40
  /** Global CSS file for styles across all components */
41
  globalStyle?: string;
42
  /** Generate export map entry points for each component */
43
  generateExportMaps?: boolean;
44
  /** Hash file names for production builds */
45
  hashFileNames?: boolean;
46
  /** Length of hashed file names */
47
  hashedFileNameLength?: number;
48
  /** Namespace for the app */
49
  namespace?: string;
50
  /** Output targets configuration */
51
  outputTargets?: OutputTarget[];
52
  /** Rollup plugins configuration */
53
  plugins?: any[];
54
  /** Generate source maps */
55
  sourceMap?: boolean;
56
  /** Source directory containing TypeScript files */
57
  srcDir?: string;
58
  /** Transform aliased import paths from tsconfig.json */
59
  transformAliasedImportPaths?: boolean;
60
  /** Validate primary package output target */
61
  validatePrimaryPackageOutputTarget?: boolean;
62
  /** Rollup commonjs configuration */
63
  commonjs?: BundlingConfig;
64
  /** Node resolve configuration */
65
  nodeResolve?: NodeResolveConfig;
66
  /** Rollup configuration overrides */
67
  rollupConfig?: RollupConfig;
68
  /** Build ES5 version */
69
  buildEs5?: boolean | 'prod';
70
  /** Minify JavaScript output */
71
  minifyJs?: boolean;
72
  /** Minify CSS output */
73
  minifyCss?: boolean;
74
  /** Force development mode */
75
  devMode?: boolean;
76
  /** Custom logger instance */
77
  logger?: Logger;
78
  /** Runtime extras configuration */
79
  extras?: ConfigExtras;
80
  /** Hydrated flag configuration */
81
  hydratedFlag?: HydratedFlag | null;
82
  /** Task queue strategy */
83
  taskQueue?: 'async' | 'immediate' | 'congestionAsync';
84
  /** Environment variables */
85
  env?: { [prop: string]: string | undefined };
86
  /** Documentation configuration */
87
  docs?: StencilDocsConfig;
88
  /** Global script file */
89
  globalScript?: string;
90
  /** Source index.html file */
91
  srcIndexHtml?: string;
92
  /** Testing configuration */
93
  testing?: TestingConfig;
94
  /** Max concurrent workers */
95
  maxConcurrentWorkers?: number;
96
  /** Build preamble text */
97
  preamble?: string;
98
  /** Additional rollup plugins */
99
  rollupPlugins?: { before?: any[]; after?: any[] };
100
  /** Entry component hints for optimization */
101
  entryComponentsHint?: string[];
102
  /** Whether to write dist files */
103
  buildDist?: boolean;
104
  /** Build log file path */
105
  buildLogFilePath?: string;
106
  /** Enable dev inspector */
107
  devInspector?: boolean;
108
  /** Dev server configuration */
109
  devServer?: StencilDevServerConfig;
110
  /** Compiler system */
111
  sys?: CompilerSystem;
112
  /** TypeScript config file path */
113
  tsconfig?: string;
114
  /** Validate TypeScript types */
115
  validateTypes?: boolean;
116
  /** Watch for file changes */
117
  watch?: boolean;
118
  /** External directories to watch */
119
  watchExternalDirs?: string[];
120
  /** Regex patterns to ignore in watch mode */
121
  watchIgnoredRegex?: RegExp | RegExp[];
122
  /** Exclude unused dependencies from build */
123
  excludeUnusedDependencies?: boolean;
124
}
125
```
126

127
### Output Targets
128

129
Configuration for different build output formats and destinations.
130

131
```typescript { .api }
132
/**
133
 * Union type of all available output target types
134
 */
135
type OutputTarget =
136
  | OutputTargetDist
137
  | OutputTargetDistCustomElements
138
  | OutputTargetDistCollection
139
  | OutputTargetWww
140
  | OutputTargetCustom
141
  | OutputTargetDocsJson
142
  | OutputTargetDocsReadme
143
  | OutputTargetDocsVscode
144
  | OutputTargetHydrate
145
  | OutputTargetStats
146
  | OutputTargetCopy;
147

148
/**
149
 * Distribution output target for npm publishing
150
 */
151
interface OutputTargetDist {
152
  type: 'dist';
153
  /** Build directory for compiled files */
154
  buildDir?: string;
155
  /** Collection directory for component metadata */
156
  collectionDir?: string | null;
157
  /** Transform aliased imports in collection bundle */
158
  transformAliasedImportPathsInCollection?: boolean | null;
159
  /** Types directory for TypeScript definitions */
160
  typesDir?: string;
161
  /** ESM loader directory path */
162
  esmLoaderPath?: string;
163
  /** Files to copy to build directory */
164
  copy?: CopyTask[];
165
  /** Include polyfills in build */
166
  polyfills?: boolean;
167
  /** Empty build directory before build */
168
  empty?: boolean;
169
}
170

171
/**
172
 * Custom elements output target for framework integration
173
 */
174
interface OutputTargetDistCustomElements {
175
  type: 'dist-custom-elements';
176
  /** Empty build directory before build */
177
  empty?: boolean;
178
  /** Treat @stencil/core modules as external */
179
  externalRuntime?: boolean;
180
  /** Files to copy to build directory */
181
  copy?: CopyTask[];
182
  /** Include global scripts in components */
183
  includeGlobalScripts?: boolean;
184
  /** Minify output files */
185
  minify?: boolean;
186
  /** Generate TypeScript declaration files */
187
  generateTypeDeclarations?: boolean;
188
  /** Export/definition behavior for custom elements */
189
  customElementsExportBehavior?: CustomElementsExportBehavior;
190
}
191

192
type CustomElementsExportBehavior = 
193
  | 'default'
194
  | 'auto-define-custom-elements'
195
  | 'bundle'
196
  | 'single-export-module';
197

198
/**
199
 * Web app output target for static sites
200
 */
201
interface OutputTargetWww {
202
  type: 'www';
203
  /** Build directory for JS/CSS files */
204
  buildDir?: string;
205
  /** Directory for entire application */
206
  dir?: string;
207
  /** Empty directory before build */
208
  empty?: boolean;
209
  /** Index HTML file path */
210
  indexHtml?: string;
211
  /** Files to copy to build directory */
212
  copy?: CopyTask[];
213
  /** Base URL of the app */
214
  baseUrl?: string;
215
  /** Include polyfills in build */
216
  polyfills?: boolean;
217
  /** Prerender configuration file */
218
  prerenderConfig?: string;
219
  /** Service worker configuration */
220
  serviceWorker?: ServiceWorkerConfig | null | false;
221
}
222

223
/**
224
 * Custom output target for build integrations
225
 */
226
interface OutputTargetCustom {
227
  type: 'custom';
228
  /** Name of the custom output target */
229
  name: string;
230
  /** When the output target should run */
231
  taskShouldRun?: 'onBuildOnly' | 'always';
232
  /** Validation function for configuration */
233
  validate?: (config: Config, diagnostics: Diagnostic[]) => void;
234
  /** Generator function for build output */
235
  generator: (config: Config, compilerCtx: CompilerCtx, buildCtx: BuildCtx, docs: JsonDocs) => Promise<void>;
236
  /** Files to copy to build directory */
237
  copy?: CopyTask[];
238
}
239
```
240

241
**Usage Examples:**
242

243
```typescript
244
import { Config } from '@stencil/core';
245

246
export const config: Config = {
247
  namespace: 'MyApp',
248
  outputTargets: [
249
    {
250
      type: 'dist',
251
      esmLoaderPath: '../loader',
252
    },
253
    {
254
      type: 'dist-custom-elements',
255
      customElementsExportBehavior: 'auto-define-custom-elements',
256
      generateTypeDeclarations: true,
257
    },
258
    {
259
      type: 'www',
260
      serviceWorker: null,
261
      copy: [
262
        { src: 'assets', dest: 'build/assets' }
263
      ]
264
    }
265
  ],
266
  globalStyle: 'src/global/app.css',
267
  buildEs5: 'prod'
268
};
269
```
270

271
### Copy Tasks
272

273
Configuration for copying files and directories during build.
274

275
```typescript { .api }
276
/**
277
 * File and directory copy operation configuration
278
 */
279
interface CopyTask {
280
  /** Source file path (absolute, relative, or glob pattern) */
281
  src: string;
282
  /** Optional destination path */
283
  dest?: string;
284
  /** Glob patterns to exclude from copy */
285
  ignore?: string[];
286
  /** Issue warnings if source files not found */
287
  warn?: boolean;
288
  /** Preserve directory structure when copying */
289
  keepDirStructure?: boolean;
290
}
291
```
292

293
**Usage Examples:**
294

295
```typescript
296
const copyTasks: CopyTask[] = [
297
  // Copy entire assets directory
298
  { src: 'assets' },
299
  // Copy with custom destination
300
  { src: 'src/docs', dest: 'documentation' },
301
  // Copy with exclusions
302
  { 
303
    src: 'static/**/*',
304
    ignore: ['**/*.tmp', '**/node_modules/**']
305
  },
306
  // Copy single file with preserved structure
307
  {
308
    src: 'config/app.json',
309
    dest: 'build/config',
310
    keepDirStructure: true
311
  }
312
];
313
```
314

315
### Build Extras
316

317
Runtime extras configuration for additional DOM features and polyfills.
318

319
```typescript { .api }
320
/**
321
 * Configuration for additional runtime features
322
 */
323
interface ConfigExtras {
324
  /** Enable import injection for better bundler compatibility */
325
  enableImportInjection?: boolean;
326
  /** Dispatch component lifecycle events for testing */
327
  lifecycleDOMEvents?: boolean;
328
  /** Support script data-opts property */
329
  scriptDataOpts?: boolean;
330
  /** Initialize components on next tick (Angular compatibility) */
331
  initializeNextTick?: boolean;
332
  /** Enable tagName transform option */
333
  tagNameTransform?: boolean;
334
  /** Experimental scoped slot changes */
335
  experimentalScopedSlotChanges?: boolean;
336
  /** Add global styles to each component */
337
  addGlobalStyleToComponents?: boolean;
338
  /** Fix appendChild to work with slot polyfill */
339
  appendChildSlotFix?: boolean;
340
  /** Fix cloneNode to work with slot polyfill */
341
  cloneNodeFix?: boolean;
342
  /** Fix textContent behavior in scoped components */
343
  scopedSlotTextContentFix?: boolean;
344
  /** Fix childNodes and children getters for slot polyfill */
345
  slotChildNodesFix?: boolean;
346
  /** Enable all slot-related fixes */
347
  experimentalSlotFixes?: boolean;
348
}
349
```
350

351
### Hydration Configuration
352

353
Configuration for component hydration behavior and styling.
354

355
```typescript { .api }
356
/**
357
 * Configuration for hydrated component flag
358
 */
359
interface HydratedFlag {
360
  /** CSS class or attribute name */
361
  name?: string;
362
  /** Use 'class' or 'attribute' selector */
363
  selector?: 'class' | 'attribute';
364
  /** CSS property to control visibility */
365
  property?: string;
366
  /** Initial CSS value before hydration */
367
  initialValue?: string;
368
  /** CSS value after hydration completes */
369
  hydratedValue?: string;
370
}
371
```
372

373
**Usage Example:**
374

375
```typescript
376
const config: Config = {
377
  // Use opacity instead of visibility
378
  hydratedFlag: {
379
    name: 'hydrated',
380
    selector: 'class',
381
    property: 'opacity',
382
    initialValue: '0',
383
    hydratedValue: '1'
384
  }
385
};
386
```
387

388
### Documentation Configuration
389

390
Configuration for generating component documentation.
391

392
```typescript { .api }
393
/**
394
 * Documentation generation configuration
395
 */
396
interface StencilDocsConfig {
397
  /** Markdown processing options */
398
  markdown?: {
399
    /** Target component styling for diagrams */
400
    targetComponent?: {
401
      /** Background color for component nodes */
402
      background?: string;
403
      /** Text color for component nodes */
404
      textColor?: string;
405
    };
406
  };
407
}
408

409
/**
410
 * README documentation output target
411
 */
412
interface OutputTargetDocsReadme {
413
  type: 'docs-readme';
414
  /** Root directory for README files */
415
  dir?: string;
416
  /** Include component dependencies */
417
  dependencies?: boolean;
418
  /** How to handle existing README files */
419
  overwriteExisting?: boolean | 'if-missing';
420
  /** Footer text for generated READMEs */
421
  footer?: string;
422
  /** Strict mode for documentation validation */
423
  strict?: boolean;
424
}
425

426
/**
427
 * JSON documentation output target
428
 */
429
interface OutputTargetDocsJson {
430
  type: 'docs-json';
431
  /** Output file path for JSON documentation */
432
  file: string;
433
  /** TypeScript definitions file for docs types */
434
  typesFile?: string | null;
435
  /** Strict mode for documentation validation */
436
  strict?: boolean;
437
  /** Additional public types file to include */
438
  supplementalPublicTypes?: string;
439
}
440

441
/**
442
 * VS Code custom data output target
443
 */
444
interface OutputTargetDocsVscode {
445
  type: 'docs-vscode';
446
  /** Output file path for VS Code data */
447
  file: string;
448
  /** Base URL for component source code */
449
  sourceCodeBaseUrl?: string;
450
}
451
```
452

453
### Rollup Configuration
454

455
Configuration for customizing Rollup bundling behavior.
456

457
```typescript { .api }
458
/**
459
 * Rollup configuration overrides
460
 */
461
interface RollupConfig {
462
  /** Input options for Rollup */
463
  inputOptions?: RollupInputOptions;
464
  /** Output options for Rollup */
465
  outputOptions?: RollupOutputOptions;
466
}
467

468
interface RollupInputOptions {
469
  /** Context for module evaluation */
470
  context?: string;
471
  /** Module context configuration */
472
  moduleContext?: ((id: string) => string) | { [id: string]: string };
473
  /** Tree shaking configuration */
474
  treeshake?: boolean;
475
  /** Max parallel file operations */
476
  maxParallelFileOps?: number;
477
  /** External dependencies configuration */
478
  external?: 
479
    | (string | RegExp)[]
480
    | string
481
    | RegExp
482
    | ((source: string, importer: string | undefined, isResolved: boolean) => boolean | null | undefined);
483
}
484

485
interface RollupOutputOptions {
486
  /** Global variable names for external dependencies */
487
  globals?: { [name: string]: string } | ((name: string) => string);
488
}
489

490
/**
491
 * Node resolve plugin configuration
492
 */
493
interface NodeResolveConfig {
494
  /** Export conditions to match */
495
  exportConditions?: string[];
496
  /** Use browser field in package.json */
497
  browser?: boolean;
498
  /** Directories to search for modules */
499
  moduleDirectories?: string[];
500
  /** Additional module paths */
501
  modulePaths?: string[];
502
  /** Dedupe module instances */
503
  dedupe?: string[] | ((importee: string) => boolean);
504
  /** File extensions to resolve */
505
  extensions?: readonly string[];
506
  /** Jail resolution to specific directory */
507
  jail?: string;
508
  /** Package.json fields to check */
509
  mainFields?: readonly string[];
510
  /** Only resolve modules (no files) */
511
  modulesOnly?: boolean;
512
  /** Prefer built-in Node.js modules */
513
  preferBuiltins?: boolean | ((module: string) => boolean);
514
  /** Only resolve specific modules */
515
  resolveOnly?: ReadonlyArray<string | RegExp> | null | ((module: string) => boolean);
516
  /** Root directory for resolution */
517
  rootDir?: string;
518
  /** Allow exports folder mapping */
519
  allowExportsFolderMapping?: boolean;
520
}
521
```
522

523
**Usage Example:**
524

525
```typescript
526
const config: Config = {
527
  rollupConfig: {
528
    inputOptions: {
529
      external: ['lodash', 'moment'],
530
      treeshake: {
531
        moduleSideEffects: false
532
      }
533
    },
534
    outputOptions: {
535
      globals: {
536
        'lodash': '_',
537
        'moment': 'moment'
538
      }
539
    }
540
  },
541
  nodeResolve: {
542
    browser: true,
543
    preferBuiltins: false,
544
    mainFields: ['browser', 'module', 'main']
545
  }
546
};
547
```