Skip to content

Backport docs changes to 21.1.x - #3849

Open
armando-navarro wants to merge 5 commits into
angular:21.1.xfrom
armando-navarro:docs-backports-21
Open

armando-navarro wants to merge 5 commits into
angular:21.1.xfrom
armando-navarro:docs-backports-21

Conversation

@armando-navarro

Copy link
Copy Markdown
Collaborator

Refs #3336
Refs #3081
Refs #3073
Refs #3834
Refs #3683

This pull request carries four docs cherry-picks from main onto 21.1.x, plus one commit written for this branch. It should merge after #3848, because docs/auth.md, docs/app-check.md, docs/zones.md and docs/database.md describe the code that pull request brings.

Commits, in order

Commit From main Change
e731e02 1b1a8b6 (#3810) docs/compat.md states the compatibility API's support status
6118794 d21d243 (#3838) Typed Firestore reads use a converter instead of a type argument
b78e830 ba07218 (#3835) A compat Setup section, the server-rendering guide built on initializeBrowserOrServerApp, and the zone wrapper text for #3827, #3829 and #3842
843212e b2b2ba3 (#3847) Dead Firebase JS SDK reference links fixed
96562ad written for this branch docs/auth.md says the linked sample app is the Angular 22 one on main

Where the cherry-picks differ from main

#3838 and #3847 apply unchanged, with their original commit messages.

The commit written for this branch

docs/auth.md links the sample app on main as an example of the one-call server setup. That app is on Angular 22, and sample/ on 21.1.x does not call initializeBrowserOrServerApp. 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.

armando-navarro and others added 5 commits November 18, 2026 02:47
)

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)
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.
@armando-navarro armando-navarro added bump: patch Size of the change: a fix or docs change that reaches users comp: compat Compatibility layer for the pre-modular API (src/compat). comp: docs Documentation. comp: firestore Cloud Firestore (src/firestore). type: chore Maintenance with no user-facing behavior change. labels Nov 18, 2026
@armando-navarro armando-navarro added this to the 21.1.0 milestone Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bump: patch Size of the change: a fix or docs change that reaches users comp: compat Compatibility layer for the pre-modular API (src/compat). comp: docs Documentation. comp: firestore Cloud Firestore (src/firestore). type: chore Maintenance with no user-facing behavior change.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants