Migration Guide

With the recent FlutterFire Roadmap announcement, we've changed the way developers integrate Flutter applications with Firebase. If you're currently using FlutterFire and wish to upgrade to the latest recommended versions, follow this guide to help ease that process.

If you're starting a fresh project, you can ignore this page and follow the Getting Started documentation.

The table below shows the recommended package versions for each plugin this migration guide covers.

PluginVersion
cloud_firestore^0.14.0+2
firebase_auth^0.18.0+1
firebase_core^0.5.0
firebase_crashlytics^0.2.0

Breaking Changes & Deprecations

Although breaking changes have been kept to a minimum, the substantial changes and improvements which have been made required us to break a few things (for the greater good). Where possible, we've deprecated some of the "old ways" of integrating FlutterFire and you should aim to replace these deprecations as soon as possible.

Migration Steps

1. Adding firebase_core

The FlutterFire plugins now depend on the firebase_core plugin. The plugin is responsible for connecting your Flutter application to your Firebase project(s), and without it all other plugins will not work.

Add the plugin to your pubspec.yaml file within your project:

pubspec.yaml
dependencies:
flutter:
sdk: flutter
firebase_core: "^0.5.0"

2. Update Firebase Plugins

Update the Firebase plugins you use in your project to versions that are compatible with the new firebase_core plugin.

Edit the plugin versions in your pubspec.yaml file within your project to match the versions below:

pubspec.yaml
dependencies:
flutter:
sdk: flutter
firebase_core: "^0.5.0"
# Newly reworked plugins covered by this migration guide:
firebase_auth: "^0.18.0+1"
firebase_crashlytics: "^0.2.0"
cloud_firestore: "^0.14.0+2"
# Updated to work with new core only plugins (no new changes):
cloud_functions: "^0.6.0"
firebase_admob: "^0.10.0-dev.1"
firebase_analytics: "^6.0.0"
firebase_database: "^4.0.0"
firebase_dynamic_links: "^0.6.0"
firebase_in_app_messaging: "^0.2.0+1"
firebase_messaging: "^7.0.0"
firebase_performance: "^0.4.0"
firebase_remote_config: "^0.4.0"
firebase_storage: "^4.0.0"

Install the updated plugins by running the following command from the project root:

$ flutter pub get

We also recommend running flutter clean before continuing.

3. Platform Setup

Even though you may have already setup your platform to connect with Firebase, we recommend following the new documentation steps for each platform to ensure everything is up-to-date.

Previously, it was possible to use FlutterFire without a "default" Firebase application. This has now changed, and all platforms now require an underlying default Firebase app has been registered. The platform specific guides below show you how to set up a default Firebase application:

A. Android Installation

  • Ensure that the com.google.gms:google-services plugin is up-to-date.
    • Update the version by changing the classpath 'com.google.gms:google-services:4.3.3' line in your android/build.gradle file to use version 4.3.3 or higher.
  • Ensure your apps Gradle wrapper distribution version is v5 or higher, FlutterFire uses v5.6.2 for its examples.
    • Update the version by changing the distributionUrl value in your projects android/gradle/wrapper/gradle-wrapper.properties file.
      • e.g. setting to v5.6.2: distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.2-all.zip
  • Ensure that you're not manually importing any Firebase Android SDK dependencies in your android/app/build.gradle files dependencies { ... } section.
    • e.g. remove any lines similar to: implementation 'com.google.firebase:firebase-{PRODUCT}:{VERSION}
    • The reworked plugins now automatically manage the versions of the Firebase SDKs used internally so these are no longer required.
  • Crashlytics only: Remove the maven { url 'https://maven.fabric.io/public' } line from your projects android/build.gradle file.
  • Crashlytics only: Remove the classpath 'io.fabric.tools:gradle:1.31.2' line from your projects android/build.gradle file.
  • Crashlytics only: Remove the apply plugin: 'io.fabric' line from your projects android/app/build.gradle file.
  • Crashlytics only: Remove any dependencies referencing *com.crashlytics.sdk.android:crashlytics* line from your projects android/app/build.gradle file (inside the dependencies { .. } block).
  • Crashlytics only: Follow the new Android integration steps shown in the FlutterFire Crashlytics installation documentation.

B. iOS Installation

These steps can also apply to macOS.

  • If you manually import Firebase and configure it via [FIRApp configure]; or FirebaseApp.configure() within your projects ios/{projectName}/AppDelegate{.m/.swift} file, you can now safely remove it - FlutterFire automatically handles this for you.
  • Crashlytics only: Open your ios/Runner.xcworkspace workspace file with Xcode.
    1. From Xcode select Runner from the left hand side project navigation.
    2. Select the Build Phases tab in the middle pane.
    3. Find a script in the list of Build Phases that contains ${PODS_ROOT}/Fabric/run as the shell script. Once located, press the x on the right of the row to remove that script. If you can't find one then you can ignore this step.
  • Crashlytics only: Follow the new iOS integration steps shown in the FlutterFire Crashlytics installation documentation.
  • If you face CocoaPods issues when building, follow the steps below in the CocoaPods could not find compatible versions for pod section.

C. Web Installation

4. Initialize FlutterFire

To ensure each plugin has a consistent API and to enable the possibility of some new features, you are now required to initialize FlutterFire before performing any other Firebase related functionality.

The firebase_core package exposes a Firebase class, provides an initializeApp method. This method should be called as soon as possible in your application. It is responsible for ensuring the default app is ready, and bootstraps all additional FlutterFire plugins which are installed.

To learn more, view the Initializing FlutterFire documentation.

Plugin Usage

Each plugin now provides a consistent API for integrating with Firebase. The example below shows how the cloud_firestore package previously created a new instance vs the new way:

// Before
Firestore firestore = Firestore();
// After
FirebaseFirestore firestore = FirebaseFirestore.instance;

If you'd like to a plugin with a secondary Firebase application, use the instanceFor method instead:

FirebaseApp secondaryApp = Firebase.app('SecondaryApp');
// Before
Firestore firestore = Firestore(app: secondaryApp);
// After
FirebaseFirestore firestore = FirebaseFirestore.instanceFor(app: secondaryApp);

To learn more about secondary Firebase app instances, view the Initializing secondary apps documentation.

Plugin Changes

Core

  • DEPRECATED: FirebaseApp.configure method is now deprecated in favor of the Firebase.initializeApp method.

  • DEPRECATED: FirebaseApp.allApps method is now deprecated in favor of the Firebase.apps property.

    • Previously, allApps was asynchronous & is now synchronous.
  • DEPRECATED: FirebaseApp.appNamed method is now deprecated in favor of the Firebase.app method.

  • BREAKING: FirebaseApp.options getter is now synchronous.

  • FirebaseOptions has been reworked to better match web property names:

    • DEPRECATED: googleAppID is now deprecated in favor of appId.
    • DEPRECATED: projectID is now deprecated in favor of projectId.
    • DEPRECATED: bundleID is now deprecated in favor of bundleId.
    • DEPRECATED: clientID is now deprecated in favor of androidClientId.
    • DEPRECATED: trackingID is now deprecated in favor of trackingId.
    • DEPRECATED: gcmSenderID is now deprecated in favor of messagingSenderId.
    • Added support for authDomain.
    • Added support for trackingId.
    • Required properties are now apiKey, appId, messagingSenderId & projectId.
  • Added support for deleting Firebase app instances via the delete method on FirebaseApp.

  • iOS: The default Firebase app is now automatically configured without needing to manually add Objective-C code to your iOS application.

  • Added support for returning consistent error messages from firebase-dart plugin.

    • Any FlutterFire related errors now throw a FirebaseException.
  • Added a FirebaseException class to handle all FlutterFire related errors.

    • Matching the web sdk, the exception returns a formatted "[plugin/code] message" message when thrown.
  • Added support for setAutomaticDataCollectionEnabled & isAutomaticDataCollectionEnabled on a FirebaseApp instance.

  • Added support for setAutomaticResourceManagementEnabled on a FirebaseApp instance.

  • Android: Gradle build tools updated to 3.5.0 from 3.3.0.

  • Android: Removed Gradle ‘hacks’ and upgrade Flutter SDK requirement from >=1.12.13+hotfix.4 to >=1.12.13+hotfix.5 - based on PR https://github.com/flutter/plugins/pull/2651

  • Android: Switched to using Firebase BoM to manage SDK versions

Crashlytics

  • BREAKING: Removal of Fabric SDKs and migration to the new Firebase Crashlytics SDK.
  • BREAKING: The following methods have been removed as they are no longer available on the Firebase Crashlytics SDK:
    • setUserEmail
    • setUserName
    • getVersion
    • isDebuggable
  • BREAKING: log now returns a Future. Calling log now sends logs immediately to the underlying Crashlytics SDK instead of pooling them in Dart.
  • BREAKING: the methods setInt, setDouble, setString and setBool have been replaced by setCustomKey.
    • setCustomKey returns a Future. Calling setCustomKey now sends custom keys immediately to the underlying Crashlytics SDK instead of pooling them in Dart.
  • DEPRECATED: enableInDevMode has been deprecated, use isCrashlyticsCollectionEnabled and setCrashlyticsCollectionEnabled instead.
  • DEPRECATED: Crashlytics has been deprecated, use FirebaseCrashlytics instead.
  • NEW: Custom keys that are automatically added by FlutterFire when calling reportError are now prefixed with flutter_error_.
  • NEW: Calling .crash() on Android & iOS/macOS now reports a custom named exception to the Firebase Console. This allows you to easily locate test crashes.
    • Name: FirebaseCrashlyticsTestCrash.
    • Message: This is a test crash caused by calling .crash() in Dart..
  • NEW: recordError now uses a named native exception when reporting to the Firebase Console. This allows you to easily locate errors originating from Flutter.
    • Name: FlutterError.
  • NEW: Added support for checkForUnsentReports.
    • Checks a device for any fatal or non-fatal crash reports that haven't yet been sent to Crashlytics.
    • See reference API docs for more information.
  • NEW: Added support for deleteUnsentReports.
    • If automatic data collection is disabled, this method queues up all the reports on a device for deletion.
    • See reference API docs for more information.
  • NEW: Added support for didCrashOnPreviousExecution.
    • Checks whether the app crashed on its previous run.
    • See reference API docs for more information.
  • NEW: Added support for sendUnsentReports.
    • If automatic data collection is disabled, this method queues up all the reports on a device to send to Crashlytics.
    • See reference API docs for more information.
  • NEW: Added support for setCrashlyticsCollectionEnabled.
    • Enables/disables automatic data collection by Crashlytics.
    • See reference API docs for more information.
  • NEW: Added support for isCrashlyticsCollectionEnabled.
    • Whether the current Crashlytics instance is collecting reports. If false, then no crash reporting data is sent to Firebase.
    • See reference API docs for more information.
  • FIX: Fixed a bug that prevented keys from being set on iOS devices.

Firestore

Along with the below changes, the plugin has undergone a quality of life update to better support exceptions thrown. Any Firestore specific errors now return a FirebaseException (see Core changes), allowing you to directly access the code (e.g. permission-denied) and message.

  • FirebaseFirestore:

    • BREAKING: Calling settings() now accepts a Settings instance.
    • DEPRECATED: Calling document() is deprecated in favor of doc().
    • DEPRECATED: Calling Firestore(app: app) is now deprecated. Use FirebaseFirestore.instance or FirebaseFirestore.instanceFor instead.
    • BREAKING: enablePersistence has now been removed, see settings() instead.
    • NEW: Add clearPersistence() support.
    • NEW: Add disableNetwork() support.
    • NEW: Add enableNetwork() support.
    • NEW: Add snapshotInSync() support.
    • NEW: Add terminate() support.
    • NEW: Add waitForPendingWrites() support.
  • CollectionReference:

    • BREAKING: Getting a collection parent document via parent() has been changed to a getter parent.
    • DEPRECATED: Calling document() is deprecated in favor of doc().
  • Query:

    • BREAKING: The internal query logic has been overhauled to better assert invalid queries locally.
    • BREAKING: getDocuments/get has been updated to accept an instance of GetOptions (see below).
    • DEPRECATED: Calling getDocuments() is deprecated in favor of get().
    • NEW: Query methods are now chainable.
    • NEW: It is now possible to call same-point cursor based queries without throwing (e.g. calling endAt() and then endBefore() will replace the "end" cursor query with the endBefore).
    • NEW: Added support for limitToLast.
  • QuerySnapshot:

    • DEPRECATED: documents has been deprecated in favor of docs.
    • DEPRECATED: documentChanges has been deprecated in favor of docChanges.
    • NEW: docs now returns a List<QueryDocumentSnapshot> vs List<DocumentSnapshot>. This doesn't break existing functionality.
  • DocumentReference:

    • BREAKING: setData/set has been updated to accept an instance of SetOptions (see below, supports mergeFields).
    • BREAKING: get() has been updated to accept an instance of GetOptions (see below).
    • BREAKING: Getting a document parent collection via parent() has been changed to a getter parent.
    • DEPRECATED: documentID has been deprecated in favor of id.
    • DEPRECATED: setData() has been deprecated in favor of set().
    • DEPRECATED: updateData() has been deprecated in favor of update().
  • DocumentSnapshot:

    • BREAKING: Getting a snapshots data via the data getter is now done via the data() method.
    • DEPRECATED: documentID has been deprecated in favor of id.
    • NEW: Added support for fetching nested snapshot data via the get() method. If no data exists at the given path, a StateError will be thrown.
  • DocumentChange:

    • DEPRECATED: Calling document() is deprecated in favor of doc().
  • WriteBatch:

    • BREAKING: setData/set now supports SetOptions to merge data/fields (previously this accepted a Map).
    • DEPRECATED: setData() has been deprecated in favor of set().
    • DEPRECATED: updateData() has been deprecated in favor of update().
  • Transaction:

    • BREAKING: Transactions have been overhauled to address a number of issues:
      • Values returned from the transaction will now be returned from the Future. Previously, only primitive values (e.g. String) were supported. It is now possible to return values such as a DataSnapshot.
      • When manually throwing an exception, the context was lost and a generic PlatformException was thrown. You can now throw & catch on any exceptions.
      • The modify methods on a transaction (set, delete, update) were previously Futures. This has been updated to better reflect how transactions should behave - they are now synchronous and are executed atomically once the transaction handler block has finished executing.
  • FieldPath:

    • NEW: The constructor has now been made public to accept a List of String values. Previously field paths were accessible only via a dot-notated string path. This meant attempting to access a field in a document with a . in the name (e.g. foo.bar@gmail.com) was impossible.
  • GetOptions: New class created to support how data is fetched from Firestore (server, cache, serverAndCache).

  • SetOptions: New class created to both merge and mergeFields when setting data on documents.

  • GeoPoint:

    • BREAKING: Added latitude and longitude validation when constructing a new GeoPoint instance.

Authentication

Overall, Firebase Auth has been heavily reworked to bring it inline with the federated plugin setup along with adding new features, documentation and many more unit and end-to-end tests. The API has mainly been kept the same, however there are some breaking changes.

  • General:

    • BREAKING: The FirebaseUser class has been renamed to User.
    • BREAKING: The AuthResult class has been renamed to UserCredential.
    • NEW: The ActionCodeSettings class is now consumable on all supporting methods.
      • NEW: Added support for the dynamicLinkDomain property.
    • NEW: Added a new FirebaseAuthException class (extends FirebaseException).
      • All errors are now returned as a FirebaseAuthException, allowing you to access the code & message associated with the error.
      • In addition, it is now possible to access the email and credential properties on exceptions if they exist.
  • FirebaseAuth

    • BREAKING: Accessing the current user via currentUser() is now synchronous via the currentUser getter.
    • BREAKING: isSignInWithEmailLink() is now synchronous.
    • DEPRECATED: FirebaseAuth.fromApp() is now deprecated in favor of FirebaseAuth.instanceFor().
    • DEPRECATED: onAuthStateChanged has been deprecated in favor of authStateChanges().
    • NEW: Added support for idTokenChanges() stream listener.
    • NEW: Added support for userChanges() stream listener.
      • The purpose of this API is to allow users to subscribe to all user events without having to manually hydrate app state in cases where a manual reload was required (e.g. updateProfile()).
    • NEW: Added support for applyActionCode().
    • NEW: Added support for checkActionCode().
    • NEW: Added support for verifyPasswordResetCode().
    • NEW: Added support for accessing the current language code via the languageCode getter.
    • NEW: setLanguageCode() now supports providing a null value.
      • On web platforms, if null is provided the Firebase projects default language will be set.
      • On native platforms, if null is provided the device language will be used.
    • NEW: verifyPhoneNumber() exposes a autoRetrievedSmsCodeForTesting property.
      • This allows developers to test automatic SMS code resolution on Android devices during development.
    • NEW (iOS): appVerificationDisabledForTesting setting can now be set for iOS.
      • This allows developers to skip ReCaptcha verification when testing phone authentication.
    • NEW (iOS): userAccessGroup setting can now be set for iOS & MacOS.
      • This allows developers to share authentication states across multiple apps or extensions on iOS & MacOS. For more information see the Firebase iOS SDK documentation.
  • User

    • BREAKING: Removed the UpdateUserInfo class when using updateProfile in favor of named arguments.
    • NEW: Added support for getIdTokenResult().
    • NEW: Added support for verifyBeforeUpdateEmail().
    • FIX: Fixed several iOS crashes when the Firebase SDK returned nil property values.
    • FIX: Fixed an issue on Web & iOS where a user's email address would still show after unlinking the email/password provider.
  • UserCredential

    • NEW: Added support for accessing the user's AuthCredential via the credential property.
  • AuthProvider & AuthCredential

    • DEPRECATED: All sub-class (e.g. GoogleAuthProvider) getCredential() methods have been deprecated in favor of credential().
      • DEPRECATED: EmailAuthProvider.getCredentialWithLink() has been deprecated in favor of EmailAuthProvider.credentialWithLink().
    • NEW: Supporting providers can now assign scope and custom request parameters.
      • The scope and parameters will be used on web platforms when triggering a redirect or popup via signInWithPopup() or signInWithRedirect().

Common Upgrade Issues

CocoaPods could not find compatible versions for pod

This issue can happen when you upgrade your FlutterFire packages and attempt to build for iOS or MacOS, this is usually down to one of the following:

  • Your Podfile.lock version inside your iOS or MacOS directory is out of date and locked to older versions of the Firebase iOS SDKs whereas the newly upgraded FlutterFire packages might be using newer versions of these SDKs.
    • Solution: Delete the Podfile.lock file, ios/Podfile, run pod cache clean --all and try your build again. This file will get regenerated after the next pod install.
  • Your pod specs repo is out of date, meaning CocoaPods locally isn't aware of any potential newer versions of the Firebase iOS SDKs that have been recently published.
    • Solution: Run pod repo update in your terminal and try your build again.