GeezerVison

Fixes #3843

• Docs included?: no. The docs/auth.md, docs/app-check.md and docs/version-22-upgrade.md changes go on the rc.1 docs pull request, docs: document the 22.0.0-rc.1 changes #3835, which merges just before the tag.
• Test units included?: yes.
  • New Node specs in src/app/browser-or-server-app.jasmine.ts.
  • A browser spec in src/app/app.spec.ts and two in src/app-check/app-check.spec.ts.
• Breaking change?: no. Nothing calls the new function until an app opts in. The App Check server warning's text changes.
• In a clean directory, yarn install, yarn test run successfully? yes, with npm: npm ci, npm run build, npm run lint, npm run test:node on Node 22, 24 and 26, and npm run test:chrome-headless.

Description

This adds initializeBrowserOrServerApp to @angular/fire/app, one call inside provideFirebaseApp that returns the ordinary app in the browser and a FirebaseServerApp for the visitor's tokens on the server. It replaces the callback the Authentication guide asks server-rendered apps to write. The reasoning is in the linked issue.

Changes

• src/app/browser-or-server-app.ts, exported from @angular/fire/app:
  • initializeBrowserOrServerApp(options, settings?). On the server it reads authIdToken and appCheckToken from REQUEST_CONTEXT, or from settings when passed there, and builds a server app when either is present.
  • By default the server app is released when the render is garbage collected, the way releaseOnDeref works, so a repeat request from the same visitor reuses it.
    • settings.releaseAfterRender opts into a release at render end (0) or that many milliseconds after it.
    • On a runtime without FinalizationRegistry the release is at render end.
  • releaseOnDeref is typed never, and stripped at runtime, so one server app is never released twice.
  • A token the SDK cannot parse (its own check throws a SyntaxError or TypeError) returns the ordinary app after one fixed warning per process, then one line per hundred. Every FirebaseError still propagates.
  • In dev mode, a request with no request context is noted once per process.
  • When the server app the SDK returns does not carry the tokens asked for, the ordinary app is returned instead.
• src/app-check/app-check.module.ts: the dev-mode server warning now says that server renders without a relayed App Check token send none, and points at the new function.
• src/app/app.ts: the comment's usage example no longer shows deleteApp on the injected app.
• tools/angular-fire-resolve-hook.mjs and tools/jasmine-register-angular-fire.mjs, preloaded by test:node and test:node-esm: a resolve hook that maps @angular/fire imports to the built library, so Node specs can import it. No Node spec could before.

Behavior to know

• The function always builds the default app. Keep exactly one provideFirebaseApp and pass inject(FirebaseApp) to every product provider, as the guide says.
• Never call deleteApp on the injected app when using the function. It releases the server app itself.
• A fresh server app costs about 300 to 400 ms (a Firestore connection and an account lookup).
  • With the default release a repeat request for the same visitor is as fast as a signed-out one.
  • With releaseAfterRender: 0 every repeat request pays that cost again, which the docs state.
• With releaseAfterRender set, the release is a DestroyRef.onDestroy callback. An ngOnDestroy method or an ApplicationRef.onDestroy listener that throws keeps it from running, and that render's server app stays behind. The default release does not run during that destroy and is not affected.

Verified outside CI

On a fresh Angular 22 app wired by following the rewritten guide literally, against a real project:

• 24 concurrent signed-in renders with distinct tokens, and 24 sharing one token, in each release mode: every page rendered signed in with its Firestore data, and the server-app count returned to zero (after a forced collection in the default mode, without one with releaseAfterRender: 0, after about a second with 1000). Also under ng serve and in an NgModule-bootstrapped app.
• Unparseable, junk, expired and real stale cookies: HTTP 200 and a signed-out page every time, with the helper's warning only for the unparseable one.
• With App Check enforcement on for Firestore: a render with a relayed token reads Firestore, the same render without one is rejected, and an expired App Check token fails the read in 340 ms rather than hanging.
• The sample app's split app.config.client.ts and app.config.server.ts layout renders signed out and signed in. The production browser bundle is the same size with and without the function.
• A raw firebase/firestore read still pending when the app is released at render end resolves normally, and a client abort mid-render lets the render finish and release its app.

Tyler, the part I'd most like a second look at is the release in buildServerApp: the default hands the SDK a root service (ɵRequestLifetime) that lives as long as the render's injector, and the timed mode releases from the injector's onDestroy.