Modules

Starting from zone.js v0.8.9, you can choose which web API modules you want to patch as to reduce overhead introduced by the patching of these modules. For example, the below samples show how to disable some modules. You just need to define a few global variables before loading zone.js.

<script>
  __Zone_disable_Error = true; // Zone will not patch Error
  __Zone_disable_on_property = true; // Zone will not patch `on` properties such as button.onclick
  __Zone_disable_geolocation = true; // Zone will not patch geolocation API
  __Zone_disable_toString = true; // Zone will not patch Function.prototype.toString
  __Zone_disable_blocking = true; // Zone will not patch alert/prompt/confirm
  __Zone_disable_PromiseRejectionEvent = true; // Zone will not patch PromiseRejectionEventHandler
</script>
<script src="../bundles/zone.umd.js"></script>

Below is the full list of currently supported modules.

Common

Browser

Node.js

Test Framework

on properties

You can also disable specific on properties by setting __Zone_ignore_on_properties as follows. For example, if you want to disable window.onmessage and HTMLElement.prototype.onclick from zone.js patching, you can do so like this:

<script>
  __Zone_ignore_on_properties = [
    {
      target: window,
      ignoreProperties: ['message'],
    },
    {
      target: HTMLElement.prototype,
      ignoreProperties: ['click'],
    },
  ];
</script>
<script src="../bundles/zone.umd.js"></script>

Excluding on properties from being patched means that callbacks will always be invoked within the root context, regardless of where the on callback has been set. Even if onclick is set within a child zone, the callback will be called inside the root zone:

Zone.current.fork({name: 'child'}).run(() => {
  document.body.onclick = () => {
    console.log(Zone.current); // <root>
  };
});

You can find more information on adding unpatched events via addEventListener, please refer to UnpatchedEvents.

Error

By default, zone.js/plugins/zone-error will not be loaded for performance reasons. This package provides the following functionality:

1. Error Inheritance: Handle the extend Error issue:

   tsCopy

   class MyError extends Error {}
   const myError = new MyError();
   console.log('is MyError instanceof Error', myError instanceof Error);
   

   Without the zone-error patch, the example above will output false. With the patch, the result will be true.

2. ZoneJsInternalStackFrames: Remove the zone.js stack from stackTrace and add zone information. Without this patch, many zone.js invocation stacks will be displayed in the stack frames.

   Copy

     at zone.run (polyfill.bundle.js: 3424)
     at zoneDelegate.invokeTask (polyfill.bundle.js: 3424)
     at zoneDelegate.runTask (polyfill.bundle.js: 3424)
     at zone.drainMicroTaskQueue (polyfill.bundle.js: 3424)
     at a.b.c (vendor.bundle.js: 12345 <angular>)
     at d.e.f (main.bundle.js: 23456)
   

   With this patch, those zone frames will be removed, and the zone information <angular>/<root> will be added.

   Copy

     at a.b.c (vendor.bundle.js: 12345 <angular>)
     at d.e.f (main.bundle.js: 23456 <root>)
   

The second feature may slow down Error performance, so zone.js provides a flag that allows you to control this behavior. The flag is __Zone_Error_ZoneJsInternalStackFrames_policy. The available options are:

1. default: This is the default setting. If you load zone.js/plugins/zone-error without setting the flag, default will be used. In this case, ZoneJsInternalStackFrames will be available when using new Error(), allowing you to obtain an error.stack that is zone-stack-free. However, this may slightly slow down the performance of new Error().

2. disable: This option will disable the ZoneJsInternalStackFrames feature. If you load zone.js/plugins/zone-error, you will only receive a wrapped Error, which can handle the Error inheritance issue.

3. lazy: This feature allows you to access ZoneJsInternalStackFrames without impacting performance. However, as a trade-off, you won't be able to obtain the zone-free stack frames via error.stack. You can only access them through error.zoneAwareStack.

Angular

Angular uses zone.js to manage asynchronous operations and determine when to perform change detection. Therefore, in Angular, the following APIs should be patched; otherwise, Angular may not work as expected:

1. ZoneAwarePromise
2. timer
3. on_property
4. EventTarget
5. XHR