Migrating to v6

Migrate to React Native Firebase v6

Introduction

This is a reference for upgrading from React Native Firebase v5.x.x to v6.x.x. Even though there is a lot to cover, each module generally follows similar steps to migrate.

We highly recommend your project is using React Native 0.60+ before upgrading to take advantage of new features to make the migration process much simpler.

We highly recommend backing up your project before migrating!

If you're looking to start fresh, check out the Getting Started section of the documentation.

Why you should migrate

React Native Firebase version 6 has been re-created from the ground up, with a heavy focus on testing, documentation & feature compatibility with the Firebase SDKs. We've also been working closely with the Firebase team to ensure all module APIs have been approved before being released.

We have also ensured the release is compatible with some of the popular tooling in the React Native community, such as autolinking & TypeScript.

Version 6 also brings support for previously unsupported modules such as Firebase ML.

NPM dependency changes

Prior to version 6, all modules are installable from the react-native-firebase NPM package. With version 6 we are now taking advantage of NPM organizations, allowing us to distribute each module as its own package. This has a number of advantages such as smaller app bundle sizes (you only install what modules you need), and internally we treat each module as its own package, allowing for easier testing and quality assurance. Every project must install the @react-native-firebase/app module, replacing the react-native-firebase module.

Removing react-native-firebase

There are a number of steps to carry out to remove the react-native-firebase module from your existing app. To help make this process easier, we'll break out the process into 3 sections:

• Removing v5 from JavaScript
• Removing v5 from Android
• Removing v5 from iOS

Removing v5 from JavaScript

As mentioned above, we need to remove the react-native-firebase NPM module from our project. To do this, open your projects package.json file and remove the dependency:

{
  "dependencies": {
    "react": "16.8.3",
    "react-native": "0.59.9",
-   "react-native-firebase": "^5.5.4"
  }
}

To remove the package from your local environment, delete the yarn.lock/package-lock.json files and reinstall the project dependencies with yarn.

Removing v5 from Android

Removing version 5 from your native Android code is a more involved process. We'll go file by file to ensure all references to the older version have been removed.

Removing from Gradle Settings

Open up your projects /android/settings.gradle file. There will be 2 lines which need to be removed:

rootProject.name = 'AwesomeApp'
- include ':react-native-firebase'
- project(':react-native-firebase').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-firebase/android')

include ':app'

Removing from Android Manifest

Open your AndroidManifest.xml file. You will need to remove any references to the io.invertase.firebase.messaging class

- <service android:name="io.invertase.firebase.messaging.RNFirebaseMessagingService">
-   <intent-filter>
-     <action android:name="com.google.firebase.MESSAGING_EVENT" />
-   </intent-filter>
- </service>

Removing native dependencies

We now need to remove the RNFirebase and Firebase dependencies from your project. In version 6, these are automatically installed for us.

Open your projects /android/app/build.gradle file. First remove the react-native-firebase dependency:

dependencies {
-   implementation project(path: ':react-native-firebase')
}

Next, remove the firebase-core and play-services-base dependencies. Note, other modules you are using may required play-services-base to be installed.

Specific versions listed may be different than your own project

dependencies {
-   implementation "com.google.firebase:firebase-core:16.0.9"
-   implementation "com.google.android.gms:play-services-base:16.1.0"
}

Next we need to remove the module specific Firebase dependencies. The naming convention for these modules is: implementation "com.google.firebase:firebase-<< module >>:<<version>>".

For example, to remove the native Firebase dependency for the Authentication module:

dependencies {
-   implementation "com.google.firebase:firebase-auth:17.0.0"
}

Removing the React Native Firebase packages

We now need to remove the React Native Firebase packages from being added to our React Native application. Go ahead and open the /android/app/src/main/java/<< app name >>/MainApplication.java file.

First, we need to remove the core RNFirebasePackage from the imports and being added to the package list:

-   import io.invertase.firebase.RNFirebasePackage;

    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
-       new RNFirebasePackage(),

Depending on what modules you installed using version 5, remove the packages for each module. For example, to remove the Authentication package:

-   import io.invertase.firebase.auth.RNFirebaseAuthPackage;

    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
-       new RNFirebaseAuthPackage(),

Cleaning Gradle

Android caches module dependencies for quicker builds. As we've heavily modified our project dependencies it's recommended you clean Gradle, allowing for a fresh installation. In your project, execute the following commands:

$ cd android/
$ ./gradlew clean

Removing v5 from iOS

The following steps assume you have used CocoaPods to manage your projects iOS dependencies.

Remove the RNFirebase Pod

Remove the RNFirebase pod from your /ios/Podfile:

target 'AwesomeApp' do
-   pod 'RNFirebase', :path => '../node_modules/react-native-firebase/ios'

Remove the Firebase Core Pod

The Firebase/Core need to be removed from the project. In version 6, this is automatically installed. Open the /ios/Podfile and remove the Pod:

target 'AwesomeApp' do
-   pod 'Firebase/Core', '~> 6.3.0'

Remove module specific Pods

Depending on what modules you were using with version 5, we now need to remove the Firebase Pods. For example, if you are using the Authentication module, remove the Firebase/Auth Pod:

target 'AwesomeApp' do
-   pod 'Firebase/Auth', '~> 6.3.0'

Re-installing Pods

Once the Pod dependencies have been removed, the following commands will remove the Pods from your local project:

$ cd ios
$ rm -rf Podfile.lock
$ pod install

Installing @react-native-firebase/app

As mentioned earlier, version 6 uses the @react-native-firebase NPM organization for each module. Every app using version 6 must install the app module before installing each specific module.

To get started, install the new dependency with Yarn:

yarn add @react-native-firebase/app

If you are using React Native 0.60+, the module will be automatically linked via autolinking.

Users on an older version of React Native must manually link the app module. See the following steps for Android and iOS for more information on manual linking.

Specific module installation

Depending on which Firebase service your app uses, you now need to install the NPM packages for each service. For example, apps using the Authentication module need to install the auth package:

yarn add @react-native-firebase/auth

Install the modules required for your application:

Users on React Native version 0.60+, the modules will be automatically linked. For users on a lower version, see the module specific pages for manual installation guides.

Updating project code

In versions prior to 6, accessing the React Native Firebase package was carried out by importing the react-native-firebase module, for example:

import firebase from 'react-native-firebase';

// App code...
const user = firebase.auth().currentUser;

Although it is possible to access specific module functionality from the package imports, if you're coming from v5 the following usage may seem daunting for a large project:

import auth from '@react-native-firebase/auth';

// App code...
const user = auth().currentUser;

Fortunately, it is possible to continue to migrate to the previous versions import method:

Find and replace all usages of the import with the new import:

- import firebase from 'react-native-firebase';
+ import firebase from '@react-native-firebase/app';

We now need to import additional packages inside of an entry point file of our project, for example to import the Authentication module, add the following to your projects /App.js file (or entry file):

import firebase from '@react-native-firebase/app';
import '@react-native-firebase/auth';

// App code
const user = firebase.auth().currentUser;

This only needs to be done once. The auth module will now be available on all firebase instances.

Module Breaking Changes

Below outlines a list of breaking changes for each module which may impact your application. Please ensure all app functionality is tested once migrated to version 6 is complete.

App

@react-native-firebase/app

• onReady() removed: Users initializing a secondary app via app.initializeApp will need to now remove the onReady listener. Instead, initializeApp resolves a promise once the secondary app has finished initializing.
• Initializing the [DEFAULT] app manually will now throw an error. Previously this only displayed a warning.

AdMob

@react-native-firebase/admob

The AdMob module has undergone a full re-write to support a new, cleaner API and regulation changes (such as GDPR). Please see the

• RewardedVideo has now been deprecated in favor of a new native API. Please see RewardedAd for more information.

Invites

The invites module has now been deprecated. Please see the official Firebase documentation for more information.

The recommended approach for handling this deprecation is to use the Dynamic Links module.

Analytics

@react-native-firebase/analytics

• All methods now return a Promise. Previously these were 'fire and forget'.

Crashlytics

@react-native-firebase/crashlytics

• setBoolValue, setFloatValue, setIntValue & setStringValue have been removed and replaced with two new methods (the Crashlytics SDK converted all these into strings internally anyway):
  • setAttribute(key: string, value: string): Promise<null> - set a singular key value to show alongside any subsequent crash reports
  • setAttributes(values: { [key: string]: string }): Promise<null> - set multiple key values to show alongside any subsequent crash reports
• All methods except crash, log & recordError now return a Promise that resolve when complete.
• recordError now accepts a JavaScript Error instead of a code and message.
• setUserIdentifier() has been renamed to setUserId() to match the Analytics Web SDK implementation.
• enableCrashlyticsCollection() has been renamed to setCrashlyticsCollectionEnabled().

Firestore

@react-native-firebase/firestore

• The Blob class can no longer be manually constructed.
• All user code is now validated in JavaScript. Passing incorrect data or querying chaining will now throw a JavaScript error. Ensure all queries are thoroughly tested.
  • The Query class has undergone a rewrite. Previously some invalid queries could be passed to the native SDKs causing a crash, these are now validated in JavaScript.
• The where equal operator = has been deprecated. Please use ==.
• The setting setTimestampsInSnapshotsEnabled has been deprecated.

Dynamic Links

@react-native-firebase/dynamic-links

• Module usage has been renamed from links() to dynamicLinks().
• The onLink and getInitialLink methods now return a DynamicLink object, rather than the string URL.
• The builder syntax has been deprecated in favor of simple objects. See buildLink() documentation for an example.
• Added extra validation. Building a dynamic link with platform specific options will now error if not all required parameters are set.

Functions

@react-native-firebase/functions

No breaking changes.

In-App Messaging

@react-native-firebase/in-app-messaging

This is a new module. See documentation for usage.

Instance ID

@react-native-firebase/iid

No breaking changes.

Notifications

Device-local notification APIs are not actually Firebase APIs at the same time they are very difficult to maintain.

For these reasons the notifications package has been removed from react-native-firebase for versions 6 and higher.

How to migrate: If you use device-local notification APIs and user-visible notifications in your app you will want to integrate a separate library that gives you access to device-local notification APIs. Many people have reported success with each of https://notifee.app, https://wix.github.io/react-native-notifications and https://github.com/zo0r/react-native-push-notification

Cloud Messaging

@react-native-firebase/messaging

• [android] The manually added RNFirebaseMessagingService service in your AndroidManifest.xml file is no longer required - you can safely remove it.
• [iOS] The manually added RNFirebaseMessaging usages in your AppDelegate files are no longer required - you can safely remove them.
• The builder syntax has been deprecated in favor of simple objects. See newRemoteMessage() documentation for an example.
• subscribeToTopic('some-topic') method must not include "/" in topic.
• [iOS] The minimum supported iOS version is now 10
• iOS 9 or lower only accounts for 0.% of all iPhone devices.
• To see a detailed device versions breakdown see this link.
• Community contributions that add iOS 9 support are welcome.

Performance Monitoring

@react-native-firebase/perf

• All Trace & HttpMetric methods (except for start & stop) are now synchronous and no longer return a Promise, extra attributes/metrics now only get sent to native when you call stop.
• firebase.perf.Trace.incrementMetric will now create a metric if it could not be found.
• firebase.perf.Trace.getMetric will now return 0 if a metric could not be found.

Realtime Database

@react-native-firebase/database

• The Reference class has undergone a rewrite. In previous versions, chaining invalid methods together on a query was possible. In version 6, the functionality now replicates the Firebase Web SDK.
  • Please thoroughly test your database queries.
• Internal JavaScript validation has been added and will throw a JavaScript error if methods are called with incorrect parameters.
• All query based modifiers are now validated as per the Web SDK spec. In v5 it is possible to chain queries which are not allowed together causing native errors (e.g. .orderByKey().orderByPriority(), .startAt('foo', 'bar').orderByKey() etc). Doing so in v6 will now throw an error to keep it in-line with the Web SDK.
• Reference.push now correctly mimics the Web SDK, returning a thenable reference.

Remote Config

@react-native-firebase/remote-config

• Module namespace has been renamed to .remoteConfig() from .config().
• All Remote Config values can now be accessed synchronously in JS, see getValue(key: string): ConfigValue & getAll(): ConfigValues below.
  • These replace all the original async methods: getValue, getValues, getKeysByPrefix.
• setDefaultsFromResource now returns a Promise that resolves when completed, this will reject with code config/resouce_not_found if the file could not be found.
• setDefaultsFromResource now expects a resource file name for Android to match iOS, formerly this required a resource id (something you would not have in RN as this was generated at build time by Android).
  • An example for both platforms can be found in the tests.
• enableDeveloperMode has been removed, you can now use setConfigSettings({ isDeveloperModeEnabled: boolean }) instead.
• setDefaults now returns a Promise that resolves when completed.

Cloud Storage

@react-native-firebase/storage

• Removed formerly deprecated UploadTaskSnapshot.downloadUrl property, use StorageReference.getDownloadURL(): Promise<string> instead.
• StorageReference.downloadFile() is now deprecated and will be removed in a later release, please rename usages of this to writeToFile() - renamed to match Native SDKs.
• firebase.storage.Native has moved to firebase.utils.Native.
• firebase.utils.Native is now deprecated and will be removed in a later release, please rename usages of this to firebase.utils.FilePath.
• firebase.utils.Native.* some properties have been renamed and deprecated and will be removed in a later release, follow the in-app console warnings on how to migrate.

ML

@react-native-firebase/ml

This is a new module. See documentation for usage.