Merge origin/main into fix/ng-add-empty-features-warning

Resolve the src/schematics/setup/index.ts import conflict: keep main's
new firebaseConfigs import and add featuresPromptMessage to the prompts
import. No logic change from either side.

Author: armando-navarro

.github/workflows/test.yml

@@ -168,7 +168,7 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
+          registry-url: 'https://wombat-dressing-room.appspot.com/'
           check-latest: false
       - name: 'Download Artifacts'
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

README.md

@@ -66,12 +66,16 @@ export class AppComponent {
 
 [Quickstart](docs/install-and-setup.md) - Get your first application up and running by following our quickstart guide.
 
+[Deploying SSR to App Hosting](docs/app-hosting.md) - Deploy a server-rendered app to Firebase App Hosting, and avoid the silent SSR-to-CSR fallback.
+
 [Contributing](CONTRIBUTING.md)
 
 [Stackblitz Template](https://stackblitz.com/edit/angular-fire-start) - Remember to set your Firebase configuration in `app/app.module.ts`.
 
 [Upgrading from v6.0? Check out our guide.](docs/version-7-upgrade.md)
 
+[Upgrading from AngularFire 20? See the v21 upgrade guide.](docs/version-21-upgrade.md)
+
 ### Sample app
 
 The [`sample`](sample) folder contains a kitchen sink application that demonstrates use of the "modular" API, in a zoneless server-rendered application, with all the bells and whistles.
@@ -142,43 +146,49 @@ import { } from '@angular/fire/storage';
   <tr>
     <td>
 
+#### [Data Connect](docs/data-connect.md#data-connect)
+```ts
+import { } from '@angular/fire/data-connect';
+```
+</td>
+    <td>
+
 #### [Performance Monitoring](docs/performance.md#performance-monitoring)
 ```ts
 import { } from '@angular/fire/performance';
 ```
 </td>
+  </tr>
+  <tr>
     <td>
 
 #### [Realtime Database](docs/database.md#realtime-database)
 ```ts
 import { } from '@angular/fire/database';
 ```
 </td>
-  </tr>
-  <tr>
     <td>
 
 #### [Remote Config](docs/remote-config.md#remote-config)
 ```ts
 import { } from '@angular/fire/remote-config';
 ```
 </td>
+  </tr>
+  <tr>
     <td>
 
 #### [App Check](docs/app-check.md#app-check)
 ```ts
 import { } from '@angular/fire/app-check';
 ```
 </td>
-  </tr>
-  <tr>
     <td>
 
-#### [Vertex AI](docs/vertexai.md#vertex-ai)
+#### [AI Logic](docs/ai.md#ai-logic)
 ```ts
-import { } from '@angular/fire/vertexai';
+import { } from '@angular/fire/ai';
 ```
 </td>
-
   </tr>
 </table>

docs/ai.md

@@ -0,0 +1,55 @@
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; AI Logic
+</small>
+
+# AI Logic
+
+Firebase AI Logic gives you access to the latest generative AI models from Google: the Gemini models and Imagen models.
+
+[Learn more](https://firebase.google.com/docs/ai-logic)
+
+> Firebase AI Logic was previously called **Vertex AI in Firebase**. If you are upgrading from AngularFire 20, the module moved from `@angular/fire/vertexai` to `@angular/fire/ai` and most symbols were renamed (`provideVertexAI` to `provideAI`, `VertexAI` to `AI`). One is not a rename: plain `getAI()` uses the Gemini Developer API backend, so the old `getVertexAI()` maps to `getAI(app, { backend: new VertexAIBackend() })`. Running `ng update @angular/fire` rewrites all of this for you and keeps your app on the Vertex AI backend. See the [AngularFire 20 to 21 upgrade guide](./version-21-upgrade.md).
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide an AI instance in the application's `app.config.ts`:
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { provideAI, getAI } from '@angular/fire/ai';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideFirebaseApp(() => initializeApp({ ... })),
+    provideAI(() => getAI()),
+    ...
+  ],
+  ...,
+}
+```
+
+Next inject `AI` into your component:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { AI } from '@angular/fire/ai';
+
+@Component({ ... })
+export class MyComponent {
+    private ai = inject(AI);
+    ...
+}
+```
+
+## 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/ai'` to `import { ... } from '@angular/fire/ai'` and follow the official documentation.
+
+[Getting Started](https://firebase.google.com/docs/ai-logic/get-started?platform=web) | [API Reference](https://firebase.google.com/docs/reference/js/ai)

docs/app-hosting.md

@@ -0,0 +1,95 @@
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Deploying SSR to Firebase App Hosting
+</small>
+
+# Deploying a server-rendered app to Firebase App Hosting
+
+[Firebase App Hosting](https://firebase.google.com/docs/app-hosting) is Firebase's recommended way to deploy a server-side-rendered (SSR) Angular application. It builds your app in Google Cloud Build, runs the Node server, and serves it behind Google's CDN and proxy. This applies to either way of deploying to App Hosting, a connected GitHub repository or `firebase deploy` from your own machine; both build the same way and are affected the same way.
+
+This guide covers one thing that trips up almost every new SSR deployment: **the server can silently stop server-rendering and fall back to client-side rendering (CSR), with no error anywhere obvious.** It explains how to detect that in 30 seconds and how to fix it.
+
+## How to deploy
+
+If you have not deployed yet, follow Firebase's own guides: [Get started with App Hosting](https://firebase.google.com/docs/app-hosting/get-started) to connect a GitHub repository (App Hosting builds and deploys on every push), or [Alternative ways to deploy](https://firebase.google.com/docs/app-hosting/alt-deploy) to deploy with `firebase deploy` from your own machine. Both build your app the same way in Google Cloud Build. The rest of this guide covers an Angular-specific issue you can hit once your app is deployed either way.
+
+## The symptom: SSR silently downgrades to CSR
+
+A freshly deployed Angular SSR app usually *looks* fine in a browser, the page renders and works. But the server may be sending an almost-empty HTML shell and letting the browser do all the rendering. When that happens you lose the whole point of SSR: crawlers and link previews see no content, and first paint on slow devices is worse.
+
+There is no error in the deploy output and no error in the browser. The only trace is in your backend's server logs, which nothing prompts you to check.
+
+App Hosting runs on Cloud Run, not Cloud Functions, so its logs live in Cloud Logging:
+
+- In the Firebase console, open your backend and go to its **Logs** tab, then look at **Runtime logs**.
+- From a terminal, use `gcloud`:
+
+  ```bash
+  gcloud logging read 'resource.type=cloud_run_revision AND resource.labels.service_name=YOUR_BACKEND_ID' --project YOUR_PROJECT_ID --limit 10
+  ```
+
+See Firebase's [View logs and metrics](https://firebase.google.com/docs/app-hosting/logging) guide for more.
+
+## The 30-second check to run after every deploy
+
+Pick an SSR route (not an SSG/prerendered one) and fetch it:
+
+```bash
+curl -s https://YOUR-SITE/ | grep ng-server-context
+```
+
+Angular's server renderer stamps a `ng-server-context` attribute on the app's root element:
+
+- `ng-server-context="ssr"` - the route was server-rendered (SSR). This is what you want.
+- `ng-server-context="ssg"` - the route was prerendered (SSG). Fine in itself, but not the SSR path this guide is about.
+- **No `ng-server-context` at all** - the server returned a client-only shell and the browser is doing all the rendering. This is the silent CSR fallback described above, regardless of how the page looks in a browser.
+
+## Why it happens
+
+Angular's server engine only trusts the `X-Forwarded-*` headers a proxy attaches to a request when it is told to. App Hosting's proxy adds several of these headers (for example `x-forwarded-for` and `x-forwarded-proto`). If Angular does not trust the full set the platform sends, it treats the request as untrusted and de-optimizes to CSR on every request.
+
+<!--
+  Maintainer note (2026-07-19): the two-step fix below is a workaround for a lag in
+  Firebase App Hosting's build image. The underlying fix (injecting the full
+  X-Forwarded-* set into NG_TRUST_PROXY_HEADERS) is already merged upstream in
+  GoogleCloudPlatform/buildpacks (commit 9346e60b, 2026-06-17) but had not reached
+  production builders as of 2026-07-19. Once it ships, `npm update` alone suffices
+  and the trustProxyHeaders step becomes optional; revisit and simplify this guide.
+-->
+
+## The Fix
+
+Two steps are needed together.
+
+**1. Update Angular to the latest patch:**
+
+```bash
+npm update @angular/core @angular/ssr
+```
+
+**2. Turn on proxy-header trust when you create the server engine.** In `src/server.ts`, pass `trustProxyHeaders: true` to `AngularNodeAppEngine`:
+
+```ts
+import { AngularNodeAppEngine } from '@angular/ssr/node';
+
+const angularApp = new AngularNodeAppEngine({
+  trustProxyHeaders: true,
+});
+```
+
+Redeploy, then run the 30-second check above. You should now see `ng-server-context="ssr"`.
+
+### Why both steps
+
+The two steps address different halves of the same handshake, and neither alone is enough:
+
+- Recent Angular patches let the `trustProxyHeaders` engine option take effect on App Hosting; on older patches a platform environment variable wins instead, so the code option is ignored. The `npm update` gets you onto a patch where the option is honored.
+- Even on the latest patch, you still have to *set* the option, so App Hosting's proxy headers are trusted.
+
+This matches Firebase's own guidance. For the current, authoritative version of this fix (including any App Hosting or Angular version notes), see Firebase's [App Hosting troubleshooting guide](https://firebase.google.com/docs/app-hosting/troubleshooting#angular-proxy-trust).
+
+> Note: App Hosting also has an experimental, opt-in local-build deploy option (you build on your own machine, then `firebase deploy`) in which the Firebase CLI applies this proxy-header configuration for you. It is off by default and not a documented, supported workflow, so this guide targets the standard source deploy; apply the fix above.
+
+## Related Angular documentation
+
+- [Angular SSR guide](https://angular.dev/guide/ssr)
+- [Configuring trusted proxy headers](https://angular.dev/best-practices/security#configuring-trusted-proxy-headers)

docs/data-connect.md

@@ -0,0 +1,59 @@
+<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 via
+```bash
+ng add @angular/fire
+```
+
+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)

docs/version-21-upgrade.md

@@ -0,0 +1,42 @@
+# Upgrading to AngularFire 21
+
+AngularFire 21 targets **Angular 21** and the **Firebase JS SDK v12**. Most of the upgrade is handled for you by `ng update`.
+
+## Run the update
+
+```bash
+ng update @angular/core @angular/cli    # move your app to Angular 21 first
+ng update @angular/fire                 # then AngularFire 21
+```
+
+`ng update @angular/fire` runs a migration that:
+
+- **Aligns your `firebase` dependency to `^12.4.0`.** AngularFire 21 requires Firebase JS SDK 12. If your app still requested `firebase` 11, npm would install both 11 and 12 side by side, and the two copies reject each other's objects at runtime. The migration updates the dependency and reinstalls so you end up with a single copy. Verify with `npm ls firebase`.
+- **Rewrites Vertex AI imports to AI Logic** (see below).
+
+## Vertex AI is now Firebase AI Logic
+
+The Vertex AI module has been renamed to Firebase AI Logic. The `@angular/fire/vertexai` entry point (and the older `@angular/fire/vertexai-preview`) are removed in favor of `@angular/fire/ai`:
+
+| Before (`@angular/fire/vertexai`) | After (`@angular/fire/ai`) |
+|---|---|
+| `getVertexAI(app?, { location? })` | `getAI(app, { backend: new VertexAIBackend(location?) })` |
+| `provideVertexAI` | `provideAI` |
+| `VertexAI` | `AI` |
+| `VertexAIError` | `AIError` |
+| `VertexAIErrorCode` | `AIErrorCode` |
+| `VertexAIModel` | `AIModel` |
+| `VertexAIInstances` | `AIInstances` |
+| `vertexAIInstance$` | `AIInstance$` |
+| `VertexAIModule` | `AIModule` |
+
+**`getVertexAI` is not a plain rename.** `getAI` already existed alongside it, and a plain `getAI()` call talks to the Gemini Developer API backend, not to Vertex AI. The equivalent of `getVertexAI()` is `getAI(app, { backend: new VertexAIBackend() })`, which is what the migration writes, so your app keeps calling the Vertex AI backend it was configured, enabled, and billed for. A `location` option moves into the `VertexAIBackend` constructor.
+
+`ng update @angular/fire` rewrites these imports and identifiers for you and logs every `getVertexAI` call it rewrites. Code it cannot rewrite safely (for example when the options are not a literal `{ location }` object or that literal references other rewritten symbols, when the function itself is handed around as a value, when a local declaration in the file reuses an imported symbol's name, or when the file already binds `getAI` or `VertexAIBackend` from a source other than AI Logic) is left in place with a warning. The import path itself still moves to the new entry point, so the leftover code fails to compile there, and nothing changes backends silently. A file where a named `getVertexAI` import has any use that cannot be rewritten keeps every use of its named `getVertexAI` imports in place (namespace-style `ns.getVertexAI(...)` calls are judged per call), and each skipped call is logged. `export * from '@angular/fire/vertexai'` is also left alone (rewriting it would silently rename your re-exported public symbols), so replace it with named re-exports by hand. `VertexAIOptions` was removed rather than renamed (the new `AIOptions` takes a `backend` instead of a `location`), so imports of it are left and warned about. Migrate those sites using the table above. `getGenerativeModel` and `getImagenModel` keep their names.
+
+Imports straight from the Firebase SDK (`firebase/vertexai`, gone in SDK 12) are rewritten to `firebase/ai` under the same rules. The rewrite parses your sources with the `typescript` package (an optional peer dependency of `@angular/fire`). Every Angular workspace already has it, but if the migration warns that it could not be resolved, install `typescript` and re-run. See [ai.md](./ai.md) for current usage.
+
+## Other notes
+
+- **Angular 21 is required.** AngularFire 21 peers `@angular/* ^21.0.0` and does not support Angular 22 (a future AngularFire 22 will).
+- The obsolete `@angular/platform-browser-dynamic` peer dependency was removed. No action is needed.