@angular/fire 20.0.3 → 21.0.0-canary.20260927231611.sha-ac17ede

package/docs/auth.md

@@ -15,14 +15,12 @@ Firebase Authentication integrates tightly with other Firebase services, and it
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
-Provide a Auth instance in the application's `app.config.ts`:
+Provide an Auth instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideAuth, getAuth } from '@angular/fire/auth';
 
@@ -33,7 +31,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `Auth` into your component:
@@ -59,13 +57,159 @@ Update the imports from `import { ... } from 'firebase/auth'` to `import { ... }
 
 ## Server-side Rendering
 
-To support Auth context in server-side rendering, you can provide `FirebaseServerApp`:
+When Angular renders your app on the server, the server does not know which user is visiting. To render the page as that user, pass their Auth ID token to `initializeServerApp`, which gives you a Firebase app that is already signed in as them.
+
+Getting the token to the server is your app's job. This guide keeps it in a cookie, because the browser attaches cookies to every request on its own.
+
+All 4 steps below are required. Miss any one of them and the page still renders, but it renders signed out, with no error to tell you why.
+
+### 1. Serve the route with `RenderMode.Server`
+
+`ng new --ssr` scaffolds `app.routes.server.ts` with every route set to `RenderMode.Prerender`. Prerendering runs at build time, so there is no request and no cookie, and Angular provides neither `REQUEST` nor `REQUEST_CONTEXT`. Any route that must already render as the signed-in user before hydration has to be `RenderMode.Server`. A `RenderMode.Client` route renders in the browser, where the user is already signed in, so it needs none of this.
+
+```ts
+import { RenderMode, ServerRoute } from '@angular/ssr';
+
+export const serverRoutes: ServerRoute[] = [
+  { path: 'account', renderMode: RenderMode.Server },
+  { path: '**', renderMode: RenderMode.Prerender },
+];
+```
+
+The rest of this guide has no effect on routes rendered any other way.
+
+### 2. Keep the ID token in a cookie
+
+Install [js-cookie](https://github.com/js-cookie/js-cookie):
+
+```bash
+npm install js-cookie
+npm install --save-dev @types/js-cookie
+```
+
+Add the cookie sync to your `app.config.ts`. AngularFire's `idToken` observable emits on sign-in, on sign-out, and whenever the token is refreshed.
 
 ```ts
-import { ApplicationConfig, PLATFORM_ID, inject } from '@angular/core';
+import { DestroyRef, PLATFORM_ID, inject, provideAppInitializer } from '@angular/core';
 import { isPlatformBrowser } from '@angular/common';
-import { provideFirebaseApp, initializeApp, initializeServeApp, initializeServerApp } from '@angular/fire/app';
-import { provideAuth, getAuth } from '@angular/fire/auth';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { Auth, idToken } from '@angular/fire/auth';
+import { beforeAuthStateChanged } from 'firebase/auth';
+import cookies from 'js-cookie';
+
+// add to appConfig.providers
+provideAppInitializer(() => {
+  if (!isPlatformBrowser(inject(PLATFORM_ID))) {
+    return;
+  }
+  const auth = inject(Auth);
+  const destroyRef = inject(DestroyRef);
+
+  const writeSessionCookie = (token: string | undefined) => {
+    if (token) {
+      cookies.set('__session', token, { secure: true, sameSite: 'lax' });
+    } else {
+      cookies.remove('__session');
+    }
+  };
+
+  idToken(auth)
+    .pipe(takeUntilDestroyed(destroyRef))
+    .subscribe((token) => writeSessionCookie(token ?? undefined));
+
+  let priorToken: string | undefined;
+  const unsubscribe = beforeAuthStateChanged(
+    auth,
+    async (user) => {
+      // Must update the cookie before the sign-out completes, otherwise a page
+      // load that races it still sends the signed-out user's token.
+      priorToken = cookies.get('__session');
+      writeSessionCookie(await user?.getIdToken());
+    },
+    () => writeSessionCookie(priorToken)
+  );
+  destroyRef.onDestroy(unsubscribe);
+}),
+```
+
+The 2 hooks cover different moments:
+- `idToken` fires after an auth state change has completed, and also when Firebase refreshes the token in the background, which is what keeps the cookie current.
+- `beforeAuthStateChanged` fires earlier, while an auth state change is still in progress and before Firebase sets the new user, so a page load that races a sign-out cannot send a token for the user who just left and get their data rendered back. Its third argument puts the cookie back if another blocking callback rejects the auth state change.
+
+Name the cookie `__session`. Behind Firebase Hosting it is the [only cookie forwarded](https://firebase.google.com/docs/hosting/manage-cache#using_cookies) to your server code, and any other name is dropped before your app sees it.
+
+#### Both attributes matter
+
+The cookie sync above sets `{ secure: true, sameSite: 'lax' }`, and neither attribute is optional.
+
+- `secure` keeps the cookie off unencrypted connections. Browsers make an exception for `localhost`, so local development still works.
+- `sameSite: 'lax'` keeps the cookie off cross-site requests while still sending it when someone follows a link into your app, which is what lets that first page render signed in. If your app never needs a signed-in first render from an external link, use `'strict'` instead.
+
+#### What this cookie carries
+
+This cookie carries a short-lived ID token that scripts on your page can read. Firebase already keeps the signed-in state in browser storage, so the cookie does not create a new place for a token to be stolen from, but it does travel on every request.
+
+If you need a session the browser cannot read, use Firebase's [session cookies](https://firebase.google.com/docs/auth/admin/manage-cookies) with the Admin SDK instead. Those cannot be handed to `initializeServerApp`, so that approach means verifying the cookie yourself and building your own server-side Auth context.
+
+#### `beforeAuthStateChanged` from `firebase/auth`
+
+One import in the code above is deliberately different from the rest of this guide. `beforeAuthStateChanged` comes from `firebase/auth` rather than `@angular/fire/auth`. AngularFire's version keeps the app marked as busy until its callback first runs, and this callback only runs when someone signs in or out.
+
+Importing it from `@angular/fire/auth` makes `ng build` hang during route extraction and fail with a timeout. That is a bug on our side, tracked in [#3748](https://github.com/angular/angularfire/issues/3748). Once the fix lands, this can be imported from `@angular/fire/auth` like everything else.
+
+### 3. Pass the cookie into the render
+
+Install [cookie-parser](https://github.com/expressjs/cookie-parser):
+
+```bash
+npm install cookie-parser
+npm install --save-dev @types/cookie-parser
+```
+
+The `server.ts` the Angular CLI generated already renders your app for every request that is not a static file. Replace that existing `app.use` block with this one, which reads the cookie and hands the token to the render. Do not add a second block, because the first one to match wins and the token would never arrive:
+
+```ts
+// server.ts
+import cookieParser from 'cookie-parser';
+
+app.use(cookieParser());
+
+app.use((req, res, next) => {
+  angularApp
+    .handle(req, { authIdToken: req.cookies?.__session })
+    .then((response) =>
+      response ? writeResponseToNodeResponse(response, res) : next(),
+    )
+    .catch(next);
+});
+```
+
+Keep it where the generated block already was, below the block that serves static files, so real files are still served before Angular tries to render them. The rest of the file, including the part that starts the server, stays as it is.
+
+The second argument to `handle` is what the render reads back as `REQUEST_CONTEXT`.
+
+### 4. Build the server app from the token
+
+In `app.config.ts`, choose the Firebase app based on where the code is running, and pass that app to every Firebase provider:
+
+```ts
+import {
+  ApplicationConfig,
+  PLATFORM_ID,
+  REQUEST_CONTEXT,
+  inject,
+} from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import {
+  FirebaseApp,
+  initializeApp,
+  initializeServerApp,
+  provideFirebaseApp,
+} from '@angular/fire/app';
+import { getAuth, provideAuth } from '@angular/fire/auth';
+import { getFirestore, provideFirestore } from '@angular/fire/firestore';
+
+const firebaseConfig = { /* ...your Firebase configuration... */ };
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -73,22 +217,60 @@ export const appConfig: ApplicationConfig = {
       if (isPlatformBrowser(inject(PLATFORM_ID))) {
         return initializeApp(firebaseConfig);
       }
-      // Optional, since it's null in dev-mode and SSG
-      const request = inject(REQUEST, { optional: true });
-      const authIdToken = request?.headers.authorization?.split("Bearer ")[1];
+      const requestContext = inject(REQUEST_CONTEXT, { optional: true }) as
+        | { authIdToken?: string }
+        | null;
+      if (!requestContext?.authIdToken) {
+        return initializeApp(firebaseConfig);
+      }
       return initializeServerApp(firebaseConfig, {
-        authIdToken,
-        releaseOnDeref: request || undefined
+        authIdToken: requestContext.authIdToken,
+        releaseOnDeref: requestContext,
       });
     }),
-    provideAuth(() => getAuth(inject(FirebaseApp)),
-    ...
+    provideAuth(() => getAuth(inject(FirebaseApp))),
+    provideFirestore(() => getFirestore(inject(FirebaseApp))),
+    // ...
   ],
-  ...
-})
+};
 ```
 
-Follow Firebase's [ Session Management with Service Workers documentation](https://firebase.google.com/docs/auth/web/service-worker-sessions) to learn how to pass the `idToken` to the server. __Note: this will not currently work in dev-mode as Angular SSR does not provide a method to get the Request headers.__
+#### Five details make this work
+
+- **Keep exactly one `provideFirebaseApp`.** AngularFire hands you the app you provided only when a single one is registered, and falls back to the default app otherwise. A second registration anywhere in your configuration would make the server app be silently ignored.
+- **Pass `inject(FirebaseApp)` to every provider, not just `provideAuth`.** `ng add @angular/fire` writes them without an argument, which resolves the default app. On a signed-in request the factory above builds a server app instead, so a provider that asks for the default app fails outright on a freshly started server.
+- **Keep the signed-out fallback.** There is no request context when Angular prerenders a page, and no token when the visitor is signed out, so the fallback builds an ordinary Firebase app and the page renders signed out.
+- **Pass `releaseOnDeref`.** It tells the SDK when it may release the server app. The SDK watches the object you give it and releases once that object is garbage collected, so pass one that lives exactly as long as the render, such as the request context itself. Leave it out and the SDK requires you to call `deleteApp` yourself for each server app you create.
+- **The cast is needed** because Angular types `REQUEST_CONTEXT` as `unknown`.
+
+AngularFire's [sample app](https://github.com/angular/angularfire/tree/main/sample) does this differently, giving the browser and the server their own `app.config.client.ts` and `app.config.server.ts` instead of deciding at runtime, inside a single `provideFirebaseApp` factory, which of `initializeApp` and `initializeServerApp` to call. That is also fine, and it keeps the server-only code out of the browser bundle, at the cost of an extra file to wire up.
+
+ID tokens are short-lived, and a returning visitor's browser can send one that expired while the tab was closed. The server cannot refresh it, because a user restored from an ID token has no refresh token, so Firebase logs an error and the page renders signed out. The browser then refreshes the token and the page updates.
+
+### Using `REQUEST` instead of a cookie
+
+Angular also exposes the request itself through the `REQUEST` token, so you can read the ID token from an `Authorization` header rather than a cookie. Firebase's [session management with service workers](https://firebase.google.com/docs/auth/web/service-worker-sessions) guide covers attaching that header. Steps 1, 3 and 4 stay the same apart from the server half of the factory, which becomes:
+
+```ts
+import { PLATFORM_ID, REQUEST, inject } from '@angular/core';
+
+provideFirebaseApp(() => {
+  if (isPlatformBrowser(inject(PLATFORM_ID))) {
+    return initializeApp(firebaseConfig);
+  }
+  const request = inject(REQUEST, { optional: true });
+  const authIdToken = request?.headers.get('authorization')?.split('Bearer ')[1];
+  if (!authIdToken) {
+    return initializeApp(firebaseConfig);
+  }
+  return initializeServerApp(firebaseConfig, {
+    authIdToken,
+    releaseOnDeref: request,
+  });
+}),
+```
+
+`REQUEST` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request), so headers are read with `headers.get(...)`. Angular sets it to `null` during builds, during static site generation, and during route extraction in development, and it is only supplied at all on `RenderMode.Server` routes, so keep the signed-out fallback for those passes.
 
 ## Convenience observables
 
@@ -106,7 +288,7 @@ import { Auth, User, user } from '@angular/fire/auth';
 
 export class UserComponent implements OnDestroy {
   private auth: Auth = inject(Auth);
-  user$ = user(auth);
+  user$ = user(this.auth);
   userSubscription: Subscription;
   ...
 
@@ -136,7 +318,7 @@ import { Auth, authState } from '@angular/fire/auth';
 
 export class UserComponent implements OnDestroy {
   private auth: Auth = inject(Auth);
-  authState$ = authState(auth);
+  authState$ = authState(this.auth);
   authStateSubscription: Subscription;
   ...
 
@@ -165,14 +347,14 @@ import { Auth, idToken } from '@angular/fire/auth';
 
 export class UserComponent implements OnDestroy {
   private auth: Auth = inject(Auth);
-  idToken$ = idToken(auth);
+  idToken$ = idToken(this.auth);
   idTokenSubscription: Subscription;
   ...
 
   constructor() {
     this.idTokenSubscription = this.idToken$.subscribe((token: string | null) => {
-        //handle idToken changes here. Note, that user will be null if there is no currently logged in user.
-     console.log(string);
+        //handle idToken changes here. Note, that token will be null if there is no currently logged in user.
+     console.log(token);
     })
   }
 
@@ -186,15 +368,18 @@ export class UserComponent implements OnDestroy {
 ## Connecting the emulator suite
 
 ```ts
+import { ApplicationConfig, inject } from '@angular/core';
+import { FirebaseApp, provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { connectAuthEmulator, getAuth, provideAuth } from '@angular/fire/auth';
 
-@NgModule({
-  imports: [
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFirebaseApp(() => initializeApp({ ... })),
     provideAuth(() => {
-      const auth = getAuth();
+      const auth = getAuth(inject(FirebaseApp));
       connectAuthEmulator(auth, 'http://localhost:9099', { disableWarnings: true });
       return auth;
     }),
   ]
-})
+}
 ```

package/docs/compat/auth/router-guards.md

@@ -1,6 +1,6 @@
 # Route users with AngularFire guards
 
-`AngularFireAuthGuard` provides a prebuilt [`canActivate` Router Guard](https://angular.io/api/router/CanActivate) using `AngularFireAuth`. By default unauthenticated users are not permitted to navigate to protected routes:
+`AngularFireAuthGuard` provides a prebuilt [`canActivate` Router Guard](https://angular.dev/api/router/CanActivate) using `AngularFireAuth`. By default unauthenticated users are not permitted to navigate to protected routes:
 
 > **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
 

package/docs/compat.md

@@ -1,5 +1,5 @@
 # AngularFire
-The official [Angular](https://angular.io/) library for [Firebase](https://firebase.google.com/).
+The official [Angular](https://angular.dev/) library for [Firebase](https://firebase.google.com/).
 
 <strong><pre>ng add @angular/fire</pre></strong>
 

package/docs/data-connect.md

@@ -0,0 +1,56 @@
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Data Connect
+</small>
+
+# Data Connect
+
+Firebase Data Connect (now known as "Firebase SQL Connect" in the Firebase documentation) is a backend service that pairs a Cloud SQL for PostgreSQL database with GraphQL, generating type-safe SDKs to query and mutate your data.
+
+[Learn more](https://firebase.google.com/docs/data-connect)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
+
+Provide a Data Connect instance in the application's `app.config.ts`. `getDataConnect` takes a connector config that identifies your service, connector, and location; this is generated for you when you set up Data Connect and is also exported from your generated SDK:
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
+
+const connectorConfig = {
+  connector: 'my-connector',
+  service: 'my-service',
+  location: 'us-central1',
+};
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFirebaseApp(() => initializeApp({ ... })),
+    provideDataConnect(() => getDataConnect(connectorConfig)),
+    ...
+  ],
+  ...,
+}
+```
+
+Next inject `DataConnect` into your component:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { DataConnect } from '@angular/fire/data-connect';
+
+@Component({ ... })
+export class MyComponent {
+    private dataConnect = inject(DataConnect);
+    ...
+}
+```
+
+## Firebase API
+
+AngularFire wraps the Firebase JS SDK to ensure proper functionality in Angular, while providing the same API.
+
+Update the imports from `import { ... } from 'firebase/data-connect'` to `import { ... } from '@angular/fire/data-connect'` and follow the official documentation.
+
+[Getting Started](https://firebase.google.com/docs/data-connect/quickstart)

package/docs/database.md

@@ -12,14 +12,12 @@ The Firebase Realtime Database is a cloud-hosted database. Data is stored as JSO
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
 Provide a Database instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideDatabase, getDatabase } from '@angular/fire/database';
 
@@ -30,7 +28,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `Database` into your component:
@@ -131,22 +129,26 @@ The `fromRef()` function creates an observable that emits reference changes.
 ## Connecting to the emulator suite
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { connectDatabaseEmulator, getDatabase, provideDatabase } from '@angular/fire/database';
 
-@NgModule({
-  imports: [
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFirebaseApp(() => initializeApp({ ... })),
     provideDatabase(() => {
       const database = getDatabase();
       connectDatabaseEmulator(database, 'localhost', 9000);
       return database;
     }),
   ]
-})
+}
 ```
 
 ## Working with multiple instances
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, FirebaseApp, initializeApp } from '@angular/fire/app';
 import { getDatabase, provideDatabase } from '@angular/fire/database';
 
@@ -156,14 +158,14 @@ const DATABASE_SHARD_URLS = [
   'https://BAZ.firebaseio.com',
 ];
 
-@NgModule({
-  imports: [
-    provideFirebaseApp(() => initializeApp(environment.firebase)),
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFirebaseApp(() => initializeApp({ ... })),
     provideDatabase((app: FirebaseApp) => getDatabase(app, DATABASE_SHARD_URLS[0])),
     provideDatabase((app: FirebaseApp) => getDatabase(app, DATABASE_SHARD_URLS[1])),
     provideDatabase((app: FirebaseApp) => getDatabase(app, DATABASE_SHARD_URLS[2])),
   ]
-})
+}
 ```
 
 ```ts

package/docs/deploy/getting-started.md

@@ -1,5 +1,7 @@
 # Deploy your application on Firebase Hosting & Functions
 
+> **This page is out of date.** It describes a setup flow that `ng add @angular/fire` no longer performs, and wiring the deploy target by hand from the samples below puts you on a deprecated path that warns on every deploy. For current guidance see [the Quickstart](../install-and-setup.md), step 6, and for server-side rendered apps see the [App Hosting guide](../app-hosting.md).
+
 In this guide, we'll look at how to use `@angular/fire` to automatically deploy an Angular application to Firebase hosting or functions by using the Angular CLI.
 
 `@angular/fire` uses Firebase functions to deploy your Angular universal projects, with server-side rendering enabled.

package/docs/firestore.md

@@ -14,13 +14,11 @@ Cloud Firestore is the API that gives your application access to your database i
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 Provide a Firestore instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideFirestore, getFirestore } from '@angular/fire/firestore';
 
@@ -71,6 +69,7 @@ In `user-profile.component.ts`:
 ```typescript
 import { Firestore, collection, collectionData} from '@angular/fire/firestore';
 import { Component, inject } from '@angular/core';
+import { Observable } from 'rxjs';
 
 @Component ({
     selector: 'app-user-profile',
@@ -89,7 +88,7 @@ export class UserProfileComponent {
         this.users$ = collectionData(userProfileCollection) as Observable<UserProfile[]>;
     }
 }
-export Interface UserProfile {
+export interface UserProfile {
     username: string;
 }
 ```
@@ -114,8 +113,9 @@ To write to Cloud Firestore use the `addDoc` function. It will create a new docu
 
 
 ```typescript
-import { Firestore, collection, collectionData, addDoc} from '@angular/fire/firestore';
+import { Firestore, collection, collectionData, addDoc, CollectionReference, DocumentReference } from '@angular/fire/firestore';
 import { Component, inject } from '@angular/core';
+import { Observable } from 'rxjs';
 
 @Component ({
     selector: 'app-user-profile',
@@ -137,7 +137,7 @@ export class UserProfileComponent {
         });
     }
 }
-export Interface UserProfile {
+export interface UserProfile {
     username: string;
 }
 ```

package/docs/functions.md

@@ -12,14 +12,12 @@ The Cloud Functions for Firebase client SDKs let you call functions directly fro
 
 ## Dependency Injection
 
-As a prerequisite, ensure that `AngularFire` has been added to your project via
-```bash
-ng add @angular/fire
-```
+As a prerequisite, ensure that `AngularFire` has been added to your project as described in the [Quickstart](./install-and-setup.md).
 
 Provide a Cloud Functions instance in the application's `app.config.ts`:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
 import { provideFunctions, getFunctions } from '@angular/fire/functions';
 
@@ -30,7 +28,7 @@ export const appConfig: ApplicationConfig = {
     ...
   ],
   ...
-})
+}
 ```
 
 Next inject `Functions` into your component: