diff --git a/adev-es/src/content/guide/zoneless.en.md b/adev-es/src/content/guide/zoneless.en.md new file mode 100644 index 0000000..4eafe65 --- /dev/null +++ b/adev-es/src/content/guide/zoneless.en.md @@ -0,0 +1,165 @@ +# Angular without ZoneJS (Zoneless) + +## Why use Zoneless? + +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**: ZoneJS works by patching browser APIs but does not automatically have patches for every new browser API. Some APIs cannot be patched effectively, such as `async`/`await`, and have 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 + +```typescript +// standalone bootstrap +bootstrapApplication(MyApp, {providers: [ + provideZonelessChangeDetection(), +]}); + +// NgModule bootstrap +platformBrowser().bootstrapModule(AppModule); +@NgModule({ + providers: [provideZonelessChangeDetection()] +}) +export class AppModule {} +``` + +## Removing ZoneJS + +Zoneless applications should remove ZoneJS entirely from the build to reduce bundle size. ZoneJS is typically +loaded via the `polyfills` option in `angular.json`, both in the `build` and `test` targets. Remove `zone.js` +and `zone.js/testing` from both to remove it from the build. Projects which use an explicit `polyfills.ts` file +should remove `import 'zone.js';` and `import 'zone.js/testing';` from the file. + +After removing ZoneJS from the build, there is no longer a need for a `zone.js` dependency either and the +package can be removed entirely: + +```shell +npm uninstall zone.js +``` + +## Requirements for Zoneless compatibility + +Angular relies on notifications from core APIs in order to determine when to run change detection and on which views. +These notifications include: + +- `ChangeDetectorRef.markForCheck` (called automatically by `AsyncPipe`) +- `ComponentRef.setInput` +- Updating a signal that's read in a template +- Bound host or template listeners callbacks +- Attaching a view that was marked dirty by one of the above + +### `OnPush`-compatible components + +One way to ensure that a component is using the correct notification mechanisms from above is to +use [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush). + +The `OnPush` change detection strategy is not required, but it is a recommended step towards zoneless compatibility for application components. It is not always possible for library components to use `ChangeDetectionStrategy.OnPush`. +When a library component is a host for user-components which might use `ChangeDetectionStrategy.Default`, it cannot use `OnPush` because that would prevent the child component from being refreshed if it is not `OnPush` compatible and relies on ZoneJS to trigger change detection. Components can use the `Default` strategy as long as they notify Angular when change detection needs to run (calling `markForCheck`, using signals, `AsyncPipe`, etc.). +Being a host for a user component means using an API such as `ViewContainerRef.createComponent` and not just hosting a portion of a template from a user component (i.e. content projection or a using a template ref input). + +### Remove `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable`, or `NgZone.onStable` + +Applications and libraries need to remove uses of `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` and `NgZone.onStable`. +These observables will never emit when an Application enables zoneless change detection. +Similarly, `NgZone.isStable` will always be `true` and should not be used as a condition for code execution. + +The `NgZone.onMicrotaskEmpty` and `NgZone.onStable` observables are most often used to wait for Angular to +complete change detection before performing a task. Instead, these can be replaced by `afterNextRender` +if they need to wait for a single change detection or `afterEveryRender` if there is some condition that might span +several change detection rounds. In other cases, these observables were used because they happened to be +familiar and have similar timing to what was needed. More straightforward or direct DOM APIs can be used instead, +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. + + +### `PendingTasks` for Server Side Rendering (SSR) + +If you are using SSR with Angular, you may know that it relies on ZoneJS to help determine when the application +is "stable" and can be serialized. If there are asynchronous tasks that should prevent serialization, an application +not using ZoneJS must make Angular aware of these with the [PendingTasks](/api/core/PendingTasks) service. Serialization +will wait for the first moment that all pending tasks have been removed. + +The two most straightforward uses of pending tasks are the `run` method: + +```typescript +const taskService = inject(PendingTasks); +taskService.run(async () => { + const someResult = await doSomeWorkThatNeedsToBeRendered(); + this.someState.set(someResult); +}); +``` + +For more complicated use-cases, you can manually add and remove a pending task: + +```typescript +const taskService = inject(PendingTasks); +const taskCleanup = taskService.add(); +try { + await doSomeWorkThatNeedsToBeRendered(); +} catch { + // handle error +} finally { + taskCleanup(); +} +``` + +In addition, the [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) helper in `rxjs-interop` ensures +the application remains unstable until the observable emits, completes, errors, or is unsubscribed. + +```typescript +readonly myObservableState = someObservable.pipe(pendingUntilEvent()); +``` + +The framework uses this service internally as well to prevent serialization until asynchronous tasks are complete. These include, but are not limited to, +an ongoing Router navigation and an incomplete `HttpClient` request. + +## Testing and Debugging + +### Using Zoneless in `TestBed` + +The zoneless provider function can also be used with `TestBed` to help +ensure the components under test are compatible with a Zoneless +Angular application. + +```typescript +TestBed.configureTestingModule({ + providers: [provideZonelessChangeDetection()] +}); + +const fixture = TestBed.createComponent(MyComponent); +await fixture.whenStable(); +``` + +To ensure tests have the most similar behavior to production code, +avoid using `fixture.detectChanges()` when possible. This forces +change detection to run when Angular might otherwise have not +scheduled change detection. Tests should ensure these notifications +are happening and allow Angular to handle when to synchronize +state rather than manually forcing it to happen in the test. + +For existing test suites, using `fixture.detectChanges()` is a common pattern +and it is likely not worth the effort of converting these to +`await fixture.whenStable()`. `TestBed` will still enforce that the +fixture's component is `OnPush` compatible and throws `ExpressionChangedAfterItHasBeenCheckedError` +if it finds that template values were updated without a +change notification (i.e. `fixture.componentInstance.someValue = 'newValue';`). +If the component is used in production, this issue should be addressed by updating +the component to use signals for state or call `ChangeDetectorRef.markForCheck()`. +If the component is only used as a test wrapper and never used in an application, +it is acceptable to use `fixture.changeDetectorRef.markForCheck()`. + +### Debug-mode check to ensure updates are detected + +Angular also provides an additional tool to help verify that an application is making +updates to state in a zoneless-compatible way. `provideCheckNoChangesConfig({exhaustive: true, interval: })` +can be used to periodically check to ensure that no bindings have been updated +without a notification. Angular throws `ExpressionChangedAfterItHasBeenCheckedError` +if there is an updated binding that would not have refreshed by the zoneless change +detection. diff --git a/adev-es/src/content/guide/zoneless.md b/adev-es/src/content/guide/zoneless.md index 4eafe65..af8cfdb 100644 --- a/adev-es/src/content/guide/zoneless.md +++ b/adev-es/src/content/guide/zoneless.md @@ -1,23 +1,23 @@ -# Angular without ZoneJS (Zoneless) +# Angular sin ZoneJS (Zoneless) -## Why use Zoneless? +## ¿Por qué usar Zoneless? -The main advantages to removing ZoneJS as a dependency are: +Las principales ventajas de eliminar ZoneJS como dependencia son: -- **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**: ZoneJS works by patching browser APIs but does not automatically have patches for every new browser API. Some APIs cannot be patched effectively, such as `async`/`await`, and have 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. +- **Rendimiento mejorado**: ZoneJS usa eventos del DOM y tareas asíncronas como indicadores de cuándo el estado de la aplicación _podría_ haberse actualizado y posteriormente activa la sincronización de la aplicación para ejecutar la detección de cambios en las vistas de la aplicación. ZoneJS no tiene conocimiento de si el estado de la aplicación realmente cambió, por lo que esta sincronización se activa con más frecuencia de la necesaria. +- **Mejores Core Web Vitals**: ZoneJS trae una cantidad considerable de sobrecarga, tanto en tamaño de payload como en costo de tiempo de inicio. +- **Mejor experiencia de depuración**: ZoneJS hace que depurar código sea más difícil. Los stack traces son más difíciles de entender con ZoneJS. También es difícil entender cuándo el código falla como resultado de estar fuera de la Angular Zone. +- **Mejor compatibilidad con el ecosistema**: ZoneJS funciona parcheando APIs del navegador, pero no tiene automáticamente parches para cada nueva API del navegador. Algunas APIs no pueden ser parcheadas efectivamente, como `async`/`await`, y tienen que ser convertidas a versiones anteriores para funcionar con ZoneJS. A veces, las bibliotecas en el ecosistema también son incompatibles con la forma en que ZoneJS parchea las APIs nativas. Eliminar ZoneJS como dependencia asegura mejor compatibilidad a largo plazo al remover una fuente de complejidad, monkey patching y mantenimiento continuo. -## Enabling Zoneless in an application +## Habilitar Zoneless en una aplicación ```typescript -// standalone bootstrap +// bootstrap standalone bootstrapApplication(MyApp, {providers: [ provideZonelessChangeDetection(), ]}); -// NgModule bootstrap +// bootstrap con NgModule platformBrowser().bootstrapModule(AppModule); @NgModule({ providers: [provideZonelessChangeDetection()] @@ -25,68 +25,52 @@ platformBrowser().bootstrapModule(AppModule); export class AppModule {} ``` -## Removing ZoneJS +## Eliminar ZoneJS -Zoneless applications should remove ZoneJS entirely from the build to reduce bundle size. ZoneJS is typically -loaded via the `polyfills` option in `angular.json`, both in the `build` and `test` targets. Remove `zone.js` -and `zone.js/testing` from both to remove it from the build. Projects which use an explicit `polyfills.ts` file -should remove `import 'zone.js';` and `import 'zone.js/testing';` from the file. +Las aplicaciones Zoneless deberían eliminar ZoneJS completamente de la compilación para reducir el tamaño del bundle. ZoneJS típicamente se carga a través de la opción `polyfills` en `angular.json`, tanto en los targets `build` como `test`. Elimina `zone.js` y `zone.js/testing` de ambos para removerlo de la compilación. Los proyectos que usan un archivo `polyfills.ts` explícito deberían eliminar `import 'zone.js';` e `import 'zone.js/testing';` del archivo. -After removing ZoneJS from the build, there is no longer a need for a `zone.js` dependency either and the -package can be removed entirely: +Después de eliminar ZoneJS de la compilación, ya no hay necesidad de tener `zone.js` como dependencia y el paquete puede ser eliminado completamente: ```shell npm uninstall zone.js ``` -## Requirements for Zoneless compatibility +## Requisitos para compatibilidad con Zoneless -Angular relies on notifications from core APIs in order to determine when to run change detection and on which views. -These notifications include: +Angular depende de notificaciones de las APIs principales para determinar cuándo ejecutar la detección de cambios y en qué vistas. +Estas notificaciones incluyen: -- `ChangeDetectorRef.markForCheck` (called automatically by `AsyncPipe`) +- `ChangeDetectorRef.markForCheck` (llamado automáticamente por `AsyncPipe`) - `ComponentRef.setInput` -- Updating a signal that's read in a template -- Bound host or template listeners callbacks -- Attaching a view that was marked dirty by one of the above +- Actualizar un signal que se lee en una plantilla +- Callbacks de listeners de host o plantilla enlazados +- Adjuntar una vista que fue marcada como dirty por alguno de los anteriores -### `OnPush`-compatible components +### Componentes compatibles con `OnPush` -One way to ensure that a component is using the correct notification mechanisms from above is to -use [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush). +Una forma de asegurar que un componente está usando los mecanismos de notificación correctos mencionados arriba es usar [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush). -The `OnPush` change detection strategy is not required, but it is a recommended step towards zoneless compatibility for application components. It is not always possible for library components to use `ChangeDetectionStrategy.OnPush`. -When a library component is a host for user-components which might use `ChangeDetectionStrategy.Default`, it cannot use `OnPush` because that would prevent the child component from being refreshed if it is not `OnPush` compatible and relies on ZoneJS to trigger change detection. Components can use the `Default` strategy as long as they notify Angular when change detection needs to run (calling `markForCheck`, using signals, `AsyncPipe`, etc.). -Being a host for a user component means using an API such as `ViewContainerRef.createComponent` and not just hosting a portion of a template from a user component (i.e. content projection or a using a template ref input). +La estrategia de detección de cambios `OnPush` no es requerida, pero es un paso recomendado hacia la compatibilidad con zoneless para componentes de aplicación. No siempre es posible para componentes de biblioteca usar `ChangeDetectionStrategy.OnPush`. +Cuando un componente de biblioteca es host para componentes de usuario que podrían usar `ChangeDetectionStrategy.Default`, no puede usar `OnPush` porque eso evitaría que el componente hijo se actualice si no es compatible con `OnPush` y depende de ZoneJS para activar la detección de cambios. Los componentes pueden usar la estrategia `Default` siempre que notifiquen a Angular cuando la detección de cambios necesita ejecutarse (llamando a `markForCheck`, usando signals, `AsyncPipe`, etc.). +Ser host para un componente de usuario significa usar una API como `ViewContainerRef.createComponent` y no solo alojar una porción de una plantilla de un componente de usuario (es decir, proyección de contenido o usar un template ref como entrada). -### Remove `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable`, or `NgZone.onStable` +### Eliminar `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable` o `NgZone.onStable` -Applications and libraries need to remove uses of `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` and `NgZone.onStable`. -These observables will never emit when an Application enables zoneless change detection. -Similarly, `NgZone.isStable` will always be `true` and should not be used as a condition for code execution. +Las aplicaciones y bibliotecas necesitan eliminar los usos de `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` y `NgZone.onStable`. +Estos observables nunca emitirán cuando una aplicación habilita la detección de cambios zoneless. +De manera similar, `NgZone.isStable` siempre será `true` y no debería usarse como condición para la ejecución de código. -The `NgZone.onMicrotaskEmpty` and `NgZone.onStable` observables are most often used to wait for Angular to -complete change detection before performing a task. Instead, these can be replaced by `afterNextRender` -if they need to wait for a single change detection or `afterEveryRender` if there is some condition that might span -several change detection rounds. In other cases, these observables were used because they happened to be -familiar and have similar timing to what was needed. More straightforward or direct DOM APIs can be used instead, -such as `MutationObserver` when code needs to wait for certain DOM state (rather than waiting for it indirectly -through Angular's render hooks). +Los observables `NgZone.onMicrotaskEmpty` y `NgZone.onStable` se usan más frecuentemente para esperar a que Angular complete la detección de cambios antes de realizar una tarea. En su lugar, estos pueden ser reemplazados por `afterNextRender` si necesitan esperar una sola detección de cambios o `afterEveryRender` si hay alguna condición que podría abarcar varias rondas de detección de cambios. En otros casos, estos observables se usaban porque resultaban familiares y tenían un timing similar a lo que se necesitaba. Se pueden usar APIs del DOM más directas en su lugar, como `MutationObserver` cuando el código necesita esperar cierto estado del DOM (en lugar de esperarlo indirectamente a través de los hooks de renderizado de Angular). - -`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. + +`NgZone.run` y `NgZone.runOutsideAngular` no necesitan ser eliminados para que el código sea compatible con aplicaciones Zoneless. De hecho, eliminar estas llamadas puede llevar a regresiones de rendimiento para bibliotecas que se usan en aplicaciones que aún dependen de ZoneJS. -### `PendingTasks` for Server Side Rendering (SSR) +### `PendingTasks` para Server Side Rendering (SSR) -If you are using SSR with Angular, you may know that it relies on ZoneJS to help determine when the application -is "stable" and can be serialized. If there are asynchronous tasks that should prevent serialization, an application -not using ZoneJS must make Angular aware of these with the [PendingTasks](/api/core/PendingTasks) service. Serialization -will wait for the first moment that all pending tasks have been removed. +Si estás usando SSR con Angular, puede que sepas que depende de ZoneJS para ayudar a determinar cuándo la aplicación está "estable" y puede ser serializada. Si hay tareas asíncronas que deberían prevenir la serialización, una aplicación que no usa ZoneJS debe hacer que Angular esté al tanto de estas con el servicio [PendingTasks](/api/core/PendingTasks). La serialización esperará hasta el primer momento en que todas las tareas pendientes hayan sido eliminadas. -The two most straightforward uses of pending tasks are the `run` method: +Los dos usos más directos de las tareas pendientes son el método `run`: ```typescript const taskService = inject(PendingTasks); @@ -96,7 +80,7 @@ taskService.run(async () => { }); ``` -For more complicated use-cases, you can manually add and remove a pending task: +Para casos de uso más complicados, puedes agregar y eliminar manualmente una tarea pendiente: ```typescript const taskService = inject(PendingTasks); @@ -104,29 +88,25 @@ const taskCleanup = taskService.add(); try { await doSomeWorkThatNeedsToBeRendered(); } catch { - // handle error + // manejar error } finally { taskCleanup(); } ``` -In addition, the [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) helper in `rxjs-interop` ensures -the application remains unstable until the observable emits, completes, errors, or is unsubscribed. +Además, el helper [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) en `rxjs-interop` asegura que la aplicación permanezca inestable hasta que el observable emita, complete, tenga un error o se cancele la suscripción. ```typescript readonly myObservableState = someObservable.pipe(pendingUntilEvent()); ``` -The framework uses this service internally as well to prevent serialization until asynchronous tasks are complete. These include, but are not limited to, -an ongoing Router navigation and an incomplete `HttpClient` request. +El framework también usa este servicio internamente para prevenir la serialización hasta que las tareas asíncronas estén completas. Estas incluyen, pero no se limitan a, una navegación del Router en curso y una petición de `HttpClient` incompleta. -## Testing and Debugging +## Pruebas y Depuración -### Using Zoneless in `TestBed` +### Usar Zoneless en `TestBed` -The zoneless provider function can also be used with `TestBed` to help -ensure the components under test are compatible with a Zoneless -Angular application. +La función provider de zoneless también puede usarse con `TestBed` para ayudar a asegurar que los componentes bajo prueba sean compatibles con una aplicación Angular Zoneless. ```typescript TestBed.configureTestingModule({ @@ -137,29 +117,12 @@ const fixture = TestBed.createComponent(MyComponent); await fixture.whenStable(); ``` -To ensure tests have the most similar behavior to production code, -avoid using `fixture.detectChanges()` when possible. This forces -change detection to run when Angular might otherwise have not -scheduled change detection. Tests should ensure these notifications -are happening and allow Angular to handle when to synchronize -state rather than manually forcing it to happen in the test. - -For existing test suites, using `fixture.detectChanges()` is a common pattern -and it is likely not worth the effort of converting these to -`await fixture.whenStable()`. `TestBed` will still enforce that the -fixture's component is `OnPush` compatible and throws `ExpressionChangedAfterItHasBeenCheckedError` -if it finds that template values were updated without a -change notification (i.e. `fixture.componentInstance.someValue = 'newValue';`). -If the component is used in production, this issue should be addressed by updating -the component to use signals for state or call `ChangeDetectorRef.markForCheck()`. -If the component is only used as a test wrapper and never used in an application, -it is acceptable to use `fixture.changeDetectorRef.markForCheck()`. - -### Debug-mode check to ensure updates are detected - -Angular also provides an additional tool to help verify that an application is making -updates to state in a zoneless-compatible way. `provideCheckNoChangesConfig({exhaustive: true, interval: })` -can be used to periodically check to ensure that no bindings have been updated -without a notification. Angular throws `ExpressionChangedAfterItHasBeenCheckedError` -if there is an updated binding that would not have refreshed by the zoneless change -detection. +Para asegurar que las pruebas tengan el comportamiento más similar al código de producción, evita usar `fixture.detectChanges()` cuando sea posible. Esto fuerza la ejecución de la detección de cambios cuando Angular de otra manera no habría programado la detección de cambios. Las pruebas deberían asegurar que estas notificaciones están ocurriendo y permitir que Angular maneje cuándo sincronizar el estado en lugar de forzarlo manualmente en la prueba. + +Para suites de pruebas existentes, usar `fixture.detectChanges()` es un patrón común y probablemente no vale el esfuerzo de convertirlas a `await fixture.whenStable()`. `TestBed` aún aplicará que el componente del fixture sea compatible con `OnPush` y lanzará `ExpressionChangedAfterItHasBeenCheckedError` si encuentra que los valores de la plantilla fueron actualizados sin una notificación de cambio (es decir, `fixture.componentInstance.someValue = 'newValue';`). +Si el componente se usa en producción, este problema debería abordarse actualizando el componente para usar signals para el estado o llamar a `ChangeDetectorRef.markForCheck()`. +Si el componente solo se usa como wrapper de prueba y nunca se usa en una aplicación, es aceptable usar `fixture.changeDetectorRef.markForCheck()`. + +### Verificación en modo debug para asegurar que las actualizaciones se detectan + +Angular también proporciona una herramienta adicional para ayudar a verificar que una aplicación está haciendo actualizaciones al estado de una manera compatible con zoneless. `provideCheckNoChangesConfig({exhaustive: true, interval: })` puede usarse para verificar periódicamente que ningún enlace ha sido actualizado sin una notificación. Angular lanza `ExpressionChangedAfterItHasBeenCheckedError` si hay un enlace actualizado que no se habría refrescado por la detección de cambios zoneless.