diff --git a/adev/src/content/guide/zoneless.md b/adev/src/content/guide/zoneless.md index 94308667953b15..7802b902d47b20 100644 --- a/adev/src/content/guide/zoneless.md +++ b/adev/src/content/guide/zoneless.md @@ -7,7 +7,7 @@ The main advantages to removing ZoneJS as a dependency are: - **Improved performance**: ZoneJS uses DOM events and async tasks as indicators of when application state _might_ have updated and subsequently triggers application synchronization to run change detection on the application's views. ZoneJS does not have any insight into whether application state actually changed and so this synchronization is triggered more frequently than necessary. - **Improved Core Web Vitals**: ZoneJS brings a fair amount of overhead, both in payload size and in startup time cost. - **Improved debugging experience**: ZoneJS makes debugging code more difficult. Stack traces are harder to understand with ZoneJS. It's also difficult to understand when code breaks as a result of being outside the Angular Zone. -- **Better ecosystem compatibility**: (new browser APIs, native async await, patching can conflict with libraries and other frameworks, maintainability, etc) +- **Better ecosystem compatibility**: ZoneJS works by patching browser APIs but does not automatically have patches for every new browser API. In addition, some APIs simply cannot be patched effecitvely, such as `async`/`await` and has to be downleveled to work with ZoneJS. Sometimes libraries in the ecosystem are also incompatible with the way ZoneJS patches the native APIs. Removing ZoneJS as a dependency ensures better long-term compatibility by removing a source of complexity, monkey patching, and ongoing maintenance. ## Enabling Zoneless in an application @@ -83,9 +83,11 @@ familiar and have similar timing to what was needed. More straightforward or dir such as `MutationObserver` when code needs to wait for certain DOM state (rather than waiting for it indirectly through Angular's render hooks). + `NgZone.run` and `NgZone.runOutsideAngular` do not need to be removed in order for code to be compatible with Zoneless applications. In fact, removing these calls can lead to performance regressions for libraries that are used in applications that still rely on ZoneJS. + ### `ExperimentalPendingTasks` for Server Side Rendering (SSR)