zone.js

A monkey-patching library that wraps every async API in the browser (and Node) with a "zone" — a context object that knows when async work starts and finishes. Angular has historically used Zones to know when to run change detection. With zoneless mode now first-class, zone.js remains shipped from this repo for backward compatibility.

Purpose

• Wrap timers, promises, event listeners, XHR/fetch, MutationObserver, requestAnimationFrame, and many other async APIs.
• Provide an NgZone that emits onMicrotaskEmpty when all in-flight async work completes — Angular schedules a tick on this signal.
• Allow apps to opt into zoneless mode (provideZonelessChangeDetection) instead of running with Zone-based scheduling.

Directory layout

packages/zone.js/
├── lib/
│   ├── browser/        # Browser monkey-patches
│   ├── common/         # Shared patches
│   ├── node/           # Node-specific patches
│   ├── jasmine/        # Jasmine test integration
│   ├── mocha/          # Mocha test integration
│   ├── jest/           # Jest integration
│   ├── rxjs/           # RxJS scheduler integration
│   └── zone-spec/      # ZoneSpec helpers (TaskTrackingZone, etc.)
├── test/
└── README.md

Key abstractions

Concept	Where	What it is
Zone (global)	packages/zone.js/lib/zone.ts	The root API; exposes current, fork, wrap, run.
Patches	lib/browser/, lib/common/, lib/node/	Monkey-patch each async API to be zone-aware.
ZoneSpec	lib/zone-spec/	Hooks for entering/leaving zones, scheduling tasks, handling errors.
Test integrations	lib/jasmine/, lib/mocha/, lib/jest/	Wait for zone-tracked async tasks before completing tests.

Integration points

• @angular/core — NgZone wraps a Zone instance. The legacy change-detection scheduler subscribes to onMicrotaskEmpty. In zoneless mode the same NgZone shape is provided by a no-op implementation.
• Test harnesses — zone.js/testing integrates with Jasmine/Mocha/Jest so async work tracked by zones is awaited before a test completes.
• RxJS scheduler integration — patches asap/async schedulers so they create zone-tracked tasks.

Status

The package is now considered legacy by the Angular team. Zoneless is the recommended mode for new apps, and the testing patterns documented in AGENTS.md explicitly avoid zone-based assumptions. zone.js continues to be supported because removing it would be a major break for the existing app ecosystem.

Entry points for modification

• New async API to patch: add a patch under packages/zone.js/lib/common/ or the platform-specific folder. Tests in packages/zone.js/test/ cover the new behavior.
• New ZoneSpec use case: model after the existing helpers in packages/zone.js/lib/zone-spec/.

pnpm zonejs:release builds the package for npm release; it has its own publishing path independent of the rest of @angular/*.