From 89ae38a9332dc0f790fbc44a8e5178ab906aa1cb Mon Sep 17 00:00:00 2001 From: James Daniels Date: Thu, 9 Jan 2025 16:29:15 -0500 Subject: [PATCH 1/3] Warn rather than error, thats trippin folk --- src/zones.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/zones.ts b/src/zones.ts index d8505433e..1f845322a 100644 --- a/src/zones.ts +++ b/src/zones.ts @@ -81,11 +81,11 @@ function getSchedulers() { var alreadyWarned = false; function warnOutsideInjectionContext(original: any, operation: string) { if (isDevMode()) { - console.warn(`Firebase API called outside injection context: ${operation}(${original.name})`); if (!alreadyWarned) { alreadyWarned = true; - console.error("Calling Firebase APIs outside of an Injection context may destabilize your application leading to subtle change-detection and hydration bugs. Find more at https://github.com/angular/angularfire/blob/main/docs/zones.md"); + console.warn("Calling Firebase APIs outside of an Injection context may destabilize your application leading to subtle change-detection and hydration bugs. Find more at https://github.com/angular/angularfire/blob/main/docs/zones.md"); } + console.warn(`Firebase API called outside injection context: ${operation}(${original.name})`); } } From ebd5d3194abbcd1dd6c68d7b9c9be2e5ddf31e97 Mon Sep 17 00:00:00 2001 From: James Daniels Date: Thu, 9 Jan 2025 17:05:00 -0500 Subject: [PATCH 2/3] Add doc on zone wrappers --- docs/zones.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/zones.md diff --git a/docs/zones.md b/docs/zones.md new file mode 100644 index 000000000..0e9eca17b --- /dev/null +++ b/docs/zones.md @@ -0,0 +1,21 @@ + +AngularFire ❱ Developer Guide ❱ Zone Wrappers + + +# Zone Wrappers + +AngularFire wraps the [framework agnostic Firebase JS SDK](https://github.com/firebase/firebase-js-sdk) and [RxFire](https://github.com/firebaseextended/rxfire) to ensure proper functionality in Zone and Zoneless applications alike. + +These wrappers ensure Firebase APIs are called outside of the Angular zone but return in the Angular zone. This isolates side-effects such as timers so that they do not destabilize your application. + +Observables, Promise-based APIs, and callbacks will await an initial emission before stabilizing your application allowing for proper SSR/SSG functionality + +## Consequences of not Zone wrapping + +When using a Firebase or RxFire API without importing from AngularFire or if AngularFire APIs are used outside of an injection context you _may_ experience instability. + +To help debugging, AngularFire emits warnings when it is unable to Zone wrap an API while in dev-mode. **Often these messages can be safely ignored** but instability can be difficult to track down ([see Resolving zone pollution in the Angular docs](https://angular.dev/best-practices/zone-pollution)), so we'd rather be verbose. + +When an application is unstable change-detection, two-way binding, and rehydration may not work as expected—leading to subtle and non-subtle bugs and performance issues in your application. Further, server-side rendering (SSR) and static site generation (SSG/pre-rendering) may timeout or render a blank page. + +There are a number of situations where AngularFire's Zone wrapping is inconsequential such adding/deleting/updating a document in response to user-input, signing a user in, etc. So long as no long-lived side-effects are kicked off, your application should be ok. Most Promise based APIs are fairly safe without zone wrapping. From 2eea611579ff6446e173d5cbcba9f59f65a423b1 Mon Sep 17 00:00:00 2001 From: James Daniels Date: Thu, 9 Jan 2025 17:14:51 -0500 Subject: [PATCH 3/3] Words --- docs/zones.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/zones.md b/docs/zones.md index 0e9eca17b..2b2e39b82 100644 --- a/docs/zones.md +++ b/docs/zones.md @@ -6,16 +6,16 @@ AngularFire wraps the [framework agnostic Firebase JS SDK](https://github.com/firebase/firebase-js-sdk) and [RxFire](https://github.com/firebaseextended/rxfire) to ensure proper functionality in Zone and Zoneless applications alike. -These wrappers ensure Firebase APIs are called outside of the Angular zone but return in the Angular zone. This isolates side-effects such as timers so that they do not destabilize your application. +These wrappers ensure Firebase APIs are called outside of the Angular zone. This isolates side-effects such as timers so that they do not destabilize your application. -Observables, Promise-based APIs, and callbacks will await an initial emission before stabilizing your application allowing for proper SSR/SSG functionality +Observables, Promise-based APIs, and those with callbacks will purposely destabilize your application until a initial value is returned, this ensures that server-side rendering (SSR) and static site generation (SSG/pre-rendering) wait for data before rendering the page's HTML. ## Consequences of not Zone wrapping When using a Firebase or RxFire API without importing from AngularFire or if AngularFire APIs are used outside of an injection context you _may_ experience instability. -To help debugging, AngularFire emits warnings when it is unable to Zone wrap an API while in dev-mode. **Often these messages can be safely ignored** but instability can be difficult to track down ([see Resolving zone pollution in the Angular docs](https://angular.dev/best-practices/zone-pollution)), so we'd rather be verbose. +instability can be difficult to track down ([see Resolving zone pollution in the Angular docs](https://angular.dev/best-practices/zone-pollution)). To help with debugging, AngularFire emits warnings when it is unable to Zone wrap an API while in dev-mode. **Often these messages can be safely ignored** but we'd rather be verbose. -When an application is unstable change-detection, two-way binding, and rehydration may not work as expected—leading to subtle and non-subtle bugs and performance issues in your application. Further, server-side rendering (SSR) and static site generation (SSG/pre-rendering) may timeout or render a blank page. +When an application is unstable change-detection, two-way binding, and rehydration may not work as expected—leading to both subtle and non-subtle bugs in your application. Further, server-side rendering (SSR) and static site generation (SSG/pre-rendering) may timeout or render a blank page. -There are a number of situations where AngularFire's Zone wrapping is inconsequential such adding/deleting/updating a document in response to user-input, signing a user in, etc. So long as no long-lived side-effects are kicked off, your application should be ok. Most Promise based APIs are fairly safe without zone wrapping. +There are a number of situations where AngularFire's Zone wrapping is inconsequential such adding/deleting/updating a document in response to user-input, signing a user in, calling a Cloud Function, etc. So long as no long-lived side-effects are kicked off, your application should be ok. Most Promise based APIs are fairly safe without zone wrapping.