Repository navigation
Backport docs changes to 21.1.x - #3849
Open
armando-navarro wants to merge 5 commits into
Open
armando-navarro wants to merge 5 commits into
armando-navarro wants to merge 5 commits into
Conversation
) docs/compat.md had no statement of whether @angular/fire/compat is supported, and the v7 upgrade guide still told readers to stop at the compatibility API because the modular API was not feature complete, a sentence written for the 7.0 release. The new section says the compatibility API is supported, receives bug fixes and no new features, and has no planned removal. It also says which of its tests CI skips (AngularFirestoreCollection, AngularFirestoreCollectionGroup, AngularFirestoreDocument and one Cloud Storage upload) and links the issue that tracks turning them back on. The v7 guide line now points at that section. (cherry picked from commit 1b1a8b6)
…nt (angular#3838) The README, the quickstart and the v7 upgrade guide showed collectionData<Item>(collection(firestore, 'items')), which fails with TS2345: collection() returns a reference typed DocumentData and the type argument asks for Item. docs/firestore.md cast the result with `as Observable<UserProfile[]>` instead, which compiles but checks nothing. The examples now attach a FirestoreDataConverter through withConverter, the Firebase SDK's way to type a reference, with a fromFirestore that substitutes a default for a missing or wrong field. A new "Typed reads" section in docs/firestore.md says why the two shortcuts do not give a typed read, where the default-versus-throw choice lives, and that idField performs no validation. (cherry picked from commit d21d243)
…ar#3835) * docs: say which wrapped calls do not hold the app unstable docs/zones.md says callback APIs hold the app unstable until an initial value, so a server render waits for data. angular#3827 makes a set of calls exceptions because their first callback may never come. Waiting on a callback that never comes would keep the app from ever becoming stable. List those calls in docs/zones.md, and point at onValue, object, list, listVal and fromRef with the value event as the calls that still make a server render wait. In docs/database.md, say the same under stateChanges, auditTrail and fromRef. Refs angular#3826 * docs: say a handler passed as an observer object is wrapped too angular#3829 wraps a handler passed as an observer object, such as { next, error }, the way it wraps a function, so the injection context reaches both forms. Refs angular#3828 * docs(compat): add a setup section in NgModule and standalone form The compat API's setup steps left docs/install-and-setup.md when angular#3236 rewrote it for the modular API, and nothing replaced them. docs/compat.md had no setup at all, the Realtime Database pages pointed at an "Installation guide" that no longer covered compat, and no page showed the standalone form. A standalone app with only the modular providers then fails its first compat injection with NG0201 for angularfire2.app.options (angular#3683). The new section on docs/compat.md gives both forms, says when the modular providers may stay, states the error the missing module produces, and lists the compat module of each product. The twelve compat pages that had an NgModule-only snippet or no setup at all now point at it. Fixes angular#3683 * docs: say which Firestore functions are not zone wrapped angular#3842 re-exports Firestore's query and reference builders, field values, comparators and setLogLevel without the zone wrapper. In docs/zones.md, add a paragraph listing them, change the switchMap example to a read, since building the query no longer warns, and say the Verbose log level covers only wrapped calls. Refs angular#3842 * docs(auth): build the server app with initializeBrowserOrServerApp The server-rendering guide's step 4 becomes the one call, the five details become three, the App Check token gets a relay section, the response gets a Cache-Control header, and the manual callback stays in a "Building the app yourself" section that step 4 points at, for apps that prefer it or whose AngularFire version has no such function. The release modes say what a throwing ngOnDestroy does to a timed release. * docs(auth): describe the sample as an example of the one-call server app The sample app on main now has one provideFirebaseApp with initializeBrowserOrServerApp in its shared app.config.ts (angular#3845), so the sentence about its split client and server files no longer holds. Refs angular#3843 * docs(auth): say which hooks stop a releaseAfterRender release The caveat on releaseAfterRender said a throwing ngOnDestroy "stops that teardown". It now says the release is a DestroyRef.onDestroy callback, that Angular runs it after every service's and component's ngOnDestroy, and that an ngOnDestroy method or an ApplicationRef.onDestroy listener that throws keeps it from running. The default release, which does not run during the injector's destroy, is unaffected either way. A new paragraph says to call initializeBrowserOrServerApp in app.config.ts rather than a route's providers: a route's child injector is not destroyed with the request, so a release registered there never runs. Refs angular#3844 * docs(auth): say the default release still happens from a route's providers Tyler asked on angular#3844 whether the default release, now tied to a root service, releases a server app built in a lazy route's providers. It does: the request's root injector is destroyed, the route's child injector is not, so only a releaseAfterRender release registered there is lost. Checked with a child environment injector that is never destroyed, in both modes. Refs angular#3844 * docs: add onConfigUpdate to the calls that do not hold the app unstable angular#3829 set onConfigUpdate to blockUntilFirst: false in tools/build.ts, because its observer runs only when a fetched template differs from the active one. The list in docs/zones.md left it out. Found in the angular#3835 review. Refs angular#3829 * docs(auth): say a second provideFirebaseApp can render signed out The bullet said a second registration makes a signed-in render fail on a freshly started server. With more than one registration, FirebaseApp resolves to the default app. Run on fresh servers, a second plain initializeApp(config) registration creates that app on the first request, so signed-in pages render signed out with no error. Only when no registration creates the default app, as with two initializeBrowserOrServerApp registrations, does the render fail, and only until a signed-out request creates it. Found in the angular#3835 review. Refs angular#3844 (cherry picked from commit ba07218)
(cherry picked from commit b2b2ba3)
The server-rendering guide links the sample app on main as an example of the one-call setup. On this branch the sample folder is an Angular 21 app that does not call initializeBrowserOrServerApp, so the sentence now says which app the link opens and that the call is the same on Angular 21.
tyler-reitz
approved these changes
Nov 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #3336
Refs #3081
Refs #3073
Refs #3834
Refs #3683
This pull request carries four docs cherry-picks from
mainonto21.1.x, plus one commit written for this branch. It should merge after #3848, becausedocs/auth.md,docs/app-check.md,docs/zones.mdanddocs/database.mddescribe the code that pull request brings.Commits, in order
maine731e021b1a8b6(#3810)docs/compat.mdstates the compatibility API's support status6118794d21d243(#3838)b78e830ba07218(#3835)initializeBrowserOrServerApp, and the zone wrapper text for #3827, #3829 and #3842843212eb2b2ba3(#3847)96562addocs/auth.mdsays the linked sample app is the Angular 22 one onmainWhere the cherry-picks differ from
main#3838 and #3847 apply unchanged, with their original commit messages.
docs/version-22-upgrade.mdis left out, because21.1.xhas no v22 upgrade guide. The 17 files the commit keeps apply unchanged.The commit written for this branch
docs/auth.mdlinks the sample app onmainas an example of the one-call server setup. That app is on Angular 22, andsample/on21.1.xdoes not callinitializeBrowserOrServerApp. The sentence says which app the link opens and that the call is the same on Angular 21.I plan to use rebase and merge, so each commit stays separate on
21.1.x.