# 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

From an app on Angular 20 and AngularFire 20, run:

```bash
ng update @angular/core@21 @angular/cli@21 @angular/fire
```

The AngularFire update runs a migration that:

- **Aligns your `firebase` dependency to `^12.18.0`.** AngularFire 21 requires Firebase JS SDK 12, at 12.18 or later. If your app requested an older `firebase`, whether that is 11 or an earlier 12, npm would install both that copy and the one AngularFire needs 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 AgentPlatformBackend(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 the Agent Platform Gemini API (formerly Vertex AI). The equivalent of `getVertexAI()` is `getAI(app, { backend: new AgentPlatformBackend() })`, which is what the migration writes, so your app keeps calling the backend it was configured, enabled, and billed for. A `location` option moves into the `AgentPlatformBackend` constructor.

### The default region changes

`getVertexAI()` with no `location` resolved to `us-central1`. `AgentPlatformBackend` with no argument resolves to `global`. Firebase suggests `global` when your model supports it, and the Gemini 3.x models are only available there, which is why the migration writes it. To keep the region you had instead, write `new AgentPlatformBackend('us-central1')`.

Review this before deploying if your project has a data residency requirement.

#### Which calls move, and what the migration tells you

- A call that passed a non-empty `location` string keeps it, so its region does not move.
- A call that passed no `location`, or an empty one, moves to `global`. `getVertexAI` treated an empty value as `us-central1`, and `AgentPlatformBackend` treats it as `global`. The migration drops the empty value rather than writing it through, and warns.
- A call whose `location` is an expression the migration cannot read gets its own warning, because only your runtime knows whether that value is empty.
- A call whose options the migration cannot rewrite at all, such as a quoted `{ 'location': ... }` key, is left as written and warned about separately. Its import still moves, so it stops compiling until you migrate it by hand.

Each of those warnings is emitted once per file, so a file that has both a moved region and an unreadable `location` produces two.

#### If your app uses the Live API, do not stay on `global`

Firebase does not support the `global` location for the Live API models, so `getLiveGenerativeModel` and `startAudioConversation` stop working there. When the migration sees either of them anywhere in your workspace it says so in the region warning. Pass `'us-central1'`, or another supported location, to `AgentPlatformBackend`.

### What the migration rewrites for you

The AngularFire update rewrites these imports and identifiers for you and logs every `getVertexAI` call it rewrites. `getGenerativeModel` keeps its name.

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.

### What the migration will not rewrite

Code the migration cannot rewrite safely 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. Nothing changes backends silently. It plays safe like this in four situations:

- **Options it cannot read:** when the `getVertexAI` call's options are not a literal `{ location }` object, or that literal references other symbols the migration is also rewriting.
- **The function used as a value:** when `getVertexAI` is stored or passed around rather than called directly.
- **Name collisions:** when a local declaration in the file reuses an imported symbol's name, or the file already gets `getAI` or `AgentPlatformBackend` from a source other than AI Logic.
- **Wildcard re-exports:** when a file has `export * from '@angular/fire/vertexai'`, that line stays as written, because rewriting it would silently rename your re-exported public symbols. Replace it with named re-exports by hand.

A file where a named `getVertexAI` import is used in a way 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.

### Removed symbols

Two symbols were removed rather than renamed. The migration leaves their imports in place, which breaks loudly, and warns with guidance:

- `VertexAIOptions`: the new `AIOptions` takes a `backend` instead of a `location`, so rebuild the options by hand using the table above.
- `getImagenModel`: Firebase shut the Imagen models down in August 2026 and removed the API in firebase 12.18 (`@firebase/ai` 2.15), so move image generation to the Gemini image models through [`getGenerativeModel`](https://firebase.google.com/docs/ai-logic/generate-images-gemini).
  - The same release removed every other `Imagen*` export too, such as `ImagenModel`, `ImagenAspectRatio` and `ImagenGenerationConfig`.
  - The migration does not warn about those. It warns about `getImagenModel` only in files that imported an old Vertex AI entry point, so check imports from `@angular/fire/ai` and `firebase/ai` by hand.

## Other notes

- **Angular 21.2 is required.** AngularFire 21 peers `@angular/* ^21.2.0` and does not support Angular 22 (a future AngularFire 22 will).
- The obsolete `@angular/platform-browser-dynamic` and the unused optional `@angular/platform-server` peer dependencies were removed. No action is needed.
- **App Check no longer runs during server rendering** (since 21.0.0-rc.2). `inject(AppCheck)` returns `null` on the server. To keep it running there, provide `APP_CHECK_ON_SERVER` as `true` in your server config. See [App Check during server rendering](./app-check.md#server-side-rendering).
- **`ng update` can stop with `The Angular CLI requires a minimum Node.js version of ...`.** This happens when the first `@angular/` package in the command has no version number: `ng update` then runs with the newest Angular CLI, which requires a newer Node.js than Angular 21 does. Either update Node.js, or give that package a version number, as the command above does. Updating AngularFire on its own needs the version too: run `ng update @angular/fire@21`, not `ng update @angular/fire`.