Skip to content

version-21-upgrade.md

Latest commit

 

History

History
83 lines (53 loc) · 6.4 KB

version-21-upgrade.md

File metadata and controls

83 lines (53 loc) · 6.4 KB
Raw

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

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.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

ng update @angular/fire 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 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.

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.