0
# Build Configuration
1

2
Core types for configuring Parcel builds, including entry points, targets, caching, development server options, and environment variables.
3

4
## Capabilities
5

6
### Initial Parcel Options
7

8
Main configuration interface for initializing Parcel builds with all available options.
9

10
```typescript { .api }
11
/**
12
 * Main configuration interface for initializing Parcel builds
13
 */
14
interface InitialParcelOptions {
15
  /** Entry points for the build */
16
  entries?: FilePath | Array<FilePath>;
17
  /** Path to custom Parcel configuration file */
18
  config?: DependencySpecifier;
19
  /** Default configuration package to extend */
20
  defaultConfig?: DependencySpecifier;
21
  /** Build targets configuration */
22
  targets?: Array<string> | {[string]: TargetDescriptor};
23
  /** Build mode - affects optimization and development features */
24
  mode?: BuildMode;
25
  /** Environment variables to inject */
26
  env?: EnvMap;
27
  /** Whether to disable build caching */
28
  shouldDisableCache?: boolean;
29
  /** Custom cache directory location */
30
  cacheDir?: FilePath;
31
  /** Watch directory for file changes */
32
  watchDir?: FilePath;
33
  /** File watcher backend type */
34
  watchBackend?: BackendType;
35
  /** Files and patterns to ignore when watching */
36
  watchIgnore?: Array<FilePath | GlobPattern>;
37
  /** Whether to include content hash in bundle names */
38
  shouldContentHash?: boolean;
39
  /** Development server configuration */
40
  serveOptions?: InitialServerOptions | false;
41
  /** Whether to auto-install missing dependencies */
42
  shouldAutoInstall?: boolean;
43
  /** Logging level configuration */
44
  logLevel?: LogLevel;
45
  /** Whether to profile build performance */
46
  shouldProfile?: boolean;
47
  /** Whether to trace build operations */
48
  shouldTrace?: boolean;
49
  /** Whether to patch console output */
50
  shouldPatchConsole?: boolean;
51
  /** Whether to build lazily (only changed files) */
52
  shouldBuildLazily?: boolean;
53
  /** Patterns to include in lazy builds */
54
  lazyIncludes?: Array<string>;
55
  /** Patterns to exclude from lazy builds */
56
  lazyExcludes?: Array<string>;
57
  /** Whether to enable incremental bundling */
58
  shouldBundleIncrementally?: boolean;
59
  /** File invalidation events for unstable features */
60
  unstableFileInvalidations?: Array<Event>;
61
  /** Custom input file system */
62
  inputFS?: FileSystem;
63
  /** Custom output file system */
64
  outputFS?: FileSystem;
65
  /** Custom cache implementation */
66
  cache?: Cache;
67
  /** Worker farm for parallel processing */
68
  workerFarm?: WorkerFarm;
69
  /** Custom package manager */
70
  packageManager?: PackageManager;
71
  /** Detailed reporting options */
72
  detailedReport?: DetailedReportOptions;
73
  /** Default target options for all targets */
74
  defaultTargetOptions?: {
75
    shouldOptimize?: boolean;
76
    shouldScopeHoist?: boolean;
77
    sourceMaps?: boolean;
78
    publicUrl?: string;
79
    distDir?: FilePath;
80
    engines?: Engines;
81
    outputFormat?: OutputFormat;
82
    isLibrary?: boolean;
83
  };
84
  /** Additional reporter plugins */
85
  additionalReporters?: Array<{
86
    packageName: DependencySpecifier;
87
    resolveFrom: FilePath;
88
  }>;
89
  /** Hot module replacement options for development */
90
  hmrOptions?: HMROptions;
91
  /** Feature flags configuration */
92
  featureFlags?: Partial<FeatureFlags>;
93
}
94
```
95

96
### Build Mode
97

98
Build mode configuration affecting optimization and development features.
99

100
```typescript { .api }
101
/**
102
 * Build mode configuration
103
 * - 'development': Faster builds with debugging features
104
 * - 'production': Optimized builds for deployment
105
 * - Custom string: User-defined mode
106
 */
107
type BuildMode = 'development' | 'production' | string;
108
```
109

110
### Target Configuration
111

112
Build target configuration for different output environments and formats.
113

114
```typescript { .api }
115
/**
116
 * Build target configuration for JS API usage
117
 */
118
interface TargetDescriptor {
119
  /** Target runtime context */
120
  context?: EnvironmentContext;
121
  /** Engine version requirements */
122
  engines?: Engines;
123
  /** Node modules inclusion strategy */
124
  includeNodeModules?: boolean | Array<PackageName> | {[PackageName]: boolean};
125
  /** Output module format */
126
  outputFormat?: OutputFormat;
127
  /** Public URL for assets */
128
  publicUrl?: string;
129
  /** Output directory (required) */
130
  distDir: FilePath;
131
  /** Output entry file name */
132
  distEntry?: FilePath;
133
  /** Source map configuration */
134
  sourceMap?: boolean | TargetSourceMapOptions;
135
  /** Whether this is a library build */
136
  isLibrary?: boolean;
137
  /** Whether to optimize the output */
138
  optimize?: boolean;
139
  /** Whether to enable scope hoisting */
140
  scopeHoist?: boolean;
141
  /** Input source files */
142
  source?: FilePath | Array<FilePath>;
143
}
144

145
/**
146
 * Package.json target configuration format
147
 */
148
interface PackageTargetDescriptor {
149
  context?: EnvironmentContext;
150
  engines?: Engines;
151
  includeNodeModules?: boolean | Array<PackageName> | {[PackageName]: boolean};
152
  outputFormat?: OutputFormat;
153
  publicUrl?: string;
154
  distDir?: FilePath;
155
  sourceMap?: boolean | TargetSourceMapOptions;
156
  isLibrary?: boolean;
157
  optimize?: boolean;
158
  scopeHoist?: boolean;
159
  source?: FilePath | Array<FilePath>;
160
}
161
```
162

163
### Engine Requirements
164

165
Browser and Node.js version requirements for build targets.
166

167
```typescript { .api }
168
/**
169
 * Engine version requirements
170
 */
171
interface Engines {
172
  /** Browser version requirements (browserslist format) */
173
  browsers?: string | Array<string>;
174
  /** Electron version requirement */
175
  electron?: SemverRange;
176
  /** Node.js version requirement */
177
  node?: SemverRange;
178
  /** Parcel version requirement */
179
  parcel?: SemverRange;
180
}
181

182
/**
183
 * Resolved browser version map
184
 * Example: { chrome: '91', firefox: '89', safari: '14' }
185
 */
186
interface VersionMap {
187
  [browserName: string]: string;
188
}
189
```
190

191
### Source Map Configuration
192

193
Source map generation and output configuration.
194

195
```typescript { .api }
196
/**
197
 * Source map configuration options
198
 */
199
interface TargetSourceMapOptions {
200
  /** Source root path for source map */
201
  sourceRoot?: string;
202
  /** Whether to inline source map in output */
203
  inline?: boolean;
204
  /** Whether to include source content in source map */
205
  inlineSources?: boolean;
206
}
207
```
208

209
### Development Server Options
210

211
Configuration for Parcel's development server.
212

213
```typescript { .api }
214
/**
215
 * Development server initialization options
216
 */
217
interface InitialServerOptions {
218
  /** Server port number */
219
  port?: number;
220
  /** Server host address */
221
  host?: string;
222
  /** HTTPS configuration */
223
  https?: HTTPSOptions | boolean;
224
}
225

226
/**
227
 * Runtime server options
228
 */
229
interface ServerOptions {
230
  port: number;
231
  host: string;
232
  https?: HTTPSOptions;
233
}
234

235
/**
236
 * HTTPS configuration for development server
237
 */
238
interface HTTPSOptions {
239
  /** Path to SSL certificate file */
240
  cert?: FilePath;
241
  /** Path to SSL private key file */
242
  key?: FilePath;
243
}
244
```
245

246
### Hot Module Replacement
247

248
Hot module replacement configuration for development builds.
249

250
```typescript { .api }
251
/**
252
 * Hot module replacement configuration
253
 */
254
interface HMROptions {
255
  /** HMR server port */
256
  port?: number;
257
  /** HMR server host */
258
  host?: string;
259
}
260
```
261

262
### Logging Configuration
263

264
Build process logging and reporting configuration.
265

266
```typescript { .api }
267
/**
268
 * Logging level configuration
269
 */
270
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'verbose';
271

272
/**
273
 * Detailed reporting options
274
 */
275
interface DetailedReportOptions {
276
  /** Number of assets to show per bundle in detailed reports */
277
  assetsPerBundle?: number;
278
}
279

280
/**
281
 * File watcher backend types
282
 */
283
type BackendType = 'fs-events' | 'watchman' | 'brute-force';
284

285
/**
286
 * Glob pattern for file matching
287
 */
288
type GlobPattern = string;
289

290
/**
291
 * File system event from @parcel/watcher
292
 */
293
interface Event {
294
  /** Event type */
295
  type: 'create' | 'update' | 'delete';
296
  /** File path affected */
297
  path: string;
298
}
299
```
300

301
**Usage Examples:**
302

303
```typescript
304
import type { InitialParcelOptions } from '@parcel/types';
305

306
// Basic production build configuration
307
const prodConfig: InitialParcelOptions = {
308
  entries: ['src/index.html'],
309
  mode: 'production',
310
  targets: {
311
    main: {
312
      distDir: 'dist',
313
      optimize: true,
314
      sourceMap: false
315
    }
316
  }
317
};
318

319
// Development configuration with HMR
320
const devConfig: InitialParcelOptions = {
321
  entries: ['src/index.html'],
322
  mode: 'development',
323
  hmrOptions: {
324
    port: 3000
325
  },
326
  serveOptions: {
327
    port: 1234,
328
    host: 'localhost'
329
  },
330
  targets: {
331
    main: {
332
      distDir: 'dev-dist',
333
      sourceMap: true
334
    }
335
  }
336
};
337

338
// Library build configuration
339
const libConfig: InitialParcelOptions = {
340
  entries: ['src/lib.ts'],
341
  targets: {
342
    main: {
343
      distDir: 'lib',
344
      isLibrary: true,
345
      outputFormat: 'esmodule',
346
      engines: {
347
        node: '>= 14'
348
      }
349
    }
350
  }
351
};
352
```