0
# Environment System
1

2
Target environment configuration, engine requirements, and feature detection for different runtime contexts and optimization settings.
3

4
## Capabilities
5

6
### Environment Interface
7

8
Complete environment configuration with context detection and feature support.
9

10
```typescript { .api }
11
/**
12
 * Build environment interface defining target runtime context
13
 */
14
interface Environment {
15
  /** Unique environment identifier */
16
  readonly id: string;
17
  /** Runtime context (browser, node, worker, etc.) */
18
  readonly context: EnvironmentContext;
19
  /** Engine version requirements */
20
  readonly engines: Engines;
21
  /** Node modules inclusion strategy */
22
  readonly includeNodeModules: 
23
    | boolean 
24
    | Array<PackageName> 
25
    | {[PackageName]: boolean};
26
  /** Output module format */
27
  readonly outputFormat: OutputFormat;
28
  /** Source type (script or module) */
29
  readonly sourceType: SourceType;
30
  /** Whether this is a library build */
31
  readonly isLibrary: boolean;
32
  /** Whether output should be optimized */
33
  readonly shouldOptimize: boolean;
34
  /** Whether scope hoisting is enabled */
35
  readonly shouldScopeHoist: boolean;
36
  /** Source map configuration */
37
  readonly sourceMap: ?TargetSourceMapOptions;
38
  /** Location that created this environment */
39
  readonly loc: ?SourceLocation;
40
  
41
  /** Check if context is browser-based */
42
  isBrowser(): boolean;
43
  /** Check if context is Node.js-based */
44
  isNode(): boolean;
45
  /** Check if context is server-side */
46
  isServer(): boolean;
47
  /** Check if context is Electron-based */
48
  isElectron(): boolean;
49
  /** Check if context is a worker */
50
  isWorker(): boolean;
51
  /** Check if context is a worklet */
52
  isWorklet(): boolean;
53
  /** Check if context is isolated (can't access parent bundles) */
54
  isIsolated(): boolean;
55
  /** Check if engines meet minimum version requirements */
56
  matchesEngines(minVersions: VersionMap, defaultValue?: boolean): boolean;
57
  /** Check if environment supports a specific feature */
58
  supports(feature: EnvironmentFeature, defaultValue?: boolean): boolean;
59
}
60
```
61

62
### Environment Context
63

64
Runtime context types for different execution environments.
65

66
```typescript { .api }
67
/**
68
 * Runtime context types
69
 */
70
type EnvironmentContext =
71
  | 'browser'           // Web browser main thread
72
  | 'web-worker'        // Web Worker
73
  | 'service-worker'    // Service Worker
74
  | 'worklet'           // Worklet (Audio, CSS, etc.)
75
  | 'node'              // Node.js runtime
76
  | 'electron-main'     // Electron main process
77
  | 'electron-renderer' // Electron renderer process
78
  | 'react-client'      // React client-side rendering
79
  | 'react-server';     // React server-side rendering
80
```
81

82
### Output Format
83

84
Module format for bundle output.
85

86
```typescript { .api }
87
/**
88
 * JavaScript module format for bundle output
89
 */
90
type OutputFormat = 
91
  | 'esmodule'    // ES modules (import/export)
92
  | 'commonjs'    // CommonJS (require/module.exports)
93
  | 'global';     // Global variable assignment
94
```
95

96
### Source Type
97

98
Source code interpretation mode.
99

100
```typescript { .api }
101
/**
102
 * Source code type for parsing and execution
103
 */
104
type SourceType = 
105
  | 'script'    // Script mode (no import/export)
106
  | 'module';   // Module mode (import/export allowed)
107
```
108

109
### Environment Options
110

111
Options for creating environment instances.
112

113
```typescript { .api }
114
/**
115
 * Options for creating an Environment instance
116
 */
117
interface EnvironmentOptions {
118
  /** Runtime context */
119
  context?: EnvironmentContext;
120
  /** Engine version requirements */
121
  engines?: Engines;
122
  /** Node modules inclusion strategy */
123
  includeNodeModules?: 
124
    | boolean 
125
    | Array<PackageName> 
126
    | {[PackageName]: boolean};
127
  /** Output module format */
128
  outputFormat?: OutputFormat;
129
  /** Source type */
130
  sourceType?: SourceType;
131
  /** Whether this is a library build */
132
  isLibrary?: boolean;
133
  /** Whether to optimize output */
134
  shouldOptimize?: boolean;
135
  /** Whether to enable scope hoisting */
136
  shouldScopeHoist?: boolean;
137
  /** Source map configuration */
138
  sourceMap?: ?TargetSourceMapOptions;
139
  /** Location information */
140
  loc?: ?SourceLocation;
141
}
142
```
143

144
### Engine Requirements
145

146
Browser and runtime version requirements.
147

148
```typescript { .api }
149
/**
150
 * Engine version requirements for different runtimes
151
 */
152
interface Engines {
153
  /** Browser version requirements (browserslist format) */
154
  browsers?: string | Array<string>;
155
  /** Electron version requirement */
156
  electron?: SemverRange;
157
  /** Node.js version requirement */
158
  node?: SemverRange;
159
  /** Parcel version requirement */
160
  parcel?: SemverRange;
161
}
162

163
/**
164
 * Resolved browser versions
165
 * Example: { chrome: '91', firefox: '89', safari: '14.1' }
166
 */
167
interface VersionMap {
168
  [browserName: string]: string;
169
}
170
```
171

172
### Environment Features
173

174
Feature detection for environment capabilities.
175

176
```typescript { .api }
177
/**
178
 * Environment feature capabilities
179
 */
180
type EnvironmentFeature =
181
  | 'esmodules'           // ES module support
182
  | 'dynamic-import'      // Dynamic import() support
183
  | 'worker-module'       // Worker modules support
184
  | 'service-worker-module' // Service worker modules
185
  | 'import-meta-url'     // import.meta.url support
186
  | 'import-meta-resolve' // import.meta.resolve support
187
  | 'arrow-functions'     // Arrow function support
188
  | 'global-this';        // globalThis support
189
```
190

191
### Target Interface
192

193
Build target combining environment with output configuration.
194

195
```typescript { .api }
196
/**
197
 * Build target representing output configuration
198
 */
199
interface Target {
200
  /** Output entry file name */
201
  readonly distEntry: ?FilePath;
202
  /** Output directory */
203
  readonly distDir: FilePath;
204
  /** Target environment */
205
  readonly env: Environment;
206
  /** Target name */
207
  readonly name: string;
208
  /** Public URL for assets */
209
  readonly publicUrl: string;
210
  /** Location that created this target */
211
  readonly loc: ?SourceLocation;
212
}
213
```
214

215
**Usage Examples:**
216

217
```typescript
218
import type { 
219
  Environment, 
220
  EnvironmentOptions, 
221
  EnvironmentContext, 
222
  OutputFormat 
223
} from '@parcel/types';
224

225
// Create environment for different contexts
226
const browserEnv: EnvironmentOptions = {
227
  context: 'browser',
228
  outputFormat: 'esmodule',
229
  engines: {
230
    browsers: ['> 1%', 'last 2 versions']
231
  },
232
  shouldOptimize: true,
233
  shouldScopeHoist: true
234
};
235

236
const nodeEnv: EnvironmentOptions = {
237
  context: 'node',
238
  outputFormat: 'commonjs',
239
  engines: {
240
    node: '>= 14'
241
  },
242
  includeNodeModules: false,
243
  isLibrary: true
244
};
245

246
const workerEnv: EnvironmentOptions = {
247
  context: 'web-worker',
248
  outputFormat: 'esmodule',
249
  engines: {
250
    browsers: ['Chrome >= 80', 'Firefox >= 72']
251
  },
252
  sourceType: 'module'
253
};
254

255
// Check environment capabilities
256
function checkEnvironmentCapabilities(env: Environment) {
257
  if (env.isBrowser()) {
258
    console.log('Browser environment detected');
259
    
260
    if (env.supports('esmodules')) {
261
      console.log('ES modules supported');
262
    }
263
    
264
    if (env.supports('dynamic-import')) {
265
      console.log('Dynamic imports supported');
266
    }
267
  }
268
  
269
  if (env.isNode()) {
270
    console.log('Node.js environment detected');
271
    
272
    if (env.matchesEngines({ node: '16' })) {
273
      console.log('Node.js 16+ detected');
274
    }
275
  }
276
  
277
  if (env.isWorker()) {
278
    console.log('Worker environment detected');
279
    
280
    if (env.supports('worker-module')) {
281
      console.log('Worker modules supported');
282
    }
283
  }
284
}
285

286
// Environment-specific optimization
287
function optimizeForEnvironment(env: Environment) {
288
  if (env.shouldOptimize) {
289
    if (env.isBrowser()) {
290
      // Browser optimizations
291
      if (env.shouldScopeHoist) {
292
        console.log('Enabling scope hoisting for browser');
293
      }
294
      
295
      if (env.supports('esmodules')) {
296
        console.log('Using ES modules for modern browsers');
297
      }
298
    }
299
    
300
    if (env.isNode()) {
301
      // Node.js optimizations
302
      console.log('Optimizing for Node.js runtime');
303
      
304
      if (env.outputFormat === 'commonjs') {
305
        console.log('Using CommonJS format');
306
      }
307
    }
308
  }
309
}
310

311
// Engine version checking
312
function checkEngineSupport(env: Environment) {
313
  const modernBrowsers = {
314
    chrome: '80',
315
    firefox: '72',
316
    safari: '13'
317
  };
318
  
319
  if (env.matchesEngines(modernBrowsers)) {
320
    console.log('Modern browser features available');
321
    return true;
322
  }
323
  
324
  console.log('Legacy browser support needed');
325
  return false;
326
}
327

328
// Context-specific feature detection
329
function getContextCapabilities(context: EnvironmentContext) {
330
  switch (context) {
331
    case 'browser':
332
      return ['esmodules', 'dynamic-import', 'import-meta-url'];
333
    
334
    case 'web-worker':
335
      return ['esmodules', 'worker-module', 'import-meta-url'];
336
    
337
    case 'service-worker':
338
      return ['esmodules', 'service-worker-module'];
339
    
340
    case 'node':
341
      return ['esmodules', 'dynamic-import', 'global-this'];
342
    
343
    case 'electron-renderer':
344
      return ['esmodules', 'dynamic-import', 'import-meta-url'];
345
    
346
    default:
347
      return [];
348
  }
349
}
350
```