Migration Guide for AngularFire V5 + Firestore

AngularFire v5.0.0 was released in October 2017 and was a complete rewrite of the realtime database API (with breaking changes). Simultaneously, Firebase released the new Firestore Database, which has many awesome advantages over the realtime DB.

The goal of this page is to show you how to use past lessons and videos with the new API and/or upgrade to the Firestore database.

Not sure which version you’re using?

Look inside the package.json file in the root of your Angular app. Under dependencies, you should see "angularfire2": "^X.X.X".

My Plan

I have produced a large library of content that covers specialized features with AngularFire. It would be nearly impossible to go back and refactor all written and video content. Instead, I am going to provide new revised lessons over the next couple months that take advantage of Firestore and soon-to-be-released Angular 5. I will create brand new content for the most popular concepts, such as infinite scroll, autocomplete search, and many more.

The underlying design patterns in past lessons are still valid, but will require some modification to the source code. The guide exists so you can still take advantage of these lessons with the new API and Firestore database.

Any lesson that uses AngularFire v4 will have a notice that looks like this at the top of the page with a link to this migration guide.

Upgrade Guide

I am offering up three different strategies for upgrading your app to AngularFire version 5.

Option 1: The Simple Fix - Use the old API

Past lessons using AngularFire2 v4 will not work in the latest version. Fortunately, the AngularFire team realized this issue and kept the old API available under a different namespace of database-deprecated. You can make your code work by simply updating your imports.

Any lesson that imports from angularfire2/database should be changed to angularfire2/database-deprecated.

You code should now look like this:

import {
  AngularFireDatabase,
  FirebaseObjectObservable,
  FirebaseListObservable
} from 'angularfire2/database-deprecated';

Option 2: Refactor Realtime DB Code to Version 5

Fully migrating to the new API is going to be a little more tedious. The main difference in v5 is the decoupling of the Observable from its reference to firebase.

Let’s compare the APIs.

/// *** Version 4 ***

const item: FirebaseObjectObservable<Item[]> = db.object('items/someKey')
item.update(data)
item.remove()

item.subscribe(data => console.log(data) )

/// *** Version 5 ***

const item: AngularFireObject<Item> = db.object('items/someKey')
item.update(data)
item.remove()

// Notice how the Observable is separate from write options
const itemObservable: Observable<Item> = object.valueChanges()
itemObservable.subscribe(data => console.log(data) )

Here is the basic process you will need to follow to update from v4 to v5:

1. For database write operations (push, update, set, remove), you will need to convert every Firebase(List | Object)Observable into the new AngularFire(List | Object) reference.

2. To read data as an Observable you will need to call valueChanges() or snapshotChanges() on the reference created in the previous step.

Option 3 (recommended): Upgrade to Firestore

The RealtimeDB has its share of annoying limitations. Exhibit A: querying/filtering data is very difficult. Exhibit B: Nested data is impossible on large datasets, requiring you to denormalize at the global level. Lucky for you, Firestore addresses these issues head on so you’re in great shape if just starting a new app. That being said, I recommend using Firestore in the majority of situations.

If you have questions about data structuring, let’s chat about it. Here’s your Slack invite link.

Firestore allows you to nest collections inside of documents without loading all the data into memory. This allows you to structure your database like so:

Here’s how the API differs from the lessons that use the Realtime DB.

/// *** Version 4 ***

const item: FirebaseObjectObservable<Item[]> = db.object('items/someKey')
item.update(data)
item.remove()

item.subscribe(data => console.log(data) )

/// *** Version 5 Firestore ***

const doc: AngularFirestoreDocument<Item> = afs.doc('items/someDocID')
doc.update(data)
doc.delete()

// Notice how the Observable is separate from write options
const docData: Observable<Item> = doc.valueChanges()
docData.subscribe(data => console.log(data) )

The API for Firestore is very similar to the realtime DB, but lists are called collections and objects are called documents. Learning Firestore is not very difficult if you already have experience with Firebase. If you want to learn more, checkout the Firestore Quick Start Tutorial.