0
# Configuration API
1

2
Global configuration system for selectively disabling patches and customizing zone behavior across different environments and use cases.
3

4
## Capabilities
5

6
### Global Configuration Interface
7

8
Zone.js provides extensive configuration options to disable specific patches and customize behavior.
9

10
```typescript { .api }
11
/**
12
 * Global configuration interface for Zone.js behavior
13
 */
14
interface ZoneGlobalConfigurations {
15
  // Core API patches
16
  /** Disable timer patches (setTimeout, setInterval) */
17
  __Zone_disable_timers?: boolean;
18
  
19
  /** Disable Promise patches */
20
  __Zone_disable_Promise?: boolean;
21
  
22
  /** Disable EventTarget patches */
23
  __Zone_disable_EventTarget?: boolean;
24
  
25
  /** Disable requestAnimationFrame patches */
26
  __Zone_disable_requestAnimationFrame?: boolean;
27
  
28
  /** Disable MutationObserver patches */
29
  __Zone_disable_MutationObserver?: boolean;
30
  
31
  /** Disable IntersectionObserver patches */
32
  __Zone_disable_IntersectionObserver?: boolean;
33
  
34
  /** Disable FileReader patches */
35
  __Zone_disable_FileReader?: boolean;
36
  
37
  /** Disable queueMicrotask patches */
38
  __Zone_disable_queueMicrotask?: boolean;
39
  
40
  /** Disable XMLHttpRequest patches */
41
  __Zone_disable_XHR?: boolean;
42
  
43
  /** Disable Fetch API patches */
44
  __Zone_disable_fetch?: boolean;
45
  
46
  /** Disable WebSocket patches */
47
  __Zone_disable_WebSocket?: boolean;
48
  
49
  /** Disable MessagePort patches */
50
  __Zone_disable_MessagePort?: boolean;
51
  
52
  // Browser-specific patches
53
  /** Disable canvas patches */
54
  __Zone_disable_canvas?: boolean;
55
  
56
  /** Disable Notification API patches */
57
  __Zone_disable_notification?: boolean;
58
  
59
  /** Disable ResizeObserver patches */
60
  __Zone_disable_ResizeObserver?: boolean;
61
  
62
  /** Disable WebRTC patches */
63
  __Zone_disable_RTCPeerConnection?: boolean;
64
  
65
  /** Disable getUserMedia patches */
66
  __Zone_disable_getUserMedia?: boolean;
67
  
68
  /** Disable custom elements patches */
69
  __Zone_disable_customElements?: boolean;
70
  
71
  // Node.js specific patches
72
  /** Disable Node.js fs patches */
73
  __Zone_disable_fs?: boolean;
74
  
75
  /** Disable EventEmitter patches */
76
  __Zone_disable_EventEmitter?: boolean;
77
  
78
  /** Disable crypto patches */
79
  __Zone_disable_crypto?: boolean;
80
  
81
  /** Disable process.nextTick patches */
82
  __Zone_disable_nextTick?: boolean;
83
  
84
  // Event configuration
85
  /** Events to skip patching entirely */
86
  __zone_symbol__UNPATCHED_EVENTS?: string[];
87
  
88
  /** Events to mark as passive */
89
  __zone_symbol__PASSIVE_EVENTS?: string[];
90
  
91
  /** Events to capture in the capturing phase */
92
  __zone_symbol__CAPTURING_EVENTS?: string[];
93
  
94
  // Advanced configuration
95
  /** Properties to ignore when patching objects */
96
  __Zone_ignore_on_properties?: Array<{
97
    target: any;
98
    ignoreProperties: string[];
99
  }>;
100
  
101
  /** Disable wrapping of uncaught promise rejections */
102
  __zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION?: boolean;
103
  
104
  /** Enable or disable zone symbol event names */
105
  __zone_symbol__ENABLE_ZONE_SYMBOL_EVENT_NAMES?: boolean;
106
  
107
  /** Block all events rather than patching */
108
  __zone_symbol__BLOCK_ALL_EVENTS?: boolean;
109
}
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
// Configure before importing zone.js
116
(window as any).__Zone_disable_timers = true;
117
(window as any).__Zone_disable_Promise = true;
118
(window as any).__zone_symbol__UNPATCHED_EVENTS = ['click', 'mouseover'];
119

120
import 'zone.js'; // Zone.js will respect the configuration
121

122
// Alternatively, configure via global object
123
declare global {
124
  interface Window {
125
    __Zone_disable_timers: boolean;
126
    __Zone_disable_EventTarget: boolean;
127
    __zone_symbol__UNPATCHED_EVENTS: string[];
128
  }
129
}
130

131
window.__Zone_disable_timers = true;
132
window.__Zone_disable_EventTarget = true;
133
window.__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'resize'];
134
```
135

136
### Test Configuration Interface
137

138
Specific configuration options for testing environments.
139

140
```typescript { .api }
141
/**
142
 * Test-specific configuration interface
143
 */
144
interface ZoneTestConfigurations {
145
  /** Disable Jasmine integration */
146
  __Zone_disable_jasmine?: boolean;
147
  
148
  /** Disable Mocha integration */
149
  __Zone_disable_mocha?: boolean;
150
  
151
  /** Disable Jest integration */
152
  __Zone_disable_jest?: boolean;
153
  
154
  /** Disable fakeAsync clock patching */
155
  __zone_symbol__fakeAsyncDisablePatchingClock?: boolean;
156
  
157
  /** Support waiting for unresolved chained promises */
158
  __zone_symbol__supportWaitUnResolvedChainedPromise?: boolean;
159
  
160
  /** Auto configure fakeAsync test environment */
161
  __zone_symbol__fakeAsyncAutoFakeAsyncWhenClockPatched?: boolean;
162
}
163
```
164

165
**Usage Examples:**
166

167
```typescript
168
// Test configuration
169
(window as any).__Zone_disable_jasmine = true;
170
(window as any).__zone_symbol__fakeAsyncDisablePatchingClock = true;
171

172
import 'zone.js/testing';
173

174
// Custom test setup
175
describe('Custom Tests', () => {
176
  beforeEach(() => {
177
    // Configure test-specific behavior
178
    (window as any).__zone_symbol__supportWaitUnResolvedChainedPromise = true;
179
  });
180
});
181
```
182

183
### Event Configuration
184

185
Detailed configuration for event handling behavior.
186

187
```typescript { .api }
188
/**
189
 * Configure events to skip patching
190
 */
191
__zone_symbol__UNPATCHED_EVENTS?: string[];
192

193
/**
194
 * Configure events as passive
195
 */
196
__zone_symbol__PASSIVE_EVENTS?: string[];
197

198
/**
199
 * Configure events for capturing phase
200
 */
201
__zone_symbol__CAPTURING_EVENTS?: string[];
202

203
/**
204
 * Block all events rather than patching
205
 */
206
__zone_symbol__BLOCK_ALL_EVENTS?: boolean;
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
// Configure event behavior before Zone.js loads
213
(window as any).__zone_symbol__UNPATCHED_EVENTS = [
214
  'scroll',      // Don't patch scroll events
215
  'mousemove',   // Don't patch mousemove events
216
  'resize'       // Don't patch resize events
217
];
218

219
(window as any).__zone_symbol__PASSIVE_EVENTS = [
220
  'touchstart',  // Mark touchstart as passive
221
  'touchmove',   // Mark touchmove as passive
222
  'wheel'        // Mark wheel as passive
223
];
224

225
(window as any).__zone_symbol__CAPTURING_EVENTS = [
226
  'focus',       // Capture focus events
227
  'blur'         // Capture blur events
228
];
229

230
import 'zone.js';
231

232
// Events configured as unpatched won't trigger zone tasks
233
document.addEventListener('scroll', () => {
234
  // This runs outside of zone context
235
  console.log('Unpatched scroll event');
236
});
237

238
// Other events still work with zones
239
document.addEventListener('click', () => {
240
  // This runs in zone context
241
  console.log('Patched click event in:', Zone.current.name);
242
});
243
```
244

245
### Property Patching Configuration
246

247
Configure which object properties should be ignored during patching.
248

249
```typescript { .api }
250
/**
251
 * Ignore specific properties when patching objects
252
 */
253
__Zone_ignore_on_properties?: Array<{
254
  target: any;
255
  ignoreProperties: string[];
256
}>;
257
```
258

259
**Usage Examples:**
260

261
```typescript
262
// Configure property patching before Zone.js loads
263
(window as any).__Zone_ignore_on_properties = [
264
  {
265
    target: HTMLElement.prototype,
266
    ignoreProperties: ['onscroll', 'onresize']
267
  },
268
  {
269
    target: XMLHttpRequest.prototype,
270
    ignoreProperties: ['onprogress']
271
  },
272
  {
273
    target: window,
274
    ignoreProperties: ['onerror', 'onunhandledrejection']
275
  }
276
];
277

278
import 'zone.js';
279

280
// Ignored properties won't be patched
281
const element = document.getElementById('myElement');
282
element.onscroll = () => {
283
  // This runs outside zone context due to configuration
284
  console.log('Ignored onscroll');
285
};
286

287
element.onclick = () => {
288
  // This runs in zone context (not ignored)
289
  console.log('Click in zone:', Zone.current.name);
290
};
291
```
292

293
### Environment-Specific Configuration
294

295
Configure Zone.js behavior for different environments.
296

297
```typescript { .api }
298
// Browser-only configuration
299
interface BrowserConfigurations {
300
  __Zone_disable_customElements?: boolean;
301
  __Zone_disable_canvas?: boolean;
302
  __Zone_disable_WebSocket?: boolean;
303
  __Zone_disable_notification?: boolean;
304
}
305

306
// Node.js-only configuration
307
interface NodeConfigurations {
308
  __Zone_disable_fs?: boolean;
309
  __Zone_disable_EventEmitter?: boolean;
310
  __Zone_disable_crypto?: boolean;
311
  __Zone_disable_nextTick?: boolean;
312
}
313
```
314

315
**Usage Examples:**
316

317
```typescript
318
// Browser environment configuration
319
if (typeof window !== 'undefined') {
320
  (window as any).__Zone_disable_canvas = true;
321
  (window as any).__Zone_disable_WebSocket = true;
322
  (window as any).__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'resize'];
323
}
324

325
// Node.js environment configuration
326
if (typeof global !== 'undefined') {
327
  (global as any).__Zone_disable_fs = true;
328
  (global as any).__Zone_disable_EventEmitter = false;
329
}
330

331
// Mixed environment configuration
332
import 'zone.js/mix';
333
```
334

335
### Performance Optimization Configuration
336

337
Configuration options for optimizing Zone.js performance.
338

339
```typescript { .api }
340
/**
341
 * Performance-related configuration options
342
 */
343
interface PerformanceConfigurations {
344
  /** Disable symbol event names for performance */
345
  __zone_symbol__ENABLE_ZONE_SYMBOL_EVENT_NAMES?: boolean;
346
  
347
  /** Block all events to avoid patching overhead */
348
  __zone_symbol__BLOCK_ALL_EVENTS?: boolean;
349
  
350
  /** Disable wrapping promise rejections */
351
  __zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION?: boolean;
352
}
353
```
354

355
**Usage Examples:**
356

357
```typescript
358
// High-performance configuration
359
(window as any).__zone_symbol__ENABLE_ZONE_SYMBOL_EVENT_NAMES = false;
360
(window as any).__zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION = true;
361

362
// Disable expensive patches
363
(window as any).__Zone_disable_MutationObserver = true;
364
(window as any).__Zone_disable_IntersectionObserver = true;
365
(window as any).__Zone_disable_ResizeObserver = true;
366

367
// Use minimal event patching
368
(window as any).__zone_symbol__UNPATCHED_EVENTS = [
369
  'scroll', 'resize', 'mousemove', 'touchmove'
370
];
371

372
import 'zone.js';
373
```
374

375
### Runtime Configuration
376

377
Some Zone.js behavior can be configured at runtime after loading.
378

379
```typescript { .api }
380
/**
381
 * Runtime configuration methods
382
 */
383
interface RuntimeConfiguration {
384
  /** Check current configuration state */
385
  isPatched(api: string): boolean;
386
  
387
  /** Get configuration value */
388
  getConfig(key: string): any;
389
  
390
  /** Load additional patches at runtime */
391
  loadPatch(name: string, fn: PatchFn): void;
392
}
393
```
394

395
**Usage Examples:**
396

397
```typescript
398
import 'zone.js';
399

400
// Check if specific APIs are patched
401
const isTimerPatched = !!(window as any).__Zone_symbol_setTimeout;
402
const isPromisePatched = !!(window as any).__Zone_symbol_Promise;
403

404
console.log('Timers patched:', isTimerPatched);
405
console.log('Promises patched:', isPromisePatched);
406

407
// Load additional patches at runtime
408
Zone.__load_patch('custom-runtime-patch', (global, Zone, api) => {
409
  console.log('Loading custom patch at runtime');
410
  // Custom patching logic
411
});
412

413
// Conditional patch loading
414
if (typeof window !== 'undefined' && window.customAPI) {
415
  Zone.__load_patch('custom-api', (global, Zone, api) => {
416
    // Patch custom API if available
417
  });
418
}
419
```
420

421
### Configuration Best Practices
422

423
Recommended patterns for configuring Zone.js in different scenarios.
424

425
```typescript { .api }
426
// Minimal configuration for performance-critical applications
427
const minimalConfig = {
428
  __Zone_disable_timers: false,        // Keep timers (usually needed)
429
  __Zone_disable_Promise: false,       // Keep promises (usually needed)
430
  __Zone_disable_EventTarget: false,   // Keep event target (usually needed)
431
  __Zone_disable_XHR: false,           // Keep XHR (usually needed)
432
  __Zone_disable_fetch: false,         // Keep fetch (usually needed)
433
  
434
  // Disable expensive patches
435
  __Zone_disable_MutationObserver: true,
436
  __Zone_disable_IntersectionObserver: true,
437
  __Zone_disable_ResizeObserver: true,
438
  __Zone_disable_canvas: true,
439
  
440
  // Optimize event handling
441
  __zone_symbol__UNPATCHED_EVENTS: [
442
    'scroll', 'resize', 'mousemove', 'touchmove'
443
  ],
444
  __zone_symbol__PASSIVE_EVENTS: [
445
    'touchstart', 'touchmove', 'wheel'
446
  ]
447
};
448

449
// Testing configuration
450
const testConfig = {
451
  __Zone_disable_jasmine: false,
452
  __zone_symbol__fakeAsyncDisablePatchingClock: false,
453
  __zone_symbol__supportWaitUnResolvedChainedPromise: true
454
};
455

456
// Node.js configuration
457
const nodeConfig = {
458
  __Zone_disable_fs: true,           // Often not needed in web apps
459
  __Zone_disable_EventEmitter: false, // Usually needed
460
  __Zone_disable_nextTick: false    // Usually needed
461
};
462
```