# React Native Firebase A well-tested feature-rich modular Firebase implementation for React Native. Supports both iOS & Android platforms for all Firebase services. ## Docs ### React Native Firebase Source: https://rnfirebase.io/ ```mdx > React Native Firebase has begun to deprecate the namespaced API (i.e firebase-js-sdk `< v9` chaining API). React Native Firebase will be moving to the modular API (i.e. firebase-js-sdk `>= v9`) in the next major release. See [migration guide](/migrating-to-v22) for more information. React Native Firebase is the officially recommended collection of packages that brings React Native support for all Firebase services on both Android and iOS apps. React Native Firebase fully supports React Native apps built using [React Native CLI](https://reactnative.dev/docs/environment-setup?guide=native) or using [Expo](https://docs.expo.dev/). **Source:** [github.com/invertase/react-native-firebase](https://github.com/invertase/react-native-firebase) · **Packages:** [npmjs.com/org/react-native-firebase](https://www.npmjs.com/org/react-native-firebase) (`@react-native-firebase/app`, `@react-native-firebase/auth`, `@react-native-firebase/firestore`, and one package per Firebase service) ## React Native Firebase vs firebase-js-sdk Use **React Native Firebase** (this project) when your app runs on Android and/or iOS: it wraps the native Firebase Android and iOS SDKs directly, so you get capabilities the web SDK cannot provide on mobile, like native app analytics, background/killed-state push notifications, and native Crashlytics crash reports. Use the plain **[firebase-js-sdk](https://github.com/firebase/firebase-js-sdk)** when you're targeting web, React Native Web, or another JavaScript-only environment with no native module support. React Native Firebase already falls back to firebase-js-sdk on those platforms; see [Other / Web](#other--web) below. ## Prerequisites Before getting started, the documentation assumes you are able to create a project with React Native and that you have an active Firebase project. If you do not meet these prerequisites, follow the links below: - [React Native - Setting up the development environment](https://reactnative.dev/docs/environment-setup) - [Create a new Firebase project](https://console.firebase.google.com/) Additionally, current versions of firebase-ios-sdk have a minimum Xcode requirement of 26.2 and the Swift 6.2.3+ toolchain, which implies a minimum macOS version of 15 (Xcode 26.2 is supported on macOS 15). See Apple's [Upcoming SDK minimum requirements](https://developer.apple.com/news/?id=ueeok6yw) for details. ## Installation for Expo projects Integration with Expo is possible when using a [development build](https://docs.expo.dev/workflow/overview/#development-builds). You can configure the project via [config plugins](https://docs.expo.dev/config-plugins/introduction/) or manually configure the native projects yourself (the "bare workflow"). _NOTE:_ React Native Firebase cannot be used in the pre-compiled [Expo Go app](https://docs.expo.dev/workflow/overview/#expo-go-an-optional-tool-for-learning) because React Native Firebase uses native code that is not compiled into Expo Go. > **Warning:** If you are using `expo-dev-client`, native crashes (such as those triggered by `crash(getCrashlytics())`) will **not** be reported to Firebase Crashlytics during development. This is because `expo-dev-client` provides a custom error overlay that catches and displays errors before they are sent to Firebase. To test native crash reporting, you must remove `expo-dev-client` and run your app in a standard release or debug build without the custom error overlay. To create a new Expo project, see the [Get started](https://docs.expo.dev/get-started/create-a-project/) guide in Expo documentation. ### Install React Native Firebase modules To install React Native Firebase's base `app` module, use the command `npx expo install @react-native-firebase/app`. Similarly you can install other React Native Firebase modules such as for Authentication and Crashlytics: `npx expo install @react-native-firebase/auth @react-native-firebase/crashlytics`. ### Configure React Native Firebase modules The recommended approach to configure React Native Firebase is to use [Expo Config Plugins](https://docs.expo.dev/config-plugins/introduction/). You will add React Native Firebase modules to the [`plugins`](https://docs.expo.io/versions/latest/config/app/#plugins) array of your `app.json` or `app.config.js`. See the note below to determine which modules require Config Plugin configurations. If you are instead manually adjusting your Android and iOS projects (this is not recommended), follow the same instructions as [React Native CLI projects](/#installation-for-react-native-cli-non-expo-projects). To enable Firebase on the native Android and iOS platforms, create and download Service Account files for each platform from your Firebase project. Then provide paths to the downloaded `google-services.json` and `GoogleService-Info.plist` files in the following `app.json` fields: [`expo.android.googleServicesFile`](https://docs.expo.io/versions/latest/config/app/#googleservicesfile-1) and [`expo.ios.googleServicesFile`](https://docs.expo.io/versions/latest/config/app/#googleservicesfile). See the example configuration below. For iOS, React Native Firebase resolves the Firebase Apple SDK with [Swift Package Manager by default](/ios-spm) on React Native 0.75+. SPM requires dynamic frameworks — configure [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/#pluginconfigtypeios) with `"useFrameworks": "dynamic"`. See the example configuration below. The following is an example `app.json` to enable the React Native Firebase modules App, Auth and Crashlytics, that specifies the Service Account files for both mobile platforms, and that sets the application ID to the example value of `com.mycorp.myapp` (change to match your own). You will need to add a plugin entry for each react-native-firebase module you use that defines an Expo config plugin - these are documented on the specific module install pages. ```json { "expo": { "android": { "googleServicesFile": "./google-services.json", "package": "com.mycorp.myapp" }, "ios": { "googleServicesFile": "./GoogleService-Info.plist", "bundleIdentifier": "com.mycorp.myapp" }, "plugins": [ "@react-native-firebase/app", "@react-native-firebase/auth", "@react-native-firebase/crashlytics", [ "expo-build-properties", { "ios": { "useFrameworks": "dynamic" } } ] ] } } ``` > Listing a module in the Config Plugins (the `"plugins"` array in the JSON above) is only required for React Native Firebase modules that involve _native installation steps_ - e.g. modifying the Xcode project, `Podfile`, `build.gradle`, `AndroidManifest.xml` etc. React Native Firebase modules without native steps will work out of the box; no `"plugins"` entry is required. Not all modules have Expo Config Plugins provided yet. A React Native Firebase module has Config Plugin support if it contains an `app.plugin.js` file in its package directory (e.g.`node_modules/@react-native-firebase/app/app.plugin.js`). If you use `@react-native-firebase/analytics` with Expo, including EAS Build, and want to configure iOS Analytics Podfile flags, add the Analytics config plugin with the relevant iOS options: ```json [ "@react-native-firebase/analytics", { "ios": { "withoutAdIdSupport": true, "googleAppMeasurementOnDeviceConversion": true } } ] ``` The `withoutAdIdSupport` option adds `$RNFirebaseAnalyticsWithoutAdIdSupport = true` to opt out of iOS Ad ID support. The `googleAppMeasurementOnDeviceConversion` option adds `$RNFirebaseAnalyticsGoogleAppMeasurementOnDeviceConversion = true` to include Google Analytics on-device conversion measurement support. You may omit either option if it is not needed. #### CocoaPods / static frameworks (opt-out) Do **not** combine RNFB's default SPM mode with static frameworks. To use CocoaPods instead of SPM (for example when you need static linkage, or to share one `FirebaseCore` with another native pod), pass `disableSPM: true` to the `@react-native-firebase/app` config plugin and set `"useFrameworks": "static"`. With React Native 0.84+ / Expo 54+ prebuilt core, list every RNFB native module you use in `forceStaticLinking`. See [iOS SPM Support](/ios-spm) for details: ```json { "expo": { "plugins": [ [ "@react-native-firebase/app", { "ios": { "disableSPM": true } } ], "@react-native-firebase/auth", "@react-native-firebase/crashlytics", [ "expo-build-properties", { "ios": { "useFrameworks": "static", "forceStaticLinking": [ "RNFBApp", "RNFBAuth", "RNFBCrashlytics", "RNFBSomeOtherRNFBModuleYouAreUsing" ] } } ] ] } } ``` ### Local app compilation If you are compiling your app locally, run [`npx expo prebuild --clean`](https://docs.expo.dev/workflow/continuous-native-generation/) to generate the native project directories. Then, follow the local app compilation steps described in [Local app development](https://docs.expo.dev/guides/local-app-development/) guide in Expo docs. If you prefer using a build service, refer to [EAS Build](https://docs.expo.dev/build/setup/). Note: if you have already installed an Expo development build (using something like `npx expo run` after doing the `--prebuild` local development steps...) before installing react-native-firebase, then you must uninstall it first as it will not contain the react-native-firebase native modules and you will get errors with `RNFBAppModule not found` etc. If so, uninstall the previous development build, do a clean build using `npx expo prebuild --clean`, and then attempt `npx expo run:` again. ### Expo Tools for VSCode If you are using the [Expo Tools](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools) VSCode extension, the IntelliSense will display a list of available plugins when editing the `plugins` section of `app.json`. --- ## Installation for React Native CLI (non-Expo) projects Installing React Native Firebase to a RN CLI project requires a few steps; installing the NPM module, adding the Firebase config files & rebuilding your application. ### 1. Install via NPM Install the React Native Firebase "app" module to the root of your React Native project with NPM or Yarn: ```bash # Using npm npm install --save @react-native-firebase/app # Using Yarn yarn add @react-native-firebase/app ``` The `@react-native-firebase/app` module must be installed before using any other Firebase service. ### 2. React Native CLI - Android Setup To allow the Android app to securely connect to your Firebase project, a configuration file must be downloaded and added to your project. #### Generating Android credentials On the Firebase console, add a new Android application and enter your projects details. The "Android package name" must match your local projects package name which can be found inside of the `namespace` field in `/android/app/build.gradle`, or in the `manifest` tag within the `/android/app/src/main/AndroidManifest.xml` file within your project for projects using android gradle plugin v7 and below > The debug signing certificate is optional to use Firebase with your app, but is required for Invites and Phone Authentication. > To generate a certificate run `cd android && ./gradlew signingReport`. This generates two variant keys. > You have to copy **both** 'SHA1' and 'SHA-256' keys that belong to the 'debugAndroidTest' variant key option. > Then, you can add those keys to the 'SHA certificate fingerprints' on your app in Firebase console. Download the `google-services.json` file and place it inside of your project at the following location: `/android/app/google-services.json`. #### Configure Firebase with Android credentials To allow Firebase on Android to use the credentials, the `google-services` plugin must be enabled on the project. This requires modification to two files in the Android directory. First, add the `google-services` plugin as a dependency inside of your `/android/build.gradle` file: ```groovy buildscript { dependencies { // ... other dependencies classpath 'com.google.gms:google-services:4.5.0' // Add me --- /\ } } ``` Lastly, execute the plugin by adding the following to your `/android/app/build.gradle` file: ```groovy apply plugin: 'com.android.application' apply plugin: 'com.google.gms.google-services' // <- Add this line ``` ### 3. React Native CLI - iOS Setup To allow the iOS app to securely connect to your Firebase project, a configuration file must be downloaded and added to your project, and you must enable frameworks in CocoaPods #### Generating iOS credentials On the Firebase console, add a new iOS application and enter your projects details. The "iOS bundle ID" must match your local project bundle ID. The bundle ID can be found within the "General" tab when opening the project with Xcode. Download the `GoogleService-Info.plist` file. Using Xcode, open the projects `/ios/{projectName}.xcodeproj` file (or `/ios/{projectName}.xcworkspace` if using Pods). Right click on the project name and "Add files" to the project, as demonstrated below: ![Add files via Xcode](https://images.prismic.io/invertase/717983c0-63ca-4b6b-adc5-31318422ab47_add-files-via-xcode.png?auto=format) Select the downloaded `GoogleService-Info.plist` file from your computer, and ensure the "Copy items if needed" checkbox is enabled. ![Select 'Copy Items if needed'](https://prismic-io.s3.amazonaws.com/invertase%2F7d37e0ce-3e79-468d-930c-b7dc7bc2e291_unknown+%282%29.png) #### Configure Firebase with iOS credentials (react-native 0.77+) To allow Firebase on iOS to use the credentials, the Firebase iOS SDK must be configured during the bootstrap phase of your application. To do this, open your `/ios/{projectName}/AppDelegate.swift` file and add the following: At the top of the file, import the Firebase SDK right after `'import ReactAppDependencyProvider'`: ```swift import Firebase ``` Within your existing `application` method, add the following to the top of the method: ```swift override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { // Add me --- \/ FirebaseApp.configure() // Add me --- /\ // ... } ``` #### Configure Firebase with iOS credentials (react-native < 0.77) To allow Firebase on iOS to use the credentials, the Firebase iOS SDK must be configured during the bootstrap phase of your application. To do this, open your `/ios/{projectName}/AppDelegate.mm` file (or `AppDelegate.m` if on older react-native), and add the following: At the top of the file, import the Firebase SDK right after `'#import "AppDelegate.h"'`: ```objectivec #import ``` Within your existing `didFinishLaunchingWithOptions` method, add the following to the top of the method: ```objectivec - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Add me --- \/ [FIRApp configure]; // Add me --- /\ // ... } ``` #### Altering CocoaPods to use frameworks Beginning with firebase-ios-sdk v9+ (react-native-firebase v15+) you must tell CocoaPods to use frameworks. On React Native 0.75+, React Native Firebase resolves the Firebase Apple SDK with [Swift Package Manager by default](/ios-spm), which **requires dynamic linkage**. Open the file `./ios/Podfile` and add this line inside your targets (right before the `use_react_native` line in current react-native releases that calls the react native Podfile function to get the native modules config): ```ruby use_frameworks! :linkage => :dynamic ``` Do **not** combine RNFB's default SPM mode with `use_frameworks! :linkage => :static` — `pod install` rejects that combination. Full requirements, Expo notes, and troubleshooting are in [iOS SPM Support](/ios-spm). ##### CocoaPods / static frameworks (opt-out) To opt out of SPM and use CocoaPods for Firebase (for example when you need static linkage, or to share one `FirebaseCore` with another native pod), set `$RNFirebaseDisableSPM = true` **before** any target block, then configure static frameworks: ```ruby # before any target block $RNFirebaseDisableSPM = true # inside your app target, before use_react_native! use_frameworks! :linkage => :static $RNFirebaseAsStaticFramework = true ``` > **Note:** `use_frameworks` is [not compatible with Flipper](https://github.com/reactwg/react-native-releases/discussions/21#discussioncomment-2924919). Flipper is deprecated in the React Native community; if your Podfile still references `:flipper_configuration`, remove or comment it out. ### 4. Autolinking & rebuilding Once the above steps have been completed, the React Native Firebase library must be linked to your project and your application needs to be rebuilt. Users on React Native 0.60+ automatically have access to "[autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md)", requiring no further manual installation steps. To automatically link the package, rebuild your project: ```bash # Android apps npx react-native run-android # iOS apps cd ios/ pod install --repo-update cd .. npx react-native run-ios ``` Once successfully linked and rebuilt, your application will be connected to Firebase using the `@react-native-firebase/app` module. This module does not provide much functionality, therefore to use other Firebase services, each of the modules for the individual Firebase services need installing separately. --- ## Other / Web If you are using the firebase-js-sdk fallback support for [web or "other" platforms](platforms#other-platforms) then you must initialize Firebase dynamically by calling [`initializeApp`](https://invertase.github.io/react-native-firebase/_react-native-firebase/app/initializeApp.html). However, you only want to do this for the web platform. For non-web / native apps the "default" firebase app instance will already be configured by the native google-services.json / GoogleServices-Info.plist files as mentioned above. At some point during your application's bootstrap processes, initialize firebase like this: ```javascript import { getApp, initializeApp } from '@react-native-firebase/app'; // web requires dynamic initialization on web prior to using firebase if (Platform.OS === 'web') { const firebaseConfig = { // ... config items pasted from firebase console for your web app here }; initializeApp(firebaseConfig); } // ...now throughout your app, use firebase APIs normally, for example: const firebaseApp = getApp(); ``` --- ## Miscellaneous ### Overriding Native SDK Versions React Native Firebase internally sets the versions of the native SDKs which each module uses. Each release of the library is tested against a fixed set of SDK versions (e.g. Firebase SDKs), allowing us to be confident that every feature the library supports is working as expected. Sometimes it's required to change these versions to play nicely with other React Native libraries or to work around temporary build failures; therefore we allow manually overriding these native SDK versions. > Using your own SDK versions is not recommended and not supported as it can lead to unexpected build failures when new react-native-firebase versions are released that expect to use new SDK versions. Proceed with caution and remove these overrides as soon as possible when no longer needed. #### Android Within your projects /android/build.gradle file, provide your own versions by specifying any of the following options shown below: ```groovy project.ext { set('react-native', [ versions: [ // Overriding Build/Android SDK Versions if desired android : [ minSdk : 23, targetSdk : 33, compileSdk: 34, ], // Overriding Library SDK Versions if desired firebase: [ // Override Firebase SDK Version bom : "34.18.0" ], ], ]) } ``` Once changed, rebuild your application with `npx react-native run-android`. #### iOS Open your projects `/ios/Podfile` and add any of the globals shown below to the top of the file: ```ruby # Override Firebase SDK Version if desired $FirebaseSDKVersion = '12.18.0' ``` Once changed, reinstall your projects pods via pod install and rebuild your project with `npx react-native run-ios`. Alternatively, if you cannot edit the Podfile easily (as when using Expo), you may add the environment variable `FIREBASE_SDK_VERSION=12.18.0` (or whatever version you need) to the command line that installs pods. For example `FIREBASE_SDK_VERSION=12.18.0 yarn expo prebuild --clean` ### Android Performance On Android, React Native Firebase uses [thread pool executor](https://developer.android.com/reference/java/util/concurrent/ThreadPoolExecutor) to provide improved performance and managed resources. To increase throughput, you can tune the thread pool executor via `firebase.json` file within the root of your project: ```json // /firebase.json { "react-native": { "android_task_executor_maximum_pool_size": 10, "android_task_executor_keep_alive_seconds": 3 } } ``` | Key | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `android_task_executor_maximum_pool_size` | Maximum pool size of ThreadPoolExecutor. Defaults to `1`. Larger values typically improve performance when executing large numbers of asynchronous tasks, e.g. Firestore queries. Setting this value to `0` completely disables the pooled executor and all tasks execute in serial per module. | | `android_task_executor_keep_alive_seconds` | Keep-alive time of ThreadPoolExecutor, in seconds. Defaults to `3`. Excess threads in the pool executor will be terminated if they have been idle for more than the keep-alive time. This value doesn't have any effect when the maximum pool size is lower than `2`. | ``` ### About Source: https://rnfirebase.io/about ```mdx # About React Native Firebase The React Native Firebase project started life in late 2016 as a personal project [Mike Diarmid](https://twitter.com/mikediarmid) and [Elliot Hesp](https://twitter.com/elliothesp) were working on. The project gained instant popularity, allowing React Native developers to hook into the native services Firebase provides. During the first few months of its development, the repository was moved into the organization of Invertase on GitHub. The organization was a collection of the personal and combined Open Source efforts Mike and Elliot had been working over the past number of years. With a constant flow of feature requests, issues and contributions, the library rapidly grew in popularity, achieving over 100k NPM downloads in its first 12 months of development. In mid-2017, we were approached by Google, who offered to help ensure the projects continued support by providing direct contact with the Firebase team and by providing funding to ensure the project had dedicated time assigned to its upkeep. In the 2018 Firebase Summit in Prague during the opening keynote, Google openly announced their working relationship with Invertase - check it out below: [https://twitter.com/rnfirebase/status/1056839638961348608/video/1](https://twitter.com/rnfirebase/status/1056839638961348608/video/1) ## Future of the library The React Native Firebase library has been a huge driving force for our knowledge and experience. Even with years of experience in Open Source, JavaScript, Android and iOS, we're constantly learning and improving the library - whilst focusing on the needs of the community and many users of the library. Maintaining a popular Open Source library is hard, yet rewarding work. With the support from the community and Google, we're pleased to announce that starting in 2019, our very own Mike Diarmid will be working full time on the library. With the lessons we've learnt, we'll be focusing on taking the library to a new level. Read about it [here](https://medium.com/invertase/react-native-firebase-2019-7e334ca9bcc6). The success and upkeep of the library would not be possible without the support and contributions from the community. To date, we've had contributions from 114 members of the Open Source community on the repository to who we're very grateful to, the project wouldn't be where it is without you. Special thanks to Chris Bianca at [CS Frequency Limited](http://invertase.link/csf-website) for their work in helping to get this project off the ground. We'd also like to extend our thanks to our backers on Open Collective, whose contributions have made it possible to sustain the vast amount of time required in the upkeep of such a project. The future of Invertase and React Native Firebase is exciting. ``` ### Enabling Multidex Source: https://rnfirebase.io/enabling-multidex ```mdx As more native dependencies are added to your project, it may bump you over the 64k method limit on the Android build system. Once this limit has been reached, you will start to see the following error whilst attempting to build your Android application: ``` Execution failed for task ':app:mergeDexDebug'. ``` To learn more about multidex, view the official [Android documentation](https://developer.android.com/studio/build/multidex#mdex-gradle). ## Enabling Multidex There are 3 steps involved in enabling multidex. Steps 1 and 2 tell Gradle to turn on multidex with a directive, and add new dependency. Open the `/android/app/build.gradle` file. Under `dependencies` we need to add the module, and then enable it within the `defaultConfig`: ```groovy android { defaultConfig { // ... multiDexEnabled true // <-- ADD THIS in the defaultConfig section } // ... } dependencies { implementation 'androidx.multidex:multidex:2.0.1' // <-- ADD THIS DEPENDENCY } ``` The 3rd step is to alter your `android/app/src/main/java/.../MainApplication.java` file to extend `MultiDexApplication` like so: ```java // ... all your other imports here import androidx.multidex.MultiDexApplication; // <-- ADD THIS IMPORT // Your class definition needs `extends MultiDexApplication` like below public class MainApplication extends MultiDexApplication implements ReactApplication { ``` Once added, rebuild your application: `npx react-native run-android`. ``` ### FAQs and Tips Source: https://rnfirebase.io/faqs-and-tips ```mdx Over the years, there’s been a lot of discussions on our [GitHub](https://github.com/invertase/react-native-firebase) and [Discord](https://invertase.link/discord). Many of them have been about common problems developers face when using our package, and some of them resulted in very good advice being given. In order to save others time and frustration, this page has been created to document some of these common problems and good pieces of advice. If you come across a discussion that results in great advice that can benefit many developers, or a discussion that resolves a problem that many developers encounter, please do add it here! Someone will definitely be grateful. # FAQs ### Why `react-native-firebase` over `firebase-js-sdk`? This package wraps `firebase-android-sdk` and `firebase-ios-sdk` into a Javascript API for React Native projects, so the main benefits come with the access to native code. - There are more modules in the native SDKs than the web SDK because some things only make sense in a mobile / native context ( App Distribution, Crashlytics), so you can actually do more, and some of it is important for example, monitoring quality with Crashlytics - Some of the modules that are both in the web SDK and native SDK have a great deal more functionality when they can harness native APIs, like messaging (with background delivery that can start your app if not running), like App Check where you can tie the attestation to device-level providers, Storage where you can do background downloads, Performance where you can start measurements from boot, etc. ### Does it work with New Architecture / Fabric / TurboModules ? As far as we know, yes. We test with new architecture enabled now, and many of our users are using react-native 0.76+ with new architecture enabled. We are not aware of any problems with the react-native-firebase modules themselves. Please let us know if you see anything. However, we are still running in the TurboModule interoperability mode as we have not directly ported to Fabric internally yet. Migration is planned in the future but may still be a while. ### I need help with [anything regarding v5 or earlier of React Native Firebase]. Where could I get help with that? React Native Firebase v5 is now deprecated and unsupported. There's been over a year's grace period provided to migrate to v6, so moving forward maintainers probably won't pay much attention to issues regarding v5. Understandably, upgrading to v6 can take some effort, but staying on v5 probably isn't a great choice for the long-term health of your project. Lots of the breaking changes that were introduced were either due to upstream deprecations in the official SDKs, or to simply make the package more stable and more representative of how the actual SDKs work. The longer you stay on v5, the more your project will be out of sync with the official SDKs, unfortunately. Couple that with the fact that it's no longer actively supported, and that's trouble looming over the horizon for your project. We highly recommend taking the necessary pains to update to v6. ### My CI build hangs at the "Running script '[CP-User] [RNFB] Core Configuration'" step This may be fixed by creating a `firebase.json` file at the root of your project if it's not there already. If you don't want to change any of the default React Native Firebase configurations, you can leave it empty in the following way: ``` { "react-native": { } } ``` ### I have a custom Analytics parameter called 'items' and it's not showing up on the Firebase console. How come? This happens to be a known problem with the upstream Analytics SDKs. The Firebase team doesn't have any plans to fix it soon. More information about this can be found [here](https://github.com/invertase/react-native-firebase/issues/4018#issuecomment-682174087). ### I'm receiving `InternalFirebaseAuth.FIREBASE_AUTH_API is not available on this device`. How do I fix this? To use some Firebase services (like auth) in an emulator, you need an Android virtual device with Google Play services installed. Check this [Stack Overflow post](https://stackoverflow.com/a/46246782/2275865) for instructions on creating a new Android virtual device with the necessary APIs installed. ### I'm getting an SIGABRT error in Xcode when faking a crash on iOS. How do I fix this? When you get an error on this line when faking a crash on iOS: ``` RCT_EXPORT_METHOD(crash) { if ([RNFBCrashlyticsInitProvider isCrashlyticsCollectionEnabled]) { assert(NO); } } ``` Just disable your debugger in Xcode. 'Project name' -> 'Edit Scheme...' -> 'Run' -> deselect "Debug executable" ### I have the latest SDK installed, but I can't send a test in app message from the console. How do I fix this? Sometimes when building an in-app-message in the console, sending a test to a device is not possible, as the "Test on device" button is grayed out. This can be very annoying, but have found a "work around" that enables the button: 1. Make sure to fill out all fields in the first step of the form. If that doesn't enable the button: 1. Make sure to click inside every field, even if the field does not need to be updated (specially the "Text color" ones). If that doesn't enable the button: 1. Change between the "Message layout" options (Card, Modal, Image only and Top banner). Sometimes, after step 3, you have to click inside a "Text color" field, but this should enable the "Test on device" option. After that you add the device Install ID, make sure to quit the app before the actual test, and then I wait for the confirmation toast to open the app up again. As long as the ID is 100% correct, the test should work as intended. ### On iOS, when the app is in quit state, the setBackgroundMessageHandler is never invoked even when I receive the notification. How can I fix this? > Note: If you use @notifee/react-native, since v7.0.0, `onNotificationOpenedApp` and `getInitialNotification` will no longer trigger as notifee will handle the event. When the app is closed/quit, this can happen even when you are getting notifications and even when you are able to invoke the app in a headless state. To fix this: 1. You first need to send the payload with "content-available: 1" in the `apns` section of the message payload so the app gets invoked in a headless state. 2. On the `index.js` page, if the app is invoked in headless mode, instead of returning null, return a simple component that does nothing and renders nothing. Otherwise, return the actual `App` component. To view the complete detail for this solution, please refer to this page: [#5656](https://github.com/invertase/react-native-firebase/issues/5656) # Tips - Whenever you face a strange issue (or an issue that causes build errors), there are two things you should always consider. - Build processes are costly and complex, so caching is used a lot. As a result, certain changes that you make in your app can cause cache conflicts in subsequent builds. Deal with this via `npx react-native-clean-project`. This does solve a lot of problems. - Try and isolate the problem with a template React Native Firebase app. This [bash script](https://github.com/mikehardy/rnfbdemo/blob/main/make-demo.sh) is particularly helpful in making an empty template app. - Advice on supporting multiple environments (for example, dev, prod, maybe also staging, qa) for your React Native Firebase App: [#3504](https://github.com/invertase/react-native-firebase/issues/3504) - Using [Fastlane for iOS deployment](https://docs.fastlane.tools/getting-started/ios/setup/) together with [RN Firebase Crashlytics](https://rnfirebase.io/crashlytics/usage) within CI has been observed to cause builds that hang indefinitely. Using `setup_ci(force: true)` before building the application may solve the issue.: [#3706](https://github.com/invertase/react-native-firebase/issues/3706) - Be careful if you are using a VPN, Google blocks many VPN IPs causing "unavailable" errors for various firebase API calls, and on an Android emulator it might completely mess up the network adapter causing network calls to never return, not only on firebase but on the entire emulated phone. ``` ### Android Installation Source: https://rnfirebase.io/install-android ```mdx # Android Manual Installation The following steps are only required if you are using React Native 0.59 or earlier and need to manually integrate the library. ## 1. Update Gradle Settings Add the following to your projects `/android/settings.gradle` file: ```groovy include ':@react-native-firebase_app' project(':@react-native-firebase_app').projectDir = new File(rootProject.projectDir, './../node_modules/@react-native-firebase/app/android') ``` ## 2. Update Gradle Dependencies Add the React Native Firebase module dependency to your `/android/app/build.gradle` file: ```groovy dependencies { // ... implementation project(path: ":@react-native-firebase_app") } ``` ## 3. Add package to the Android Application Import and apply the React Native Firebase module package to your `/android/app/src/main/java/**/MainApplication.java` file: Import the package: ```java import io.invertase.firebase.app.ReactNativeFirebaseAppPackage; ``` Add the package to the registry: ```java protected List getPackages() { return Arrays.asList( new MainReactPackage(), new ReactNativeFirebaseAppPackage(), ``` ## 4. Rebuild the project Once the above steps have been completed, rebuild your Android project: ```bash npx react-native run-android ``` ``` ### iOS Installation Source: https://rnfirebase.io/install-ios ```mdx # iOS Manual Installation The following steps are only required if you are using React Native 0.59 or earlier, and need to manually integrate the library. ## 1. Add the Pod Add the `RNFBApp` Pod to your projects `/ios/Podfile`: ```ruby target 'app' do # ... pod 'RNFBApp', :path => '../node_modules/@react-native-firebase/app' end ``` ## 2. Update Pods & rebuild the project You may need to update your local Pods in order for the `RNFBApp` Pod to be installed in your project: ```bash $ cd ios/ $ pod install --repo-update ``` Once the Pods have installed locally, rebuild your iOS project: ```bash npx react-native run-ios ``` ``` ### iOS SPM Support Source: https://rnfirebase.io/ios-spm ```mdx # iOS SPM Support React Native Firebase can resolve its Firebase Apple SDK dependencies with [Swift Package Manager (SPM)](https://www.swift.org/package-manager/) or CocoaPods. This changes only how the native Firebase SDK is installed; your JavaScript and native application code do not change. ## Requirements and defaults - React Native 0.75 or newer uses SPM by default. - `$RNFirebaseDisableSPM = true` selects CocoaPods. - React Native versions older than 0.75 use CocoaPods because their pod tooling does not provide `spm_dependency`. - SPM requires CocoaPods 1.10 or newer. React Native 0.75+ templates already satisfy this requirement. SPM requires dynamic framework linkage: ```ruby use_frameworks! :linkage => :dynamic ``` Do not use RNFB's SPM mode with `use_frameworks! :linkage => :static`. firebase-ios-sdk SPM products are automatic libraries (plain `.library(...)`, not `type: .dynamic`), so each pod that depends on them embeds its own copy. With static pod linkage those copies collide at link time as duplicate-symbol errors. `pod install` fails fast for that combination instead of surfacing the linker failure later. Dynamic linkage is required for SPM mode to build and run; see [Sharing FirebaseCore with other native pods](#sharing-firebasecore-with-other-native-pods) for what dynamic linkage does and does not give you. CocoaPods mode supports either static or dynamic linkage, subject to the requirements of the other dependencies in your app. ## Expo projects Expo projects can select dynamic linkage with [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/): ```json { "expo": { "plugins": [ [ "expo-build-properties", { "ios": { "useFrameworks": "dynamic" } } ] ] } } ``` To use CocoaPods mode in a generated project, pass `disableSPM` to the `@react-native-firebase/app` config plugin -- it adds `$RNFirebaseDisableSPM = true` before the target blocks during prebuild -- and configure the linkage your project requires: ```json { "expo": { "plugins": [ [ "@react-native-firebase/app", { "ios": { "disableSPM": true } } ] ] } } ``` The sections below (**Use SPM (React Native CLI)**, **Use CocoaPods (React Native CLI)**) describe editing `ios/Podfile` directly. Do not follow them in an Expo project -- Expo regenerates `ios/Podfile` from your config plugins on every prebuild, so a direct edit does not persist. Use `expo-build-properties` (or your own config plugin) instead, as shown above. ## Use SPM (React Native CLI) For React Native 0.75 or newer, SPM is selected automatically. Configure dynamic linkage in your `ios/Podfile`, then install pods normally: ```ruby use_frameworks! :linkage => :dynamic ``` ```bash cd ios pod install ``` The install output identifies the selected mode: ```text [react-native-firebase] RNFBApp: Using SPM for Firebase dependency resolution (products: FirebaseCore, FirebaseInstallations) ``` RNFB also adds an `[RNFB] Embed Firebase SPM Frameworks` build phase to the app target. This phase embeds Firebase frameworks built by SPM that React Native's pod-level SPM integration does not otherwise copy into the app bundle. ### Release build and module-resolution settings RNFB automatically applies two build settings needed for SPM + dynamic linkage, on every `pod install`/`pod update`: - `-ObjC` in the app target's linker flags, so Release's dead-code stripping does not drop Firebase's `FIRLibrary`/`FIRComponent` registration. - `SWIFT_ENABLE_EXPLICIT_MODULES = 'NO'` and `CLANG_ENABLE_EXPLICIT_MODULES = 'NO'` on both the app project and the Pods project, so Xcode 26's explicit Swift and Clang modules don't fail to resolve Firebase's internal-only SPM targets (`FirebaseCoreInternal`, `FirebaseSharedSwift`) or `@import`s of Firebase modules in your own Objective-C/Objective-C++ files. This does not disable SPM -- it makes Swift and Clang use implicit module discovery across the app, CocoaPods, and SPM build boundary. You do not need to configure either of these yourself. If `pod install` warns that they could not be applied automatically, or if Xcode still reports that a Firebase module cannot be resolved, add the fallback in your existing `post_install` block, after `react_native_post_install`: ```ruby post_install do |installer| react_native_post_install( installer, config[:reactNativePath], # your existing options ) rnfirebase_apply_spm_build_settings(installer) end ``` ### Framework-embedding fallback RNFB normally installs its SPM framework-embedding phase automatically after CocoaPods has integrated `[CP] Embed Pods Frameworks` into the app target (`post_integrate`). If `pod install` warns that automatic embedding could not be configured, call the documented fallback from `post_integrate`: ```ruby post_integrate do |installer| rnfirebase_add_spm_embed_phase(installer) end ``` Do not add the fallback unless the warning appears or the generated app target does not contain `[RNFB] Embed Firebase SPM Frameworks`. ## Use CocoaPods (React Native CLI) To opt out of SPM, add this before any target block in your Podfile: ```ruby $RNFirebaseDisableSPM = true ``` Then use the static or dynamic linkage required by your project and run `pod install`. The install output confirms the fallback: ```text [react-native-firebase] RNFBApp: SPM disabled ($RNFirebaseDisableSPM = true), using CocoaPods for Firebase dependencies ``` `$RNFirebaseDisableSPM` must be set to exactly `true` to opt out of SPM. Any other value -- `false`, `nil`, or leaving it unset -- uses SPM (React Native 0.75+ default). This matters for generated or template-based Podfiles that always emit the variable, e.g. `$RNFirebaseDisableSPM = false`: that still uses SPM, it does not fall back to CocoaPods. ## Sharing FirebaseCore with other native pods React Native attaches SPM products to each pod target via `spm_dependency`. Because firebase-ios-sdk products are automatic libraries, each dynamic pod framework that depends on Firebase embeds its own copy of `FirebaseCore`. `FirebaseApp.configure()` in the app configures only the copy that target links. Another pod's copy is never configured, so `FirebaseApp.app()` can return `nil` there (and Auth can silently look signed-out even when RNFB JS Auth has a user). | RNFB | Other native dependency | Shared FirebaseCore? | | ------------------------------------------ | ----------------------- | ---------------------------------------------- | | SPM | SPM (`spm_dependency`) | No: each dynamic pod embeds its own copy | | SPM | CocoaPods Firebase pods | No: dual resolution (SPM + CocoaPods Firebase) | | CocoaPods (`$RNFirebaseDisableSPM = true`) | CocoaPods Firebase pods | Yes: one CocoaPods `FirebaseCore` | If a third-party native module must share the same configured `FirebaseApp` with RNFB, opt out of SPM and resolve Firebase through CocoaPods for every native consumer: ```ruby $RNFirebaseDisableSPM = true ``` Do not mix RNFB SPM with a third-party pod that pulls Firebase via CocoaPods pods. That is dual resolution and does not produce one shared runtime. Static pod linkage is not a sharing workaround under SPM: it fails at link time with duplicate symbols (and `pod install` rejects the combination). ## Troubleshooting - **`pod install` fails with "SPM + static linkage is not supported":** Do not combine RNFB SPM mode with static linkage. Use dynamic linkage (`use_frameworks! :linkage => :dynamic`) or set `$RNFirebaseDisableSPM = true`. - **`FirebaseApp.app()` is `nil` / Auth looks signed-out inside another native pod, or runtime logs duplicate `FIRApp` classes:** SPM mode cannot share one `FirebaseCore` across dynamic pod frameworks. Set `$RNFirebaseDisableSPM = true` and resolve Firebase via CocoaPods for RNFB and that dependency. See [Sharing FirebaseCore with other native pods](#sharing-firebasecore-with-other-native-pods). - **`FirebaseCoreInternal`/`FirebaseSharedSwift` cannot be resolved, or a Release/Archive build crashes at launch with a missing Firebase symbol:** RNFB applies `-ObjC`, `SWIFT_ENABLE_EXPLICIT_MODULES = 'NO'`, and `CLANG_ENABLE_EXPLICIT_MODULES = 'NO'` automatically; call `rnfirebase_apply_spm_build_settings(installer)` as a fallback only if `pod install` warns it could not do so. - **A Firebase framework is missing at app launch:** Re-run `pod install`, check for its automatic-embedding warning, and confirm the app target contains `[RNFB] Embed Firebase SPM Frameworks`. Use the fallback only when needed. - **`spm_dependency` is unavailable:** Upgrade to React Native 0.75 or newer, or continue with the automatic CocoaPods fallback. - **SPM and CocoaPods both produce the same Firebase framework:** Remove manually declared Firebase pods/packages so RNFB owns Firebase dependency resolution. - **Release archive fails with an `xcframework-ios.signature` "couldn't be copied ... because an item with the same name already exists" error:** a long-standing Xcode Archive bug with SPM binary xcframeworks, not an RNFB regression. RNFB works around it automatically; if the warning says it could not do so, add a Run Script build phase to your app target that removes the named artifact: ```bash rm -f "${CONFIGURATION_BUILD_DIR}"/.xcframework-ios.signature ``` - **Archive fails with `Undefined symbols ... _OBJC_CLASS_$_FIRApp`:** RNFB links `FirebaseCore` into your app target automatically (after CocoaPods integrates `[CP] Embed Pods Frameworks`) so the required `[FIRApp configure]`/`FirebaseApp.configure()` call links. This only surfaces if that automatic step could not run; call `rnfirebase_add_spm_core_to_app_target(installer)` from `post_integrate` as a fallback if your own native code also calls Firebase APIs directly. - **A stale "firebase-ios-sdk" Swift Package reference remains on the app target after switching from SPM to `$RNFirebaseDisableSPM = true`:** RNFB removes it automatically on the next `pod install`; if that could not run, remove the "firebase-ios-sdk" Swift Package dependency from the app target manually in Xcode. After changing dependency resolution, verify both a Debug build and a Release archive. A simulator build alone does not exercise all framework-embedding and archive-time processing behavior. ### tvOS hybrid-linkage TestFlight crash A custom hybrid setup has reported an immediate tvOS TestFlight launch failure when Firebase is statically linked into the app while RNFB is built as dynamic frameworks with `-undefined dynamic_lookup`. Simulator and direct Xcode installs may still work because App Store archive processing strips symbols differently. This is not the standard RNFB SPM configuration. Prefer a consistent linkage model. If the hybrid setup is unavoidable, first confirm the archived app binary no longer exports the Firebase symbols required by the RNFB frameworks. The reported workaround is to preserve those symbols on the main app target's Release configuration: ```ruby installer.aggregate_targets.each do |aggregate_target| aggregate_target.user_project.native_targets.each do |target| next unless target.name == 'YourAppTargetName' # main app target, not a Pod target target.build_configurations.each do |config| next unless config.name == 'Release' config.build_settings['STRIP_SWIFT_SYMBOLS'] = 'NO' config.build_settings['DEAD_CODE_STRIPPING'] = 'NO' config.build_settings['STRIP_INSTALLED_PRODUCT'] = 'NO' config.build_settings['COPY_PHASE_STRIP'] = 'NO' config.build_settings['DEPLOYMENT_POSTPROCESSING'] = 'NO' flags = Array(config.build_settings['OTHER_LDFLAGS'] || ['$(inherited)']) flags << '-Wl,-export_dynamic' unless flags.include?('-Wl,-export_dynamic') config.build_settings['OTHER_LDFLAGS'] = flags end end aggregate_target.user_project.save end ``` This workaround increases binary size and disables Release optimizations. Apply it only to the affected target after reproducing this specific archive-only failure. ``` ### Migrating to v6 Source: https://rnfirebase.io/migrating-to-v6 ```mdx # 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](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md) & [TypeScript](https://reactnative.dev/docs/typescript). Version 6 also brings support for previously unsupported modules such as [Firebase ML](https://firebase.google.com/docs/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](/migrating-to-v6#removing-v5-from-javascript) - [Removing v5 from Android](/migrating-to-v6#removing-v5-from-android) - [Removing v5 from iOS](/migrating-to-v6#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: ```diff { "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: ```diff 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 ```diff - - - - - ``` #### 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: ```diff 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_ ```diff 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 >>:<>"`. For example, to remove the native Firebase dependency for the Authentication module: ```diff 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: ```diff - import io.invertase.firebase.RNFirebasePackage; ``` ```diff @Override protected List getPackages() { return Arrays.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: ```diff - import io.invertase.firebase.auth.RNFirebaseAuthPackage; ``` ```diff @Override protected List getPackages() { return Arrays.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: ```bash $ 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`: ```diff 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: ```diff 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: ```diff 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: ```bash $ 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](https://yarnpkg.com/lang/en/): ```bash yarn add @react-native-firebase/app ``` If you are using React Native 0.60+, the module will be automatically linked via [autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). Users on an older version of React Native must manually link the `app` module. See the following steps for [Android](/install-android) and [iOS](/install-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: ```bash yarn add @react-native-firebase/auth ``` Install the modules required for your application: | Module | NPM Package | | ------------------------------------------------------------ | --------------------------------------- | | AdMob | @react-native-firebase/admob | | Analytics | @react-native-firebase/analytics | | App | @react-native-firebase/app | | App Invites | @react-native-firebase/invites | | Authentication | @react-native-firebase/auth | | Cloud Firestore | @react-native-firebase/firestore | | Cloud Functions | @react-native-firebase/functions | | Cloud Messaging | @react-native-firebase/messaging | | Cloud Storage | @react-native-firebase/storage | | Crashlytics | @react-native-firebase/crashlytics | | In-app Messaging | @react-native-firebase/in-app-messaging | | Instance ID | @react-native-firebase/iid | | ML | @react-native-firebase/ml | | Performance Monitoring | @react-native-firebase/perf | | Realtime Database | @react-native-firebase/database | | Remote Config | @react-native-firebase/remote-config | 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: ```js 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: ```js 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: ```diff - 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): ```js 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 AdMob documentation and update your code usage. - `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 Dynamic Links deprecation FAQ](https://firebase.google.com/support/dynamic-links-faq) 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` - set a singular key value to show alongside any subsequent crash reports - `setAttributes(values: { [key: string]: string }): Promise` - 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](https://david-smith.org/iosversionstats/). - 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/resource_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` 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. ``` ### Migrating to v22 Source: https://rnfirebase.io/migrating-to-v22 ```mdx # Switching off warning logs You may notice a lot of console warning logs as we deprecate the existing namespaced API. If you would like to switch these logs off, you may set the following global property to `true` anywhere before you initialize Firebase. ```js globalThis.RNFB_SILENCE_MODULAR_DEPRECATION_WARNINGS = true; ``` # Enabling deprecation strict modes You may enable a feature for the API migration which will throw a javascript error immediately when any namespaced API usage is detected. This is useful to help you quickly locate any remaining usage of the deprecated namespace API via examination of the line numbers in the stack trace. Note that there may be modular API implementation errors within the react-native-firebase modules, this may still be useful as a troubleshooting aid when collaborating with the maintainers to correct these errors. ```js globalThis.RNFB_MODULAR_DEPRECATION_STRICT_MODE = true; ``` # Migrating to React Native modular API If you are familiar with the Firebase JS SDK, the upgrade will be a familiar process, following similar steps to [the migration guide](https://firebase.google.com/docs/web/modular-upgrade#refactor_to_the_modular_style) for firebase-js-sdk. React Native Firebase uses the same API as the official [Firebase JS SDK modular API documentation](https://firebase.google.com/docs/reference/js) so the same migration steps apply here, except there is no need for special "compat" imports as an intermediate step. The process will always follow the same steps for every API you use: - determine the new modular API function for the old namespaced API you are using - import that new modular API function - change the call from using the firebase module to access the API and passing parameters, to the new style of using the modular API function, passing in the firebase module object(s) required for it to work and then the parameters. In the end, it should be a very mechanical process and can be done incrementally, one API call at a time. There are concrete examples below to show the process ## Firestore Deprecation Example ### Namespaced (deprecated) Query You ought to move away from the following way of making Firestore queries. The React Native Firebase namespaced API is being completely removed in React Native Firebase v22: ```js import firestore from '@react-native-firebase/firestore'; const db = firestore(); const querySnapshot = await db.collection('cities').where('capital', '==', true).get(); querySnapshot.forEach(doc => { console.log(doc.id, ' => ', doc.data()); }); ``` ### Modular Query This is how the same query would look using the new, React Native Firebase modular API: ```js import { collection, query, where, getDocs, getFirestore } from '@react-native-firebase/firestore'; const db = getFirestore(); const q = query(collection(db, 'cities'), where('capital', '==', true)); const querySnapshot = await getDocs(q); querySnapshot.forEach(doc => { console.log(doc.id, ' => ', doc.data()); }); ``` For more examples of requesting Firestore data, see the official Firebase documentation for [Get data with Cloud Firestore](https://firebase.google.com/docs/firestore/query-data/get-data). ### Migration Help You will find code snippets for "Web namespaced API" and "Web modular API" throughout the official Firebase documentation. Update your code to use "Web modular API". Here are some links to help you get started: - [Firestore](https://firebase.google.com/docs/firestore/quickstart) - [Auth](https://firebase.google.com/docs/auth/web/start) - [RTDB](https://firebase.google.com/docs/database/web/start) - [Storage](https://firebase.google.com/docs/storage/web/start) - [Remote Config](https://firebase.google.com/docs/remote-config/get-started?platform=web) - [Messaging](https://firebase.google.com/docs/cloud-messaging/js/client) - [Functions](https://firebase.google.com/docs/functions/callable) - [App Check](https://firebase.google.com/docs/app-check/web/recaptcha-provider) - [Analytics](https://firebase.google.com/docs/analytics/get-started) - [Perf](https://firebase.google.com/docs/perf-mon/get-started-web) - [Crashlytics](https://github.com/invertase/react-native-firebase/blob/ae03f3f0be636fcd949965ee720a691f8582ef82/packages/crashlytics/lib/types/crashlytics.ts) (Crashlytics doesn't exist on Firebase web, this is a link to the type declarations which contains all methods available). ``` ### Migrating to v23 Source: https://rnfirebase.io/migrating-to-v23 ```mdx # Firebase Crashlytics Modular API method `isCrashlyticsCollectionEnabled(crashlytics)` has been removed, please use the property on Crashlytics instance `getCrashlytics().isCrashlyticsCollectionEnabled` instead. # Firebase Auth `MultiFactorUser.enrolledFactor` has been removed, please use `MultiFactorUser.enrolledFactors`. See example: ```js const credential = await signInWithEmailAndPassword(getAuth(), 'dummy@example.com', 'password'); const multiFactorUser = credential.user.multiFactor; // Use below - remove any instances of `multiFactorUser.enrolledFactor` console.log(multiFactorUser.enrolledFactors); ``` # Firebase App - `gaMeasurementId` property from `FirebaseOptions` has been replaced with `measurementId` to match Firebase web JS SDK. # Firebase Dynamic Links ⚠️ **REMOVED** ⚠️ Firebase Dynamic Links has been Removed This package has been deprecated and removed from the React Native Firebase repository. ## Why was it deprecated? Firebase Dynamic Links has been deprecated by Google and will be shut down on August 25th, 2025. For more information about the deprecation and migration options, please visit: **[Firebase Dynamic Links Deprecation FAQ](https://firebase.google.com/support/dynamic-links-faq)** ## Migration Options The deprecation FAQ provides detailed guidance on how to migrate from Firebase Dynamic Links, including: - **Full feature parity**: Use alternative deep-linking service providers - **Simple deep-linking**: Migrate to App Links and Universal Links. [See Firebase documentation](https://firebase.google.com/support/guides/app-links-universal-links). - **No replacement needed**: Remove the package entirely ## Timeline - **August 25th, 2025**: Firebase Dynamic Links service will be completely shut down - All existing links will stop working - All APIs will return error responses Please refer to the official deprecation FAQ for complete migration guidance and support. # Android Platform - Android `minSdk` has been bumped from `21` to `23` (except Auth which already had a `minSdk` of `23`). - Auth play services has been bumped from `21.3.0` to `21.4.0`. - Crashlytics gradle plugin has been bumped from `3.0.4` to `3.0.5`. - Performance gradle plugin has been bumped from `1.4.2` to `2.0.0`. - App distribution gradle plugin has been bumped from `5.1.0` to `5.1.1`. # iOS platform - Minimum iOS deployment target has now been bumped to `15` from `13`. - Minimum Xcode version required for iOS development is now Xcode `16.2`, previous was Xcode `15.2`. - `gaMeasurementId` property from `FirebaseOptions` (now `measurementId` in React Native Firebase) has been removed from firebase-ios-sdk as it wasn't used. # Web platform - Firebase JS SDK has been bumped to `12.0.0` which now requires a minimum of Node.js `20` and a minimum of `ES2020`. [See release notes](https://firebase.google.com/support/release-notes/js#version_1200_-_july_17_2025). ``` ### Migrating to v24 Source: https://rnfirebase.io/migrating-to-v24 ```mdx Version 24 includes breaking changes for Firestore TypeScript types and Cloud Functions native integration. Review the sections below for the modules you use. # Firestore Version 24 introduces `withConverter` functionality from Firebase JS SDK. Due to the differences in types between references and queries in namespace vs modular API, and the namespaced APIs deprecation cycle being effectively complete with the API set for removal, we have adopted the modular API typing in general for firestore APIs. Reference and query types have been updated to support input of two generic types (`AppModelType`, `DbModelType`). Additionally, to match the JS SDK, they are now exported separately at the root, instead of through `FirebaseFirestoreTypes`. Most commonly these types will be affected: `CollectionReference`, `DocumentReference`, `DocumentSnapshot`, `QueryDocumentSnapshot`, `QuerySnapshot`, `Query`. ```js // Previously import { doc, getFirestore, onSnapshot, FirebaseFirestoreTypes } from '@react-native-firebase/firestore'; onSnapshot(doc(getFirestore(), 'foo', 'foo'), { next: (snapshot: FirebaseFirestoreTypes.DocumentSnapshot) => { console.log(snapshot.get('foo')); }, }); ``` ```js // Now import { doc, getFirestore, onSnapshot, DocumentSnapshot } from '@react-native-firebase/firestore'; onSnapshot(doc(getFirestore(), 'foo', 'foo'), { next: (snapshot: DocumentSnapshot) => { console.log(snapshot.get('foo')); }, }); ``` # Cloud Functions **PR:** [#8603](https://github.com/invertase/react-native-firebase/pull/8603) / v24.0.0 ([#8799](https://github.com/invertase/react-native-firebase/issues/8799) streaming callables) From v24 onward, `@react-native-firebase/functions` is implemented as a **TurboModule** and **requires React Native's New Architecture**. The legacy bridge module was removed. ## Who is affected | You use… | Action | | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `@react-native-firebase/functions` on **New Architecture** | No change required | | `@react-native-firebase/functions` on the **legacy architecture** | Enable New Architecture, or stay on v23 if you cannot migrate yet | | Other RN Firebase modules only | Functions is the first module with a hard requirement; `@react-native-firebase/app` prints a deprecation warning on legacy architecture builds | ## Enable New Architecture **React Native CLI (Android)** — set in `android/gradle.properties`: ```properties newArchEnabled=true ``` **React Native CLI (iOS)** — New Architecture is enabled when `RCT_NEW_ARCH_ENABLED=1` during `pod install` (React Native sets this from `newArchEnabled` on recent templates). Follow the [React Native New Architecture guide](https://reactnative.dev/docs/the-new-architecture/landing-page) for your RN version. **Expo** — enable in your app config (Expo SDK 52+): ```json { "expo": { "newArchEnabled": true } } ``` Rebuild native projects after changing this (`pod install`, clean Android build). ## If New Architecture is disabled - **Android:** the Functions Gradle script fails the build with `New Architecture support is required for @react-native-firebase/functions`. - **iOS:** `pod install` fails with `RNFBFunctions requires New Architecture. Enable New Architecture to use this module`. ## API notes The JavaScript API (`functions()`, `httpsCallable`, modular helpers) is unchanged. v24 also adds [`httpsCallable().stream()`](/functions/usage) support, which relies on the TurboModule implementation. Other React Native Firebase modules still run on legacy architecture in v24, but old architecture support is deprecated project-wide and will be required for additional modules in future releases. ``` ### Migrating to v25 Source: https://rnfirebase.io/migrating-to-v25 ```mdx Version 25 completes the TypeScript alignment started in v24. Modular types across multiple packages now match the [firebase-js-sdk](https://firebase.google.com/docs/web/modular-upgrade) modular API as closely as possible. Runtime behavior is largely unchanged; **TypeScript consumers** and apps using the **modular API** are most affected. If you upgraded to v24 for Firestore only, see [Migrating to v24](/migrating-to-v24) first — Firestore breaking changes remain in v24. ## Table of contents - [Why we made these changes](/migrating-to-v25#why-we-made-these-changes) - [Agent-assisted migration](/migrating-to-v25#agent-assisted-migration) - [Who is affected](/migrating-to-v25#who-is-affected) - [General pattern](/migrating-to-v25#general-pattern) - [Tooling & native SDKs](/migrating-to-v25#tooling--native-sdks) - [Cloud Storage](/migrating-to-v25#cloud-storage) - [Realtime Database](/migrating-to-v25#realtime-database) - [Remote Config](/migrating-to-v25#remote-config) - [Performance Monitoring](/migrating-to-v25#performance-monitoring) - [Installations](/migrating-to-v25#installations) - [App Check](/migrating-to-v25#app-check) - [Firebase Auth](/migrating-to-v25#firebase-auth) - [Cloud Messaging](/migrating-to-v25#cloud-messaging) - [Automated migration checklist](/migrating-to-v25#automated-migration-checklist) ## Why we made these changes React Native Firebase aims to be a drop-in replacement for the [firebase-js-sdk](https://firebase.google.com/docs/web/setup) — with native extensions and performance where the platform allows. At the JavaScript level we have always tracked the modular API closely, but our TypeScript declarations had diverged: namespaces specific to React Native Firebase, instance-style typings, and helper names that did not match the SDK. v25 finishes aligning those types module by module. For you as a developer that means: - **Shared mental model** — code, examples, and AI assistance written for firebase-js-sdk modular APIs map directly to React Native Firebase. - **Safer refactors** — TypeScript catches incorrect imports and call shapes at compile time instead of at runtime. - **Easier cross-platform work** — the same typed modular surface works across web, React Native, and shared business logic. - **A clear path forward** — namespaced APIs remain for compatibility but modular root exports are the supported, typed source of truth. Most apps behave the same after updating package versions; the work is primarily import and type adjustments where TypeScript reports errors. ## Agent-assisted migration This guide is written to be **complete enough for an automated first pass**. We recommend feeding this document to your coding agent, then asking it to analyze your codebase against each relevant section below and produce a concrete change list (or PR) for the packages you use. The [Automated migration checklist](/migrating-to-v25#automated-migration-checklist) at the end is structured for that workflow. ## Who is affected | You use… | Likely impact | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | TypeScript + modular imports (`getX()`, `ref()`, etc.) | **High** — update imports and call patterns per package sections below | | TypeScript + namespaced API only (`firebase.storage().ref()`) | **Low–medium** — namespaced APIs remain; some types are deprecated or stricter | | JavaScript only, no type checking | **Low** — runtime is mostly compatible; deprecated APIs still work but emit warnings | ## General pattern Across v25 package migrations: 1. Import **modular types and functions from the package root**, not from `Firebase*Types` namespaces. 2. Prefer **free functions** (`getToken(appCheck)`, `trace(perf, name)`) over instance methods on service objects. 3. `Firebase*Types` namespaces remain for namespaced compatibility but are **deprecated** for new code. 4. Namespaced APIs (`firebase.auth()`, `storage()`) still work; modular is the typed source of truth. # Tooling & native SDKs **Commit:** `c8c1fc105` (SDK bump) | Change | Who | Action | | --------------------------------------------------------- | -------------- | ------------------------------------------- | | `firebase-ios-sdk` 12.12.0+ requires **Xcode 26.2+** | iOS developers | Upgrade Xcode before building v25 | | `firebase-android-sdk` 34.12.0, `firebase-js-sdk` 12.12.0 | All | Update lockfiles / pods as usual on upgrade | # Cloud Storage **PR:** [#8824](https://github.com/invertase/react-native-firebase/pull/8824) Modular Storage types now match firebase-js-sdk. The namespaced API (`firebase.storage()`, `FirebaseStorageTypes`) is preserved separately and deprecated for new code. ## Type & export changes | Before (v24 modular / types) | Now (v25) | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Instance methods on `Storage` / `StorageReference` in modular typings | Use root-level functions: `ref()`, `uploadBytes()`, `getDownloadURL()`, etc. | | `refFromURL(storage, url)` | `ref(storage, url)` — `ref()` accepts `gs://` and `https://` URLs | | `child(ref, path)` | `ref(ref, path)` | | Modular `toString(ref)` helper | `ref.toString()` on the reference | | `storage.statics.StringFormat`, `TaskEvent`, `TaskState` | Import `StringFormat`, `TaskEvent`, `TaskState` from package root | | `md5hash` in metadata | `md5Hash` (firebase-js-sdk spelling) | | Generic `Error` in task callbacks | `NativeFirebaseError` | | `ListOptions.pageToken` required `string` | `string \| null` (nullable, matching firebase-js-sdk) | ## Example: modular references and uploads ```js // Previously import { getStorage, refFromURL, child } from '@react-native-firebase/storage'; const storage = getStorage(); const fileRef = child(refFromURL(storage, 'gs://bucket/path/file.jpg'), 'thumb.jpg'); await fileRef.putFile(localPath); ``` ```js // Now import { getStorage, ref, putFile } from '@react-native-firebase/storage'; const storage = getStorage(); const fileRef = ref(ref(storage, 'gs://bucket/path/file.jpg'), 'thumb.jpg'); await putFile(fileRef, localPath); ``` ## Example: types and task constants ```js // Previously import { getStorage, FirebaseStorageTypes } from '@react-native-firebase/storage'; function onState(snapshot: FirebaseStorageTypes.TaskSnapshot) { if (snapshot.state === getStorage().app.storage().constructor.TaskState.RUNNING) { /* … */ } } ``` ```js // Now import { getStorage, ref, uploadBytesResumable, TaskState, type TaskSnapshot } from '@react-native-firebase/storage'; function onState(snapshot: TaskSnapshot) { if (snapshot.state === TaskState.RUNNING) { /* … */ } } ``` **RN-only helpers** (`putFile`, `writeToFile`) remain exported from the package root for native file paths. # Realtime Database **PR:** [#8977](https://github.com/invertase/react-native-firebase/pull/8977) Modular RTDB types (`DatabaseReference`, `Query`, `DataSnapshot`, `OnDisconnect`, `QueryConstraint`) no longer expose namespaced instance-style methods in public typings. Use function-based modular helpers. ## Breaking changes | Before | Now | | --------------------------------------------------------------- | ---------------------------------------------- | | `import { ServerValue } from '@react-native-firebase/database'` | Use `serverTimestamp()` and `increment(delta)` | | `await goOffline(db)` / `.then()` on `goOffline` | `goOffline(db)` returns `void` | | `await goOnline(db)` | `goOnline(db)` returns `void` | | `getServerTime(db)` treated as async | Returns synchronous `Date` | ## Example: server timestamps ```js // Previously import { getDatabase, ref, set, ServerValue } from '@react-native-firebase/database'; await set(ref(getDatabase(), 'posts/1'), { createdAt: ServerValue.TIMESTAMP }); ``` ```js // Now import { getDatabase, ref, set, serverTimestamp } from '@react-native-firebase/database'; await set(ref(getDatabase(), 'posts/1'), { createdAt: serverTimestamp() }); ``` ## Example: modular query helpers ```js // Previously — instance methods typed on modular references import { getDatabase, ref, query, orderByChild, equalTo, onValue, } from '@react-native-firebase/database'; const db = getDatabase(); const scoresRef = ref(db, 'scores'); const q = query(scoresRef, orderByChild('score'), equalTo(100)); onValue(q, snapshot => { /* … */ }); ``` Function-based helpers (`query`, `orderByChild`, `onValue`, etc.) are unchanged at runtime; **TypeScript** may now require you to stop calling deprecated instance methods (`.orderByChild()`, `.on()`) on modular-typed references and use the modular functions instead. Namespaced `firebase.database.ServerValue` remains available. # Remote Config **PR:** [#8972](https://github.com/invertase/react-native-firebase/pull/8972) Modular Remote Config now uses firebase-js-sdk type names and instance properties. ## Removed / renamed modular API | Removed (v24) | Replacement (v25) | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `fetch(remoteConfig, expirationDurationSeconds?)` | `fetchConfig(remoteConfig)` | | `setConfigSettings(remoteConfig, settings)` | `remoteConfig.settings = { minimumFetchIntervalMillis, fetchTimeoutMillis }` | | `setDefaults(remoteConfig, defaults)` | `remoteConfig.defaultConfig = { … }` | | `onConfigUpdated(remoteConfig, cb)` | `onConfigUpdate(remoteConfig, observer)` | | `fetchTimeMillis()`, `settings()`, `lastFetchStatus()` helpers | Read `remoteConfig.fetchTimeMillis`, `.settings`, `.lastFetchStatus` | | `RemoteConfigValue.value` / `.source` getters | `value.asString()` (etc.) and `value.getSource()` | | Exports: `LastFetchStatus`, `ValueSource`, `ConfigSettings`, `ConfigDefaults`, `ConfigValue`, `ConfigValues`, `LastFetchStatusType`, `RemoteConfigLogLevel` | Use `FetchStatus`, `ValueSource`, `Value`, `RemoteConfigSettings`, `LogLevel` | **Settings field rename:** modular `RemoteConfigSettings` uses `fetchTimeoutMillis` (firebase-js-sdk), not the older React Native Firebase style `fetchTimeMillis` on the modular surface. ## Example: fetch and read values ```js // Previously import { getRemoteConfig, fetch, activate, getValue, FirebaseRemoteConfigTypes, } from '@react-native-firebase/remote-config'; const rc = getRemoteConfig(); await fetch(rc, 3600); await activate(rc); const flag = getValue(rc, 'feature_enabled'); console.log(flag.value, flag.source); ``` ```js // Now import { getRemoteConfig, fetchConfig, activate, getValue, type Value, } from '@react-native-firebase/remote-config'; const rc = getRemoteConfig(); rc.settings = { minimumFetchIntervalMillis: 3600000, fetchTimeoutMillis: 60000, }; await fetchConfig(rc); await activate(rc); const flag: Value = getValue(rc, 'feature_enabled'); console.log(flag.asString(), flag.getSource()); ``` # Performance Monitoring **PR:** `4aedfe883` (TypeScript migration) ## Breaking changes | Before | Now | | ------------------------------------------------------ | ----------------------------------------------------------------------- | | `await initializePerformance(app, settings)` | Returns `FirebasePerformance` **synchronously** | | `perf.newTrace(name)`, `perf.startTrace(name)` | `trace(perf, name)` | | `perf.newHttpMetric(url, method)` | `httpMetric(perf, url, method)` | | `perf.newScreenTrace(name)` / `startScreenTrace(name)` | `newScreenTrace(perf, name)` / `startScreenTrace(perf, name)` | | `perf.setPerformanceCollectionEnabled(bool)` | `perf.dataCollectionEnabled = bool` | | `PerformanceSettings` React Native Firebase shape | `{ dataCollectionEnabled?, instrumentationEnabled? }` (firebase-js-sdk) | | `trace.getAttribute(key)` typed as `string \| null` | `string \| undefined` | **RN-only exports retained:** `httpMetric`, `newScreenTrace`, `startScreenTrace`, `HttpMethod`, `HttpMetric`, `ScreenTrace`. ## Example ```js // Previously import { getPerformance } from '@react-native-firebase/perf'; const perf = getPerformance(); const t = perf.newTrace('load_screen'); await t.start(); ``` ```js // Now import { getPerformance, trace } from '@react-native-firebase/perf'; const perf = getPerformance(); const t = trace(perf, 'load_screen'); await t.start(); ``` # Installations **PR:** `739a4ca36` (TypeScript migration) Modular `getInstallations()` returns a firebase-js-sdk-shaped `Installations` object exposing only `app`. Use modular helper functions instead of instance methods. ## Breaking changes | Before | Now | | -------------------------- | --------------------------------------------------------------- | | `installations.getId()` | `getId(installations)` | | `installations.getToken()` | `getToken(installations)` | | `installations.delete()` | `deleteInstallations(installations)` — argument is **required** | ## Example ```js // Previously import { getInstallations } from '@react-native-firebase/installations'; const installations = getInstallations(); const id = await installations.getId(); ``` ```js // Now import { getInstallations, getId } from '@react-native-firebase/installations'; const installations = getInstallations(); const id = await getId(installations); ``` Namespaced `firebase.installations()` / `FirebaseInstallationsTypes` remain available (deprecated). # App Check **PR:** [#8889](https://github.com/invertase/react-native-firebase/pull/8889) Version 25 aligns App Check's modular exports more closely with the Firebase JS SDK. If your app uses the modular API, import App Check types and helpers directly from `@react-native-firebase/app-check` instead of routing modular code through `FirebaseAppCheckTypes`. The most common updates are: - Import modular helpers such as `initializeAppCheck`, `getToken`, `getLimitedUseToken`, `setTokenAutoRefreshEnabled`, and `onTokenChanged` from the package root. - Import modular types such as `AppCheck` and `AppCheckTokenResult` from the package root. - `FirebaseApp` is no longer exported from `@react-native-firebase/app-check`; import it from `@react-native-firebase/app`. - `FirebaseAppCheckTypes` is **type-only** — use `import type { FirebaseAppCheckTypes }`. - Modular `AppCheck` has no instance methods (matching firebase-js-sdk); use free functions. - `onTokenChanged` callback receives `AppCheckTokenResult`, not `AppCheckListenerResult`. - Keep using `ReactNativeFirebaseAppCheckProvider` on React Native when you need native provider selection for Android / Apple / web. ```js // Previously import appCheck, { FirebaseAppCheckTypes } from '@react-native-firebase/app-check'; const instance = appCheck(); instance.getToken().then((result: FirebaseAppCheckTypes.AppCheckTokenResult) => { console.log(result.token); }); ``` ```js // Now import { getApp } from '@react-native-firebase/app'; import { AppCheckTokenResult, ReactNativeFirebaseAppCheckProvider, initializeAppCheck, getToken, } from '@react-native-firebase/app-check'; const provider = new ReactNativeFirebaseAppCheckProvider(); provider.configure({ android: { provider: __DEV__ ? 'debug' : 'playIntegrity', }, apple: { provider: __DEV__ ? 'debug' : 'appAttestWithDeviceCheckFallback', }, web: { provider: 'reCaptchaV3', siteKey: 'your-recaptcha-site-key', }, }); const appCheck = await initializeAppCheck(getApp(), { provider, isTokenAutoRefreshEnabled: true, }); const result: AppCheckTokenResult = await getToken(appCheck); console.log(result.token); ``` If you do not need to reuse a provider instance, you can now also pass the React Native provider configuration inline through `providerOptions`: ```js import { getApp } from '@react-native-firebase/app'; import { initializeAppCheck } from '@react-native-firebase/app-check'; await initializeAppCheck(getApp(), { provider: { providerOptions: { android: { provider: __DEV__ ? 'debug' : 'playIntegrity', }, apple: { provider: __DEV__ ? 'debug' : 'appAttestWithDeviceCheckFallback', }, web: { provider: 'reCaptchaV3', siteKey: 'your-recaptcha-site-key', }, }, }, isTokenAutoRefreshEnabled: true, }); ``` # Firebase Auth **PR:** [#8991](https://github.com/invertase/react-native-firebase/pull/8991) Version 25 aligns `@react-native-firebase/auth` TypeScript types with the firebase-js-sdk modular API. Runtime behavior is largely unchanged, but TypeScript consumers should review the following breaking changes. For maintainers and coding agents: the living triage matrix is [`okf-bundle/packages/auth/compare-types-triage.md`](https://github.com/invertase/react-native-firebase/blob/main/okf-bundle/packages/auth/compare-types-triage.md). Run `yarn compare:types auth` after public API edits and update `.github/scripts/compare-types/configs/auth.ts` when differences are intentional. ## Platform matrix (read before changing Auth) | Context | `Platform.OS` | Backend | Notes | | ---------------- | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **iOS/Android** | `ios`, `android` | Native Firebase Auth SDK | Native bridge types (`verifyPhoneNumber` listener, Multi-Factor Authentication overloads, async `isSignInWithEmailLink`) | | **Other/Hermes** | e.g. macOS, Windows RN | firebase-js-sdk via the auth web bridge | No DOM; MFA/TOTP covered by `tests/local-tests` | | **Other/Web** | browser embedding | firebase-js-sdk | DOM APIs (reCAPTCHA, redirect) possible but not all delegated yet | When a symbol is documented as **iOS/Android only**, do not assume it throws or is missing on Other without checking the web bridge. When compare:types signatures match but runtime differs, document in triage / this guide (not necessarily in `differentShape`). ## Modular types Import modular types directly from `@react-native-firebase/auth` instead of `FirebaseAuthTypes` where possible. The namespaced `FirebaseAuthTypes` namespace remains available but is deprecated. For auth errors, use `NativeFirebaseAuthError` (or the modular `AuthError` interface) instead of expecting a firebase-js-sdk `AuthError` class export — React Native Firebase does not re-export the firebase-js-sdk error class. ## Removed modular export - `initializeRecaptchaConfig` is not exported. React Native Firebase uses native SDK Phone Auth verification rather than the browser reCAPTCHA bootstrap flow. ## Deprecated provider helpers The following RN Firebase-specific provider classes are **deprecated in v25**. Use `OAuthProvider` instead (matching firebase-js-sdk): | Deprecated | Replacement | | ------------------- | ---------------------------------------------- | | `AppleAuthProvider` | `new OAuthProvider('apple.com')` | | `OIDCAuthProvider` | `new OAuthProvider('oidc.')` | | `OIDCProvider` | `OAuthProvider` | ```js // Previously (deprecated) import { AppleAuthProvider } from '@react-native-firebase/auth'; const credential = AppleAuthProvider.credential(idToken, rawNonce); // Now import { OAuthProvider } from '@react-native-firebase/auth'; const provider = new OAuthProvider('apple.com'); const credential = provider.credential({ idToken, rawNonce }); ``` ```js // Previously (deprecated) import { OIDCAuthProvider } from '@react-native-firebase/auth'; const credential = OIDCAuthProvider.credential('sample-provider', idToken, accessToken); // Now import { OAuthProvider } from '@react-native-firebase/auth'; const provider = new OAuthProvider('oidc.sample-provider'); const credential = provider.credential({ idToken, accessToken }); ``` `AppleAuthProvider` and `OIDCAuthProvider` remain exported for compatibility but will be removed in a future major release. ## Action code URL parsing `ActionCodeURL.parseLink` and `parseActionCodeURL` are implemented as **synchronous** pure URL parsers (matching firebase-js-sdk). They work on all platforms without calling the native bridge. ## Signature changes - `isSignInWithEmailLink(auth, emailLink)` — returns `Promise` on iOS/Android (native bridge). The firebase-js-sdk returns a synchronous `boolean`. Port web code with `await isSignInWithEmailLink(auth, link)` (or `.then(...)`). - `sendSignInLinkToEmail(auth, email, actionCodeSettings)` — `actionCodeSettings` is **required** in the modular API (matching firebase-js-sdk). - **Namespaced email link (react-native-firebase convenience):** `firebase.auth().sendSignInLinkToEmail(email, settings?)` still accepts omitted settings. Internally `_resolveActionCodeSettings()` defaults `url` from `app.options.authDomain` and `handleCodeInApp: true`. This is **not** platform-specific — only namespaced vs modular. Do not “fix” modular to match namespaced defaults. - `signInWithEmailLink(auth, email, emailLink?)` — the third argument is optional, matching firebase-js-sdk. - `signInWithRedirect` / `linkWithRedirect` — return `Promise` on native because provider flows resolve immediately with credentials instead of following the browser redirect contract. - `reauthenticateWithRedirect` — returns `Promise` on native while still updating `currentUser` after the native provider flow completes. - `connectAuthEmulator(auth, url, options?)` — when `options` is provided, `disableWarnings` is required (matching firebase-js-sdk). ## Web APIs with matching types but different native runtime (iOS/Android) These modular helpers are exported for firebase-js-sdk API parity. **On iOS/Android they throw synchronously** (or are not applicable) because native SDKs do not implement the browser persistence, redirect, or reCAPTCHA phone-link flows. Types match the firebase-js-sdk; behavior does not — see API reference `@remarks` on each symbol. | API | Native iOS/Android behavior | | ------------------------------- | ----------------------------------------------------------------------------------------------------- | | `getRedirectResult` | Always throws — use immediate `UserCredential` from `signInWithRedirect` / `linkWithRedirect` instead | | `setPersistence` | Always throws — native SDKs manage auth state | | `useDeviceLanguage` | Always throws | | `revokeAccessToken` | Always throws | | `linkWithPhoneNumber` | Always throws | | `reauthenticateWithPhoneNumber` | Always throws | `initializeAuth(app, deps?)` accepts the firebase-js-sdk `Dependencies` type for API parity but **ignores** persistence, popup redirect resolver, and error-map dependencies on iOS/Android (see below). ## Phone Auth (iOS/Android) - `verifyPhoneNumber(auth, phoneNumber, ...)` — **iOS/Android only** native listener flow (force-resend, auto-verification callbacks). On Other platforms use `signInWithPhoneNumber` / firebase-js-sdk `PhoneAuthProvider` instead. - `signInWithPhoneNumber(auth, phoneNumber, appVerifier?)` — modular API no longer accepts the former `forceResend` fourth argument from React Native Firebase; use `verifyPhoneNumber` when you need the native listener / force-resend behavior. ## Sign in with Apple - `revokeToken(auth, authorizationCode)` — React Native Firebase-specific modular helper for Apple's account-deletion requirement. **Supported on iOS** (native `revokeTokenWithAuthorizationCode`). Android and Web bridges resolve without performing revocation. - Do not confuse with `revokeAccessToken` — that is firebase-js-sdk web-only OAuth token revocation and always throws on iOS/Android. - The namespaced `firebase.auth().revokeToken(authorizationCode)` API remains available but is deprecated. ## Auth instance surface - `auth.tenantId = 'tenant-id'` is now supported (delegates to `setTenantId`). - `auth.authStateReady()`, `auth.beforeAuthStateChanged(...)`, `auth.emulatorConfig`, and `auth.updateCurrentUser(user)` are implemented on the Auth instance. - **`auth.config` runtime split (types unified):** Declarations match firebase-js-sdk `Config`, but runtime differs by platform: - **iOS/Android:** always `{}` — native SDKs do not expose the web config object. - **Other (Hermes/Web):** firebase-js-sdk can populate `auth.config`, but React Native Firebase does not delegate this yet. Do not read `auth.config` on native expecting `apiKey` / `authDomain`; use `getCustomAuthDomain(auth)` on iOS/Android or app options on Other until delegation lands. ## Credential providers Provider credential factories return firebase-js-sdk-shaped credential **classes** (`OAuthCredential`, not internal type aliases) with `toJSON()` and `static fromJSON()` where applicable. - `OAuthCredential.rawNonce` — used for Sign in with Apple and Facebook limited-login flows (matches firebase-js-sdk credential options). OAuth 1.0 token secrets (e.g. Twitter) use the inherited `AuthCredential.secret` bridge field instead of `rawNonce`. - RN Firebase credentials retain internal `token` / `secret` bridge fields required by the native modules (implementation detail; omitted from generated API reference). - `OAuthProvider.credentialFromResult` / `credentialFromError` and sibling provider helpers (`GoogleAuthProvider`, `GithubAuthProvider`, `TwitterAuthProvider`, `FacebookAuthProvider`, `PhoneAuthProvider`) **always return `null` at runtime today**. Declared types match firebase-js-sdk. - **iOS/Android:** no native extraction planned — credentials are not recoverable from native provider results. - **Other/Hermes:** not delegated (firebase-js-sdk credential recovery is tied to popup/redirect flows). - **Other/Web:** future implementation should delegate to firebase-js-sdk in the auth web bridge — do not invest in native iOS/Android bridge work for this. - `GoogleAuthProvider.credential()` throws when both `idToken` and `accessToken` are absent (matching firebase-js-sdk). - `FacebookAuthProvider.credential(token)` matches firebase-js-sdk. React Native Firebase also exports `credential(token, secret)` for Facebook limited-login nonce behavior — an intentional extension documented in compare:types. ## Multi-factor - Modular `multiFactor(user)` now uses the user's auth instance instead of always calling `getAuth()`, fixing secondary Firebase app usage. - Namespaced `firebase.auth().multiFactor(user)` now correctly validates that `user` is the `currentUser`. - `TotpSecret.generateQrCodeUrl()` returns `Promise` on iOS/Android (native bridge). firebase-js-sdk returns a synchronous string. - `TotpSecret.openInOtpApp(qrCodeUrl)` — RN-only helper that deep-links into a One-Time Password authenticator app; not part of firebase-js-sdk. - **Other platforms:** MFA and TOTP flows are exercised in `tests/local-tests` via the firebase-js-sdk bridge — not a gap to “port” from native overloads. ## Normalized modular return values Modular helpers normalize several return shapes toward firebase-js-sdk: - `UserCredential` includes top-level `providerId` and `operationType`. - When the native bridge returns federated metadata, `additionalUserInfo` is attached as an **enumerable** property on modular `UserCredential` objects. Core fields match firebase-js-sdk (`isNewUser`, `profile`, `providerId`, `username`); extra native keys are copied onto the object for backwards compatibility. - Use `getAdditionalUserInfo(userCredential)` for the canonical read (returns `AdditionalUserInfo | null`, same shape as firebase-js-sdk). For TypeScript when you need provider-specific native extras, cast to `AdditionalUserInfoNative` (`AdditionalUserInfo & Record`). - `checkActionCode` normalizes `fromEmail` to `previousEmail` and coerces multi-factor info shapes. - `signInWithPhoneNumber` wraps confirmation results and validates `verificationId` presence. ## `initializeAuth` `initializeAuth(app, deps?)` accepts the firebase-js-sdk `Dependencies` type for API parity, but persistence, popup redirect resolver, and error-map dependencies are ignored because native SDKs manage auth state. ## Namespaced type adjustments - `FirebaseAuthTypes.UserInfo` profile fields can be null. - `firebase.auth().config` is typed as `Record` on the namespaced API (stricter than modular `auth.config`). # Cloud Messaging **PR:** [#9053](https://github.com/invertase/react-native-firebase/pull/9053) Notification **permission** APIs in `@react-native-firebase/messaging` are **deprecated** in v25. They are not Firebase-specific; dedicated libraries handle permissions more completely. | Deprecated API | Use instead | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requestPermission(messaging, …)` | [`react-native-permissions`](https://github.com/zoontek/react-native-permissions) or [`expo-notifications`](https://docs.expo.dev/versions/latest/sdk/notifications/) (Expo) | | `hasPermission(messaging)` | Same | | `registerDeviceForRemoteMessages(messaging)` | Same (platform setup) | | `isDeviceRegisteredForRemoteMessages(messaging)` | Same | | `AuthorizationStatus` static on messaging | Permission library equivalents | These APIs still work at runtime but are marked `@deprecated` in TypeScript and documented for removal in a future major release. See [#6283](https://github.com/invertase/react-native-firebase/issues/6283). # Automated migration checklist Use this section when running scripted or agent-assisted upgrades from v24 → v25. ## 1. Upgrade dependencies ```bash # Bump all @react-native-firebase/* packages to v25 together (monorepo versions are aligned) yarn add @react-native-firebase/app@^25.0.0 … cd ios && pod install ``` Ensure **Xcode 26.2+** for iOS builds. ## 2. Fix TypeScript by package For each `@react-native-firebase/` in your imports: | Package | Search for | Replace with | | --------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- | | `storage` | `refFromURL`, `child(`, `FirebaseStorageTypes`, `.statics.` | `ref()`, root imports, modular functions | | `database` | `ServerValue`, `.orderByChild(`, `await goOffline` | `serverTimestamp()`, `query`/`orderByChild` functions, sync `goOffline` | | `remote-config` | `fetch(`, `setDefaults`, `setConfigSettings`, `.value`, `.source` | `fetchConfig`, `defaultConfig`/`settings` props, `asString()`/`getSource()` | | `perf` | `.newTrace`, `.newHttpMetric`, `await initializePerformance` | `trace()`, `httpMetric()`, sync `initializePerformance` | | `installations` | `.getId()`, `.getToken()`, `.delete()` | `getId()`, `getToken()`, `deleteInstallations()` | | `app-check` | `appCheck().getToken()`, value import of `FirebaseAppCheckTypes` | `initializeAppCheck` + `getToken()`, `import type` | | `auth` | `FirebaseAuthTypes`, `AppleAuthProvider`, `OIDCAuthProvider` | Root modular types, `OAuthProvider` | | `messaging` | `requestPermission`, `hasPermission` | `react-native-permissions` / `expo-notifications` | ## 3. Validate ```bash yarn compile # root TypeScript compile yarn compare:types # maintainers: per-package drift vs firebase-js-sdk yarn tests:jest packages//__tests__ # targeted tests for touched packages ``` ## 4. Namespaced API users If you only use `firebase.storage()`, `firebase.auth()`, etc. and do not import modular types: - You may see **deprecation warnings** in IDE / `@deprecated` JSDoc. - Plan a gradual move to modular imports; namespaced removal is planned for a future major release. - Runtime behavior should remain compatible for most flows. ## Related PRs (v25 breaking changes since v24.0.0) | Package | PR / commit | | ------------------------ | --------------------------------------------------------------------- | | Storage | [#8824](https://github.com/invertase/react-native-firebase/pull/8824) | | App Check | [#8889](https://github.com/invertase/react-native-firebase/pull/8889) | | Remote Config | [#8972](https://github.com/invertase/react-native-firebase/pull/8972) | | Realtime Database | [#8977](https://github.com/invertase/react-native-firebase/pull/8977) | | Performance | `4aedfe883` | | Installations | `739a4ca36` | | Auth | [#8991](https://github.com/invertase/react-native-firebase/pull/8991) | | Messaging (deprecations) | [#9053](https://github.com/invertase/react-native-firebase/pull/9053) | | Native SDKs (Xcode) | `c8c1fc105` | Packages migrated to TypeScript **without** public API breaks in v25: `@react-native-firebase/app-distribution` ([#8967](https://github.com/invertase/react-native-firebase/pull/8967)), `@react-native-firebase/ml` ([#9005](https://github.com/invertase/react-native-firebase/pull/9005)). ``` ### Migrating to v26 Source: https://rnfirebase.io/migrating-to-v26 ```mdx Version 26 removes the deprecated **namespaced** JavaScript API from selected packages. Each migrated package is **modular-only**: use `getX(app?)` and root-level helper functions from the package entry point. Namespaced default exports, `firebase.()`, and `Firebase*Types` namespaces are removed from those packages. If you are upgrading from v24 or earlier, complete [Migrating to v25](/migrating-to-v25) first — v25 TypeScript alignment changes still apply. ## Table of contents - [New Architecture requirement](/migrating-to-v26#new-architecture-requirement) - [Platform behavior differences](/migrating-to-v26#platform-behavior-differences) - [firebase-js-sdk API parity improvements](/migrating-to-v26#firebase-js-sdk-api-parity-improvements) - [General pattern](/migrating-to-v26#general-pattern) - [App](/migrating-to-v26#app) - [Machine Learning (ML)](/migrating-to-v26#machine-learning-ml) - [In-App Messaging](/migrating-to-v26#in-app-messaging) - [Installations](/migrating-to-v26#installations) - [Cloud Messaging](/migrating-to-v26#cloud-messaging) - [iOS APNs registration (ARM64 Simulator + new Promise rejections)](/migrating-to-v26#ios-apns-registration-arm64-simulator--new-promise-rejections) - [App Distribution](/migrating-to-v26#app-distribution) - [Cloud Functions](/migrating-to-v26#cloud-functions) - [Performance Monitoring](/migrating-to-v26#performance-monitoring) - [App Check](/migrating-to-v26#app-check) - [Analytics](/migrating-to-v26#analytics) - [Remote Config](/migrating-to-v26#remote-config) - [Crashlytics](/migrating-to-v26#crashlytics) - [Realtime Database](/migrating-to-v26#realtime-database) - [Cloud Storage](/migrating-to-v26#cloud-storage) - [Authentication](/migrating-to-v26#authentication) - [Cloud Firestore](/migrating-to-v26#cloud-firestore) - [Automated migration checklist](/migrating-to-v26#automated-migration-checklist) ## New Architecture requirement From v26 onward, **every React Native Firebase package with a native bridge** is implemented as a **Codegen TurboModule** and **requires React Native's New Architecture**. The legacy bridge modules were removed in the coordinated v26 break. If you cannot enable New Architecture yet, **stay on v25** (or v23 if you still depend on legacy-architecture Cloud Functions — see below). ### Exceptions (no New Architecture requirement) | Package | Why | | --------------------------------- | ------------------------------------------------------------------------------------ | | `@react-native-firebase/ai` | Pure JavaScript — uses the firebase-js-sdk web interop layer; no native TurboModule. | | `@react-native-firebase/vertexai` | Pure JavaScript — same as `ai`; deprecated in favor of `@react-native-firebase/ai`. | ### Cloud Functions (already required since v24) `@react-native-firebase/functions` has required New Architecture **since v24** ([Migrating to v24 — Cloud Functions](/migrating-to-v24#cloud-functions)). v26 extends the same requirement to all remaining native modules. ### Enable New Architecture **React Native CLI (Android)** — set in `android/gradle.properties`: ```properties newArchEnabled=true ``` **React Native CLI (iOS)** — New Architecture is enabled when `RCT_NEW_ARCH_ENABLED=1` during `pod install` (React Native sets this from `newArchEnabled` on recent templates). Follow the [React Native New Architecture guide](https://reactnative.dev/docs/the-new-architecture/landing-page) for your RN version. **Expo** — enable in your app config (Expo SDK 52+): ```json { "expo": { "newArchEnabled": true } } ``` Rebuild native projects after changing this (`pod install`, clean Android build). ### If New Architecture is disabled Native builds fail early with explicit guards: - **Android:** Gradle scripts print `New Architecture support is required for @react-native-firebase/` and fail the build. - **iOS:** `pod install` fails with ` requires New Architecture. Enable New Architecture to use this module`. ### Platform behavior differences When migrating from firebase-js-sdk web examples, watch for these high-impact runtime divergences: {/* prettier-ignore */} | Area | firebase-js-sdk (web) | React Native Firebase | | --- | --- | --- | | **Auth** | Browser persistence, redirects, reCAPTCHA, `revokeAccessToken`, `useDeviceLanguage`, `linkWithPhoneNumber` / `reauthenticateWithPhoneNumber` | Native iOS/Android SDKs manage persistence. Several web-only helpers **throw synchronously** on React Native (`setPersistence`, `getRedirectResult`, `revokeAccessToken`, `useDeviceLanguage`, `linkWithPhoneNumber`, `reauthenticateWithPhoneNumber`). Use native provider flows instead. | | **Analytics** | Cross-platform modular API | On-device conversion measurement helpers (`initiateOnDeviceConversionMeasurement*`) are **iOS only**; on Android and web the JS layer resolves without calling native (no-op). `logTransaction` (verified iOS in-app purchase events) is **iOS only** and **rejects** on other platforms. | | **Realtime Database** | `goOnline` / `goOffline` are synchronous; web transport toggles | `goOnline` / `goOffline` are **synchronous** through TurboModules, matching firebase-js-sdk. `getServerTime`, `setPersistenceEnabled`, and `setPersistenceCacheSizeBytes` are RN-specific. `forceLongPolling` / `forceWebSockets` **throw** — transport is native-controlled. | | **Phone Number Verification** | N/A (Android SDK only) | **Android only** — all entry points throw on iOS and Web. | | **Cloud Storage** | `uploadBytes` / `uploadString` from JS blobs; upload task controls return sync `boolean` | `putFile` and `writeToFile` are **native-only** file-path APIs. `UploadTask.pause()` / `.resume()` / `.cancel()` also return sync `boolean` values through native TurboModules. | | **Cloud Messaging** | Web push / service-worker surface | FCM token lifecycle, permissions, background handlers, and **APNs token APIs are iOS only**. Event delivery still uses the legacy native event proxy during the TurboModule migration; behavior matches pre-v26 releases but will change when Codegen events land in a future release. | | **Remote Config** | `reset()` clears server and local state | `reset()` is **Android only** — iOS does not clear activated, fetched, or default Remote Config values. `setDefaultsFromResource` loads from native resource files (`.plist` / XML). | | **Performance** | `initializePerformance` returns synchronously; trace `start`/`stop` are sync | `initializePerformance` is **synchronous** on RN (applies settings to the native instance). Trace, HTTP metric, and screen trace `start`/`stop` are **synchronous** through TurboModules, matching firebase-js-sdk. | | **Firestore** | IndexedDB persistence, `memoryLocalCache`, `persistentLocalCache`, FieldValue `maximum()` / `minimum()` sentinels | Local cache factories and IndexedDB APIs are **web only**. Persistence is controlled by the native Firestore SDK. `initializeFirestore` returns **`Firestore` synchronously**. FieldValue `maximum()` / `minimum()` are not exported yet because iOS SDK 12.15.0 lacks matching native factories. | | **App Check** | reCAPTCHA version 3 / Enterprise web providers | Use `ReactNativeFirebaseAppCheckProvider` for Device Check, App Attest, Play Integrity, etc. Web reCAPTCHA provider classes have **no RN equivalent**. | | **RN-native-only modules** | No web SDK | `crashlytics`, `in-app-messaging`, `app-distribution`, and `ml` are **React Native only** — no firebase-js-sdk modular surface. | Per-package notes also appear in each module's [usage](/) page under **Platform support**. ## firebase-js-sdk API parity improvements v26 aligns React Native Firebase modular types and several runtime signatures with **firebase-js-sdk** where TurboModules removed bridge-forced `Promise` wrappers. Use this section when porting web SDK examples or when scripted upgrades hit TypeScript or runtime errors. **Migration rule:** If a method below is **sync**, remove `await` and any `.then()` / `.catch()` chain on its return value — sync APIs return `void` or a value directly; calling `.then()` on `void` throws at runtime. ### Synchronous APIs enabled by TurboModules {/* prettier-ignore */} | Method | Before (pre-v26 / legacy bridge) | After (v26) | Notes | | ------ | -------------------------------- | ----------- | ----- | | `registerVersion(library, version, variant?)` | `Promise` (web) | `void` — throws on RN | Web-only on RN; remove `await` if copied from web samples | | `isSignInWithEmailLink(auth, emailLink)` | `Promise` | `boolean` | Remove `await` | | `TotpSecret.generateQrCodeUrl(accountName?, issuer?)` | `Promise` | `string` | Remove `await`; omitted args default from current user / app name | | `trace(…).start()` / `.stop()` | `Promise` | `void` | Remove `await` on perf trace lifecycle | | `httpMetric(…).start()` / `.stop()` | `Promise` | `void` | Same as traces | | `ScreenTrace.start()` / `.stop()` | `Promise` | `void` | Same as traces | | `startScreenTrace(performance, screenName)` | `Promise` | `ScreenTrace` | Remove `await` | | `goOnline(db)` / `goOffline(db)` | `Promise` | `void` | Remove `await` | | `UploadTask.pause()` / `.resume()` / `.cancel()` | `Promise` | `boolean` | Remove `await`; use the returned boolean directly | ### Type parity improvements {/* prettier-ignore */} | Export / method | Before | After | Notes | | --------------- | ------ | ----- | ----- | | `onSnapshotsInSync(firestore, observer)` | `next?: () => void`; `error?: Error` | `next?: (value: void) => void`; `error?: FirestoreError` | Callback overload `onSnapshotsInSync(firestore, () => {})` unchanged | | `uploadBytes(ref, data, metadata?)` | Return type `TaskResult` | `UploadResult` | Alias rename only | | `uploadBytesResumable(ref, data, metadata?)` | Return type `Task` | `UploadTask` | Alias rename only | | Storage / Remote Config error callbacks | `NativeFirebaseError` | `FirebaseError` / `StorageError` | `NativeFirebaseError` remains assignable to `FirebaseError` | | `AppCheckTokenListener` | Not exported | Exported type alias | Matches firebase-js-sdk observer typing | | `FunctionsError`, `FunctionsErrorCodeCore` | Missing or misaligned | Exported / aligned | Registry + compare-types config | | `firestore/pipelines` (`StageOptions`, `TimeGranularity`, `isType`, …) | Declaration drift | Aligned to SDK `.d.ts` | Type-only; no call-shape change | ### Synchronous modular return values {/* prettier-ignore */} | Method | Before | After | Notes | | ------ | ------ | ----- | ----- | | `logEvent(analytics, …)` | `Promise` | `void` | Fire-and-forget; remove `await` / `.then()` | | `initializeAppCheck(app?, options?)` | `Promise` | `AppCheck` | Returns handle immediately; provider setup continues natively | | `initializeFirestore(app, settings, databaseId?)` | `Promise` | `Firestore` | Returns instance immediately; `settings()` runs on native bridge | | `getRemoteConfig(app?, options?)` | `(app?)` only | `(app?, options?: RemoteConfigOptions)` | `options` accepted for parity; no-op on native | | `aggregateFieldEqual()` | Not exported | Exported | Aggregate query helper | | `LastFetchStatus` literals | — | — | **Unchanged** — native still uses `no_fetch_yet` / `throttled` (documented drift) | ### Firestore parity additions {/* prettier-ignore */} | Export / method | Before | After | Notes | | --------------- | ------ | ----- | ----- | | `TransactionOptions` | Not exported | Exported | Type for transaction retry options | | `runTransaction(firestore, updateFunction, options?)` | No options argument | Accepts `options?: TransactionOptions` | `{ maxAttempts?: number }` on native iOS and Android; omitted options use the SDK default of **5** retries; explicit values **< 1** throw `Max attempts must be at least 1` (firebase-js-sdk parity) | | `aggregateQuerySnapshotEqual()` | Not exported | Exported | Aggregate query snapshot equality helper, alongside `aggregateFieldEqual()` | | `maximum(n)` / `minimum(n)` FieldValue sentinels | Exported by firebase-js-sdk 12.15.0 | Not exported by RNFB yet | Android SDK 34.15.0 has native factories, but iOS Firebase Firestore SDK 12.15.0 does not; RNFB waits for cross-platform parity | ### Observer and Promise pitfalls {/* prettier-ignore */} | Pitfall | Symptom | Fix | | ------- | ------- | --- | | `.then()` on sync API | `TypeError: … .then is not a function` | Use direct call: `logEvent(…)` not `logEvent(…).then(…)` | | `await` on sync API | Unnecessary microtask delay; misleading types in strict TS | Drop `await` where the table above marks the API sync | | `onConfigUpdate(remoteConfig, observer)` | Runtime throw: observer must include **both** `next` and `error` functions | Pass `{ next: (update) => {…}, error: (err) => {…} }` — do not omit `error` | | `onSnapshotsInSync` observer form | Type error on `error` callback | Type `error` as `(error: FirestoreError) => void`, or use the `() => void` callback overload | | `runTransaction(..., { maxAttempts: 0 })` or negative | Runtime throw: `Max attempts must be at least 1` | Omit `options` for the default **5** attempts, or pass `maxAttempts: 1` or higher | ## General pattern For each package listed in this guide: 1. Remove default export / `firebase.()` usage — import modular helpers from the package root. 2. Replace `Firebase*Types` namespace imports with root types (`InAppMessaging`, `Installations`, `FirebaseML`, etc.). 3. Prefer free functions (`getId(installations)`, `setMessagesDisplaySuppressed(inAppMessaging, enabled)`) over instance methods on service objects. **Modular-only in v26:** `@react-native-firebase/app`, `@react-native-firebase/ml`, `@react-native-firebase/in-app-messaging`, `@react-native-firebase/installations`, `@react-native-firebase/messaging`, `@react-native-firebase/app-distribution`, `@react-native-firebase/functions`, `@react-native-firebase/perf`, `@react-native-firebase/app-check`, `@react-native-firebase/remote-config`, `@react-native-firebase/crashlytics`, `@react-native-firebase/database`, `@react-native-firebase/storage`, `@react-native-firebase/analytics`, `@react-native-firebase/auth`, and `@react-native-firebase/firestore`. Other packages may still expose the namespaced API with deprecation warnings; modular imports remain the supported path. # App The namespaced API for `@react-native-firebase/app` has been **removed**. This package is **modular-only** — use named exports such as `getApp()`, `initializeApp()`, and `getUtils()`. ## Removed namespaced API | Removed | Replacement (modular) | | ----------------------------------------------------- | ------------------------------------------------------------------- | | Default export `firebase` | Named exports from `@react-native-firebase/app` | | `firebase.app(name?)` | `getApp(name?)` | | `firebase.apps` | `getApps()` | | `firebase.initializeApp(options, name?)` | `initializeApp(options, name?)` | | `firebase.utils(app?)` | `getUtils(app?)` | | `firebase.utils.FilePath` | `FilePath` (named export) | | `firebase.SDK_VERSION` | `SDK_VERSION` (named export) | | `firebase.setLogLevel(...)` | `setLogLevel(...)` | | `firebase.()` accessors on the default export | Import modular helpers from each `@react-native-firebase/*` package | ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; firebase.app().name; firebase.initializeApp(options, 'secondary'); firebase.utils().FilePath.DOCUMENT_DIRECTORY; ``` ```js // Now import { getApp, initializeApp, getUtils, FilePath } from '@react-native-firebase/app'; getApp().name; initializeApp(options, 'secondary'); getUtils().FilePath.DOCUMENT_DIRECTORY; // or FilePath.DOCUMENT_DIRECTORY; ``` ## Breaking: Android Play Services availability Promise behavior On Android, `makePlayServicesAvailable()` now rejects when the Play Services availability task is canceled or fails. Previously, the call always resolved even when the update flow was not completed. Update callers to handle rejection: ```js import { getUtils } from '@react-native-firebase/app'; try { await getUtils().makePlayServicesAvailable(); } catch (error) { // Handle canceled or failed Play Services update } ``` # Machine Learning (ML) The namespaced API for `@react-native-firebase/ml` has been **removed**. This package is **modular-only** — use `getML(app?)`. ## Removed namespaced API | Removed | Replacement (modular) | | --------------------------- | ------------------------------------- | | `firebase.ml()` | `getML()` or `getML(app)` | | Default export `ml()` | `getML()` or `getML(app)` | | `FirebaseMLTypes` namespace | Import `FirebaseML` from package root | ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import ml from '@react-native-firebase/ml'; firebase.ml().app.name; ml().app.name; ``` ```js // Now import { getApp } from '@react-native-firebase/app'; import { getML } from '@react-native-firebase/ml'; getML().app.name; // default app getML(getApp('secondaryFromNative')).app.name; ``` # In-App Messaging The namespaced API for `@react-native-firebase/in-app-messaging` has been **removed**. This package is **modular-only** — use `getInAppMessaging()` and the root-level helper functions. There is no `firebase/in-app-messaging` entry in the firebase-js-sdk modular surface; React Native Firebase follows the same modular service-instance pattern used for other native-only modules. ## Removed namespaced API | Removed | Replacement (modular) | | ------------------------------------------- | ------------------------------------------------------------------------------------ | | `firebase.inAppMessaging()` | `getInAppMessaging()` | | Default export `inAppMessaging()` | `getInAppMessaging()` | | `FirebaseInAppMessagingTypes` | Import `InAppMessaging` and helpers (`setMessagesDisplaySuppressed`, etc.) from root | | Instance-only usage without modular helpers | Prefer free functions: `setMessagesDisplaySuppressed(inAppMessaging, enabled)`, etc. | ## Example: suppressing messages during setup ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import inAppMessaging from '@react-native-firebase/in-app-messaging'; await firebase.inAppMessaging().setMessagesDisplaySuppressed(true); // or await inAppMessaging().setMessagesDisplaySuppressed(true); ``` ```js // Now import { getInAppMessaging, setMessagesDisplaySuppressed, } from '@react-native-firebase/in-app-messaging'; await setMessagesDisplaySuppressed(getInAppMessaging(), true); ``` See [In-App Messaging usage](/in-app-messaging/usage) for additional examples. # Installations The namespaced API for `@react-native-firebase/installations` has been **removed**. This package is **modular-only** — use `getInstallations()` and the root-level helper functions. Modular `getInstallations()` returns a firebase-js-sdk-shaped `Installations` object exposing only `app`. Use modular helper functions instead of instance methods. ## Removed namespaced API | Removed | Replacement (modular) | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `firebase.installations()` | `getInstallations()` | | Default export `installations()` | `getInstallations()` | | `FirebaseInstallationsTypes` | Import `Installations` and helpers (`getId`, `getToken`, `deleteInstallations`) from root | | `installations.getId()` / `.getToken()` / `.delete()` | `getId(installations)`, `getToken(installations)`, `deleteInstallations(installations)` | ## Breaking changes (modular call shape) | Before | Now | | -------------------------- | --------------------------------------------------------------- | | `installations.getId()` | `getId(installations)` | | `installations.getToken()` | `getToken(installations)` | | `installations.delete()` | `deleteInstallations(installations)` — argument is **required** | ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import installations from '@react-native-firebase/installations'; const id = await firebase.installations().getId(); // or const id = await installations().getId(); ``` ```js // Now import { getInstallations, getId } from '@react-native-firebase/installations'; const installations = getInstallations(); const id = await getId(installations); ``` See [Installations usage](/installations/usage) for additional examples. # Cloud Messaging The namespaced API for `@react-native-firebase/messaging` has been **removed**. This package is **modular-only** — use `getMessaging()` and the root-level helper functions. Modular `getMessaging()` returns a firebase-js-sdk-shaped `Messaging` object. Prefer free functions (`getToken(messaging)`, `onMessage(messaging, listener)`, etc.) over calling methods on the service instance. ## Removed namespaced API | Removed | Replacement (modular) | | ---------------------------------------------------------- | ----------------------------------------------------------------------------- | | `firebase.messaging()` | `getMessaging()` | | Default export `messaging()` | `getMessaging()` | | `FirebaseMessagingTypes` | Import `Messaging`, `RemoteMessage`, and helpers from package root | | `messaging.getToken()` / `.onMessage()` / etc. | `getToken(messaging)`, `onMessage(messaging, listener)`, etc. | | `messaging.setDeliveryMetricsExportToBigQuery()` | `experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enabled)` | | `firebase.messaging.SDK_VERSION` / `messaging.SDK_VERSION` | `SDK_VERSION` top-level export from package root | ## Example: foreground messages ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import messaging from '@react-native-firebase/messaging'; firebase.messaging().onMessage(message => { console.log(message.data); }); // or messaging().onMessage(message => { console.log(message.data); }); ``` ```js // Now import { getMessaging, onMessage } from '@react-native-firebase/messaging'; onMessage(getMessaging(), message => { console.log(message.data); }); ``` ## Example: delivery metrics to BigQuery ```js // Previously (removed) await firebase.messaging().setDeliveryMetricsExportToBigQuery(true); ``` ```js // Now import { getMessaging, experimentalSetDeliveryMetricsExportedToBigQueryEnabled, } from '@react-native-firebase/messaging'; await experimentalSetDeliveryMetricsExportedToBigQueryEnabled(getMessaging(), true); ``` See [Cloud Messaging usage](/messaging/usage) for additional examples. ## iOS APNs registration (ARM64 Simulator + new Promise rejections) On **ARM64 iOS Simulator** (Apple Silicon), React Native Firebase **no longer calls** UIKit `registerForRemoteNotifications` from messaging **registration** and **auto-registration** paths (including the TurboModule `registerDeviceForRemoteMessages` path, `requestPermission`'s APNs side-effect, and native auto-register on app launch). Calling that UIKit API can block the main thread indefinitely. **Physical iOS devices are unchanged** — they still call UIKit `registerForRemoteNotifications` as before. This is intentional product policy so the main thread stays responsive on Simulator. You will **not** receive a real APNs device token on ARM64 Simulator; use a physical device for end-to-end push registration and delivery. ### New possible Promise rejections Prior releases could hang forever waiting for APNs registration (especially when the main thread was wedged) and did **not** reject with the codes below in the same situations. Apps that assumed `registerDeviceForRemoteMessages` always resolved (or never rejected) must handle these errors. #### `messaging/registration-timeout` - **When:** After about **10 seconds**, a timer on a **global** queue (not the main queue) rejects the in-flight registration Promise when APNs registration has not settled. - **APIs:** Surfaces on **`registerDeviceForRemoteMessages`** only. - **`requestPermission`:** On ARM64 Simulator, the APNs UIKit side-effect is **skipped**; the permission Promise still resolves with `AuthorizationStatus` and does **not** reject with this code. - **ARM64 Simulator:** Expected when you call `registerDeviceForRemoteMessages` — UIKit register is skipped, the Promise stays pending, then the global-queue timer rejects. - **Physical device:** Possible if the system never delivers a registration success/failure callback within about 10 seconds (for example missing notification permission, or a blocked main thread). - **Code / message:** `messaging/registration-timeout` — `registerDeviceForRemoteMessages timed out waiting for APNs device registration. The system did not respond — possibly missing notification permission, or the main thread is blocked (common on ARM64 Simulator).` #### `messaging/registration-superseded` - **When:** A newer `registerDeviceForRemoteMessages` call starts while a prior attempt is still in flight; the earlier Promise is rejected so it is not orphaned. - **APIs:** Surfaces on **`registerDeviceForRemoteMessages`** only (overlapping calls). - **Code / message:** `messaging/registration-superseded` — `registerDeviceForRemoteMessages was called again before the previous APNs registration attempt settled.` Further usage notes: [Auto Registration (iOS)](/messaging/usage#auto-registration-ios), [iOS Messaging Setup](/messaging/usage/ios-setup). Maintainer platform detail: [iOS APNs registration on Simulator](https://github.com/invertase/react-native-firebase/blob/main/okf-bundle/packages/messaging/ios-apns-simulator-registration.md). # App Distribution The namespaced API for `@react-native-firebase/app-distribution` has been **removed**. This package is **modular-only** — use `getAppDistribution()` and the root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `firebase.appDistribution()` | `getAppDistribution()` | | Default export `appDistribution()` | `getAppDistribution()` | | `FirebaseAppDistributionTypes` | Import `AppDistribution`, `AppDistributionRelease` from package root | | `appDistribution.isTesterSignedIn()` / etc. | `isTesterSignedIn(appDistribution)`, `signInTester(appDistribution)`, `checkForUpdate(appDistribution)`, `signOutTester(appDistribution)` | | `firebase.appDistribution.SDK_VERSION` | `SDK_VERSION` top-level export from package root | ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import appDistribution from '@react-native-firebase/app-distribution'; await firebase.appDistribution().isTesterSignedIn(); ``` ```js // Now import { getAppDistribution, isTesterSignedIn } from '@react-native-firebase/app-distribution'; const appDistribution = getAppDistribution(); await isTesterSignedIn(appDistribution); ``` # Cloud Functions The namespaced API for `@react-native-firebase/functions` has been **removed**. This package is **modular-only** — use `getFunctions()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | ----------------------------- | ----------------------------------------------------------------------------- | | `firebase.functions()` | `getFunctions()` or `getFunctions(app, regionOrCustomDomain)` | | Default export `functions()` | `getFunctions()` | | `FirebaseFunctionsTypes` | Import `Functions`, `HttpsCallable`, `HttpsErrorCode`, etc. from package root | | `functions().httpsCallable()` | `httpsCallable(functions, name, options?)` | | `functions().useEmulator()` | `connectFunctionsEmulator(functions, host, port)` | ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import functions from '@react-native-firebase/functions'; await firebase.functions().httpsCallable('myFn')({ foo: 'bar' }); ``` ```js // Now import { getFunctions, httpsCallable } from '@react-native-firebase/functions'; const functions = getFunctions(); await httpsCallable(functions, 'myFn')({ foo: 'bar' }); ``` # Performance Monitoring The namespaced API for `@react-native-firebase/perf` has been **removed**. This package is **modular-only** — use `getPerformance()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | -------------------------- | ------------------------------------------------------------------------ | | `firebase.perf()` | `getPerformance()` | | Default export `perf()` | `getPerformance()` | | `FirebasePerformanceTypes` | Import `FirebasePerformance`, `PerformanceTrace`, etc. from package root | | `perf().newTrace()` | `trace(performance, name)` | | `perf().newHttpMetric()` | `httpMetric(performance, url, httpMethod)` | ## Signature changes - `Trace`, `HttpMetric`, and `ScreenTrace` `start()` / `stop()` now return `void` synchronously (previously `Promise`), matching the firebase-js-sdk web `PerformanceTrace`. The underlying native calls are in-memory, so no `await` is required — remove any `await` on these calls. - `startScreenTrace(performance, screenName)` and the internal `startTrace(name)` helper now return the trace instance synchronously instead of a `Promise`. # App Check The namespaced API for `@react-native-firebase/app-check` has been **removed**. This package is **modular-only** — use `getAppCheck()` / `initializeAppCheck()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | --------------------------- | ---------------------------------------------------------------- | | `firebase.appCheck()` | `getAppCheck()` or `initializeAppCheck(app, options)` | | Default export `appCheck()` | `getAppCheck()` | | `FirebaseAppCheckTypes` | Import `AppCheck`, `AppCheckTokenResult`, etc. from package root | | `appCheck().getToken()` | `getToken(appCheck, forceRefresh?)` | ## Signature changes - `initializeAppCheck(app?, options?)` returns `AppCheck` synchronously (previously `Promise`). Native provider setup continues in the background — remove `await` and do not chain `.then()`. # Analytics The namespaced API for `@react-native-firebase/analytics` has been **removed**. This package is **modular-only** — use `getAnalytics()` and root-level helper functions. Analytics supports only the **default Firebase app** (same as before). Calling `getAnalytics(secondaryApp)` throws. ## Removed namespaced API | Removed | Replacement (modular) | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `firebase.analytics()` | `getAnalytics()` | | Default export `analytics()` | `getAnalytics()` | | `FirebaseAnalyticsTypes` | Import `Analytics`, event parameter types, etc. from package root | | `analytics().logEvent(...)` | `logEvent(analytics, ...)` | | `analytics().setUserId(...)` etc. | `setUserId(analytics, ...)`, `setConsent(analytics, ...)`, etc. | | Deprecated helper events (`logScreenView`, `logPurchase`, …) | Still exported as modular helpers; prefer `logEvent(analytics, 'screen_view', params)` | ## Signature changes - `logEvent(analytics, …)` returns `void` synchronously (previously `Promise`). Remove `await` and `.then()` chains. ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import analytics from '@react-native-firebase/analytics'; await firebase.analytics().logEvent('screen_view', { screen_name: 'Home' }); await analytics().setUserId('user-123'); ``` ```js // Now import { getAnalytics, logEvent, setUserId } from '@react-native-firebase/analytics'; const analytics = getAnalytics(); logEvent(analytics, 'screen_view', { screen_name: 'Home' }); await setUserId(analytics, 'user-123'); ``` See [Analytics usage](/analytics/usage) for additional examples. # Remote Config The namespaced API for `@react-native-firebase/remote-config` has been **removed**. This package is **modular-only** — use `getRemoteConfig()` and root-level helper functions. Modular `getRemoteConfig()` returns a firebase-js-sdk-shaped `RemoteConfig` object with `app`, `settings`, `defaultConfig`, `fetchTimeMillis`, and `lastFetchStatus`. Use modular helper functions for fetch/activate/getters; assign `remoteConfig.settings` and `remoteConfig.defaultConfig` instead of removed modular `setConfigSettings()` / `setDefaults()` helpers. ## Removed namespaced API | Removed | Replacement (modular) | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `firebase.remoteConfig()` | `getRemoteConfig()` | | Default export `remoteConfig()` | `getRemoteConfig()` | | `FirebaseRemoteConfigTypes` | Import `RemoteConfig`, `Value`, etc. from package root | | `remoteConfig().activate()` etc. | `activate(remoteConfig)`, `fetchConfig(remoteConfig)`, `getValue(remoteConfig, key)`, etc. | | `remoteConfig.LastFetchStatus` / `.ValueSource` on namespace | `LastFetchStatus`, `ValueSource` named exports | ## Breaking changes (modular call shape) | Before | Now | | ------------------------------------------- | ---------------------------------------- | | `remoteConfig().fetch()` | `fetchConfig(remoteConfig)` | | `remoteConfig().setConfigSettings({ ... })` | `remoteConfig.settings = { ... }` | | `remoteConfig().setDefaults({ ... })` | `remoteConfig.defaultConfig = { ... }` | | `remoteConfig().onConfigUpdated(listener)` | `onConfigUpdate(remoteConfig, observer)` | ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import remoteConfig from '@react-native-firebase/remote-config'; await firebase.remoteConfig().fetchAndActivate(); const value = firebase.remoteConfig().getValue('key').asString(); ``` ```js // Now import { getRemoteConfig, fetchAndActivate, getValue } from '@react-native-firebase/remote-config'; const remoteConfig = getRemoteConfig(); await fetchAndActivate(remoteConfig); const value = getValue(remoteConfig, 'key').asString(); ``` See [Remote Config usage](/remote-config/usage) for additional examples. # Crashlytics The namespaced API for `@react-native-firebase/crashlytics` has been **removed**. This package is **modular-only** — use `getCrashlytics()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | ------------------------------ | ----------------------------------------------- | | `firebase.crashlytics()` | `getCrashlytics()` | | Default export `crashlytics()` | `getCrashlytics()` | | `FirebaseCrashlyticsTypes` | Import `Crashlytics` from package root | | `crashlytics().log()` | `log(crashlytics, message)` | | `crashlytics().recordError()` | `recordError(crashlytics, error, jsErrorName?)` | # Realtime Database The namespaced API for `@react-native-firebase/database` has been **removed**. This package is **modular-only** — use `getDatabase()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | --------------------------- | -------------------------------------------------------------- | | `firebase.database()` | `getDatabase()` or `getDatabase(app, url?)` | | Default export `database()` | `getDatabase()` | | `FirebaseDatabaseTypes` | Import `Database`, `DatabaseReference`, etc. from package root | | `database().ref()` | `ref(database, path?)` | | `database().refFromURL()` | `refFromURL(database, url)` | ## Signature changes - `goOnline(db)` and `goOffline(db)` (and the database instance methods) now return `void` synchronously (previously `Promise`), matching firebase-js-sdk. Remove any `await` on these calls. # Cloud Storage The namespaced API for `@react-native-firebase/storage` has been **removed**. This package is **modular-only** — use `getStorage()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | -------------------------- | -------------------------------------------------------------------- | | `firebase.storage()` | `getStorage()` or `getStorage(app, bucketUrl?)` | | Default export `storage()` | `getStorage()` | | `FirebaseStorageTypes` | Import `FirebaseStorage`, `StorageReference`, etc. from package root | | `storage().ref()` | `ref(storage, path?)` | | `storageRef.put()` | `uploadBytesResumable(storageRef, data, metadata?)` | ## Signature changes - `UploadTask.pause()`, `UploadTask.resume()`, and `UploadTask.cancel()` now return `boolean` synchronously (previously `Promise`), matching firebase-js-sdk task semantics. Remove `await`, `.then()`, and `.catch()` from these control calls and use the returned boolean directly. - `cancel()` delegates to the native SDK. Android cancels active uploads; iOS active-upload cancel follows the current Firebase Storage iOS SDK 12.15.0 behavior tracked in [firebase-ios-sdk#16353](https://github.com/firebase/firebase-ios-sdk/issues/16353). # Authentication The namespaced API for `@react-native-firebase/auth` has been **removed**. This package is **modular-only** — use `getAuth()` / `initializeAuth()` and root-level helper functions. ## Removed namespaced API | Removed | Replacement (modular) | | ---------------------------------------- | --------------------------------------------------------------- | | `firebase.auth()` | `getAuth()` or `getAuth(app)` | | Default export `auth()` | `getAuth()` | | `FirebaseAuthTypes` namespace | Import `Auth`, `User`, `UserCredential`, etc. from package root | | `auth().signInWithEmailAndPassword(...)` | `signInWithEmailAndPassword(getAuth(), ...)` | | `auth().useEmulator(url)` | `connectAuthEmulator(getAuth(), url, options?)` | | `firebase.auth.EmailAuthProvider` | `EmailAuthProvider` (named export) | ## Signature changes - `isSignInWithEmailLink(auth, emailLink)` now returns `boolean` synchronously, matching firebase-js-sdk. - `TotpSecret.generateQrCodeUrl(accountName?, issuer?)` now returns `string` synchronously, matching firebase-js-sdk. When `accountName` or `issuer` is omitted, React Native Firebase fills the same defaults from the current user email and Firebase app name. ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import auth from '@react-native-firebase/auth'; firebase.auth().signOut(); auth().currentUser; ``` ```js // Now import { getAuth, signOut } from '@react-native-firebase/auth'; const auth = getAuth(); await signOut(auth); auth.currentUser; ``` # Cloud Firestore The namespaced API for `@react-native-firebase/firestore` has been **removed**. This package is **modular-only** — use `getFirestore()` / `initializeFirestore()` and root-level helper functions. The `@react-native-firebase/firestore/pipelines` subpath export is unchanged. ## Removed namespaced API | Removed | Replacement (modular) | | ---------------------------------------------- | ------------------------------------------------------------------------------------- | | `firebase.firestore()` | `getFirestore()` or `getFirestore(app, databaseId?)` | | Default export `firestore()` | `getFirestore()` | | `FirebaseFirestoreTypes` namespace | Import `Firestore`, `DocumentReference`, `Query`, etc. from package root | | `firestore().collection(...)` | `collection(getFirestore(), ...)` | | `firestore().doc(...)` | `doc(getFirestore(), ...)` | | `firestore().batch()` | `writeBatch(getFirestore())` | | `firestore().runTransaction(...)` | `runTransaction(getFirestore(), updateFunction, options?)` | | `firestore().useEmulator(...)` | `connectFirestoreEmulator(getFirestore(), ...)` | | `firestore().settings(...)` | `initializeFirestore(app, settings, databaseId?)` | | `firestore.FieldValue` / `firestore.Timestamp` | `FieldValue`, `Timestamp`, `FieldPath`, `Bytes`, `GeoPoint`, `Filter` (named exports) | | `firestore.Blob` | `Bytes` | ## Signature changes - `initializeFirestore(app, settings, databaseId?)` returns `Firestore` synchronously (previously `Promise`). Remove `await` and `.then()`; settings apply on the native bridge after return. - `TransactionOptions` is now exported. `runTransaction(firestore, updateFunction, options?)` accepts `{ maxAttempts?: number }` and passes the retry limit to the native iOS and Android Firestore SDKs. When `options` is omitted, the native default applies (**5** attempts, matching [firebase-js-sdk `runTransaction`](https://firebase.google.com/docs/reference/js/firestore_.md#runtransaction)). When `maxAttempts` is provided explicitly, values below **1** throw synchronously with `Max attempts must be at least 1` — the same validation as firebase-js-sdk. - `aggregateFieldEqual()` and `aggregateQuerySnapshotEqual()` are now exported for aggregate query equality checks (firebase-js-sdk parity). - FieldValue `maximum(n)` and `minimum(n)` sentinels from firebase-js-sdk 12.15.0 are not exported yet. Android Firebase Firestore SDK 34.15.0 supports them, but iOS Firebase Firestore SDK 12.15.0 does not expose matching `FIRFieldValue` factories, so React Native Firebase waits for cross-platform support. ## Example ```js // Previously (removed) import firebase from '@react-native-firebase/app'; import firestore from '@react-native-firebase/firestore'; firebase.firestore().collection('users').doc('alice').set({ name: 'Alice' }); firestore.FieldValue.serverTimestamp(); ``` ```js // Now import { getFirestore, collection, doc, setDoc, serverTimestamp, } from '@react-native-firebase/firestore'; const db = getFirestore(); await setDoc(doc(collection(db, 'users'), 'alice'), { name: 'Alice', createdAt: serverTimestamp(), }); ``` See [Firestore usage](/firestore/usage) for additional examples. # Automated migration checklist Use this section when running scripted or agent-assisted upgrades to v26 for modular-only packages. ## 1. Upgrade dependencies ```bash # Bump all @react-native-firebase/* packages to v26 together (monorepo versions are aligned) yarn add @react-native-firebase/app@^26.0.0 … cd ios && pod install ``` ## 2. Fix imports by package For each modular-only package you use: | Package | Search for | Replace with | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `app` | default `firebase` import, `firebase.app()`, `firebase.apps`, `firebase.initializeApp()`, `firebase.utils()`, `firebase.SDK_VERSION` | `getApp()`, `getApps()`, `initializeApp()`, `getUtils()`, `FilePath`, `SDK_VERSION`, `setLogLevel`, etc. | | `ml` | `firebase.ml()`, default `ml()`, `FirebaseMLTypes` | `getML()`, root `FirebaseML` type | | `in-app-messaging` | `firebase.inAppMessaging()`, default `inAppMessaging()`, `FirebaseInAppMessagingTypes` | `getInAppMessaging()`, root modular helpers (`setMessagesDisplaySuppressed`, etc.) | | `installations` | `firebase.installations()`, default `installations()`, `.getId()`, `.getToken()`, `.delete()`, `FirebaseInstallationsTypes` | `getInstallations()`, `getId()`, `getToken()`, `deleteInstallations()` | | `messaging` | `firebase.messaging()`, default `messaging()`, `FirebaseMessagingTypes`, instance methods | `getMessaging()`, root helpers (`getToken`, `onMessage`, etc.), `SDK_VERSION`, `experimentalSetDeliveryMetricsExportedToBigQueryEnabled` | | `app-distribution` | `firebase.appDistribution()`, default `appDistribution()`, `FirebaseAppDistributionTypes`, instance methods | `getAppDistribution()`, `isTesterSignedIn`, `signInTester`, `checkForUpdate`, `signOutTester`, `SDK_VERSION` | | `functions` | `firebase.functions()`, default `functions()`, `FirebaseFunctionsTypes`, instance methods | `getFunctions()`, `httpsCallable`, `httpsCallableFromUrl`, `connectFunctionsEmulator`, `HttpsErrorCode` | | `perf` | `firebase.perf()`, default `perf()`, `FirebasePerformanceTypes`, instance methods | `getPerformance()`, `trace`, `httpMetric`, `newScreenTrace`, `startScreenTrace`, `initializePerformance` | | `app-check` | `firebase.appCheck()`, default `appCheck()`, `FirebaseAppCheckTypes`, instance methods | `getAppCheck()`, `initializeAppCheck`, `getToken`, `getLimitedUseToken`, `setTokenAutoRefreshEnabled`, `onTokenChanged`, `CustomProvider` | | `analytics` | `firebase.analytics()`, default `analytics()`, `FirebaseAnalyticsTypes`, instance methods | `getAnalytics()`, `logEvent`, `setUserId`, `setConsent`, `getAppInstanceId`, `getSessionId`, etc. | | `remote-config` | `firebase.remoteConfig()`, default `remoteConfig()`, `FirebaseRemoteConfigTypes`, instance methods | `getRemoteConfig()`, `activate`, `fetchConfig`, `fetchAndActivate`, `getValue`, `getAll`, `onConfigUpdate`, `LastFetchStatus`, `ValueSource` | | `crashlytics` | `firebase.crashlytics()`, default `crashlytics()`, `FirebaseCrashlyticsTypes`, instance methods | `getCrashlytics()`, `log`, `recordError`, `setUserId`, `setAttribute`, `setAttributes`, `setCrashlyticsCollectionEnabled`, etc. | | `database` | `firebase.database()`, default `database()`, `FirebaseDatabaseTypes`, instance methods | `getDatabase()`, `ref`, `refFromURL`, `onValue`, `runTransaction`, `connectDatabaseEmulator`, etc. | | `storage` | `firebase.storage()`, default `storage()`, `FirebaseStorageTypes`, instance/reference methods | `getStorage()`, `ref`, `uploadBytesResumable`, `getDownloadURL`, `connectStorageEmulator`, `StringFormat`, `TaskEvent`, `TaskState` | | `firestore` | `firebase.firestore()`, default `firestore()`, `FirebaseFirestoreTypes`, instance methods | `getFirestore()`, `doc`, `collection`, `setDoc`, `writeBatch`, `runTransaction`, `connectFirestoreEmulator`, `FieldValue`, `Timestamp`, `Bytes`, `SDK_VERSION` | Also remove `await`, `.then()`, and `.catch()` from `UploadTask.pause()`, `UploadTask.resume()`, and `UploadTask.cancel()`. For Firestore transactions, import `TransactionOptions` when you pass `{ maxAttempts }` (omit `options` for the default **5** retries; do not pass `0` or negative values). Import `aggregateFieldEqual()` / `aggregateQuerySnapshotEqual()` for aggregate equality checks. ## 3. Validate ```bash yarn compile yarn tests:jest packages//__tests__ ``` ``` ### Migrating to v27 Source: https://rnfirebase.io/migrating-to-v27 ```mdx Version 27 bundles several **breaking behavior corrections** and dependency bumps that landed after v26: - **Firebase JS SDK 12.18.0** — on web/macOS (`Platform.other`), `FunctionsError.message` appends an HTTP status suffix and `customData.url` is populated ([#9218](https://github.com/invertase/react-native-firebase/pull/9218)). - **Cloud Messaging** — four documented runtime contracts are enforced after previous accidental shapes ([#9246](https://github.com/invertase/react-native-firebase/pull/9246), [#9247](https://github.com/invertase/react-native-firebase/pull/9247), [#9252](https://github.com/invertase/react-native-firebase/pull/9252), [#9254](https://github.com/invertase/react-native-firebase/pull/9254)). - **Imagen API removed** from `@react-native-firebase/ai` after Google shut down the Imagen models as a service on **2026-08-17**. Generate images with a Gemini image model through `getGenerativeModel()` instead. If you are upgrading from v25 or earlier, complete [Migrating to v26](/migrating-to-v26) first — the namespaced API removal and New Architecture requirement still apply. ## Table of contents - [Agent-assisted migration](/migrating-to-v27#agent-assisted-migration) - [Firebase JS SDK 12.18.0](/migrating-to-v27#firebase-js-sdk-12180) - [Cloud Messaging](/migrating-to-v27#cloud-messaging) - [String APNs sound → `notification.ios.sound`](/migrating-to-v27#string-apns-sound--notificationiossound) - [iOS `sentTime` is epoch milliseconds](/migrating-to-v27#ios-senttime-is-epoch-milliseconds) - [iOS badge is a string](/migrating-to-v27#ios-badge-is-a-string) - [`onMessageSent` receives a string message ID](/migrating-to-v27#onmessagesent-receives-a-string-message-id) - [Removed Imagen API](/migrating-to-v27#removed-imagen-api) - [Example](/migrating-to-v27#example) - [Automated migration checklist](/migrating-to-v27#automated-migration-checklist) ## Agent-assisted migration This guide is written to be **complete enough for an automated first pass**. We recommend feeding this document to your coding agent, then asking it to analyze your codebase against each relevant section below and produce a concrete change list (or PR) for the packages you use. The [Automated migration checklist](/migrating-to-v27#automated-migration-checklist) at the end is structured for that workflow. # Firebase JS SDK 12.18.0 **PR:** [#9218](https://github.com/invertase/react-native-firebase/pull/9218) React Native Firebase pins **firebase-js-sdk 12.18.0**. On **web and macOS** (`Platform.other`), Cloud Functions uses the JS SDK callable path. That path now enriches `FunctionsError` (aliased as `HttpsError` in React Native Firebase): | Change | Before | After (v27 / JS SDK 12.18.0) | Who | | ------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- | ---------------- | | `FunctionsError.message` | Exact server message string | Message plus a trailing ` []` suffix (for example `Invalid test requested. [400]`) | Web / macOS only | | `FunctionsError.customData.url` | Not present | Request URL string on `customData` | Web / macOS only | **Native iOS and Android** continue to surface callable failures through the native bridge as `HttpsError` **without** the HTTP status suffix. Do not assume the suffix or `customData.url` on those platforms. ### Migration actions 1. Search for exact-equality checks on `error.message` / `e.message` for callable failures. 2. On web/macOS, prefer `message.startsWith(expected)` or strip a trailing ` [digits]` before comparing. 3. If you need the HTTP status or request URL, read them from the suffix / `customData.url` on web/macOS only; keep a native fallback path for iOS/Android. ```js // Previously (exact match — breaks on web/macOS after 12.18.0) if (e.message === 'Invalid test requested.') { /* … */ } // Now (tolerant of the optional " [status]" suffix) const base = e.message.replace(/ \[\d+\]$/, ''); if (base === 'Invalid test requested.') { /* … */ } // Optional on Platform.other: // e.customData?.url ``` Upstream note: [firebase@12.18.0](https://github.com/firebase/firebase-js-sdk/releases/tag/firebase%4012.18.0) — “Add HTTP status code to the `message` field and add `url` to `customData`.” # Cloud Messaging These changes **correct runtime behavior** to match the public `RemoteMessage` / listener contracts. There is no new public TypeScript surface — consumers that worked around the old accidental shapes must update. ## String APNs sound → `notification.ios.sound` **PR:** [#9246](https://github.com/invertase/react-native-firebase/pull/9246) String-valued APNs sounds are serialized at the documented `message.notification.ios.sound` path. Previously, only string sounds were placed at the undocumented `message.notification.sound` path (critical-sound dictionaries already used the correct iOS nesting). | Before (accidental) | After (documented) | | ------------------------------------- | ----------------------------------------- | | `message.notification.sound` (string) | `message.notification.ios.sound` (string) | ```js // Previously const sound = message.notification?.sound; // Now const sound = message.notification?.ios?.sound; ``` ## iOS `sentTime` is epoch milliseconds **PR:** [#9247](https://github.com/invertase/react-native-firebase/pull/9247) On iOS, `RemoteMessage.sentTime` is a **number** of epoch **milliseconds**, matching Android and the public type. FCM supplies seconds (often as a string); native serialization converts those values to milliseconds. | Before (iOS accidental) | After | | ----------------------------------------------------- | ----------------------------------------------------------- | | string epoch **seconds** (for example `"1522880044"`) | number epoch **milliseconds** (for example `1522880044000`) | Android behavior is unchanged. Remove `parseInt` / string comparisons that assumed seconds. ```js // Previously (iOS) const sentMs = Number(message.sentTime) * 1000; // Now (iOS and Android) const sentMs = message.sentTime; // number, epoch ms ``` ## iOS badge is a string **PR:** [#9252](https://github.com/invertase/react-native-firebase/pull/9252) iOS `aps.badge` is serialized as a **string**, matching `RemoteMessage.notification.ios.badge?: string`. | Before (iOS accidental) | After | | ------------------------ | -------------------------- | | number (for example `7`) | string (for example `"7"`) | ```js // Previously const badge = message.notification?.ios?.badge; // number on iOS // Now const badge = Number(message.notification?.ios?.badge ?? 0); ``` ## `onMessageSent` receives a string message ID **PR:** [#9254](https://github.com/invertase/react-native-firebase/pull/9254) `onMessageSent` listeners receive the documented **message-ID string**. Android previously forwarded the transport wrapper `{ messageId }` to application code. | Before (accidental) | After (documented) | | ----------------------- | ------------------ | | `{ messageId: string }` | `string` | ```js // Previously onMessageSent(messaging, ({ messageId }) => { console.log(messageId); }); // Now onMessageSent(messaging, messageId => { console.log(messageId); }); ``` # Removed Imagen API Nothing else in `@react-native-firebase/ai` changed. `getGenerativeModel()`, `getTemplateGenerativeModel()`, `TemplateGenerativeModel`, and Gemini image generation are unaffected. ## Removed exports {/* prettier-ignore */} | Removed | Replacement | | --- | --- | | `getImagenModel` | `getGenerativeModel()` with a Gemini image model | | `getTemplateImagenModel` | `getTemplateGenerativeModel()` with a template that uses an image model | | `ImagenModel` | `GenerativeModel` | | `TemplateImagenModel` | `TemplateGenerativeModel` | | `ImagenModelParams` | `ModelParams` | | `ImagenGenerationConfig` | `GenerationConfig` with `responseModalities` and `imageConfig` | | `ImagenImageFormat` | No replacement — Gemini image models always return `PNG`; read `inlineData.mimeType` to confirm | | `ImagenGenerationResponse` | `GenerateContentResult` | | `ImagenInlineImage` | `InlineDataPart` on the response candidate | | `ImagenGCSImage` | No replacement — Gemini image models return inline data | | `ImagenAspectRatio` | `ImageConfigAspectRatio` | | `ImagenSafetySettings` | `SafetySetting[]` on `getGenerativeModel()` | | `ImagenSafetyFilterLevel` | `HarmBlockThreshold` | | `ImagenPersonFilterLevel` | No replacement — Gemini image models allow generating people by default | ## Example ```js // Previously (removed) import { getApp } from '@react-native-firebase/app'; import { getAI, getImagenModel, ImagenAspectRatio } from '@react-native-firebase/ai'; const ai = getAI(getApp()); const imagenModel = getImagenModel(ai, { model: 'imagen-3.0-generate-002', generationConfig: { aspectRatio: ImagenAspectRatio.LANDSCAPE_16x9, }, }); const result = await imagenModel.generateImages('Draw a red bicycle on a beach at sunset'); console.log(result.images[0].mimeType); ``` ```js // Now import { getApp } from '@react-native-firebase/app'; import { getAI, getGenerativeModel, ImageConfigAspectRatio, ImageConfigImageSize, ResponseModality, } from '@react-native-firebase/ai'; const ai = getAI(getApp()); const model = getGenerativeModel(ai, { model: 'gemini-3.1-flash-image', generationConfig: { responseModalities: [ResponseModality.IMAGE], imageConfig: { aspectRatio: ImageConfigAspectRatio.LANDSCAPE_16x9, imageSize: ImageConfigImageSize.SIZE_1K, }, }, }); const result = await model.generateContent('Draw a red bicycle on a beach at sunset'); const imagePart = result.response.inlineDataParts()?.[0]; console.log(imagePart?.inlineData.mimeType); ``` See [AI Logic usage](/ai/usage) for more image generation examples, and Google's [Imagen to Gemini migration guide](https://firebase.google.com/docs/ai-logic/imagen-models-migration) for model and prompt guidance. # Automated migration checklist Use this section when running scripted or agent-assisted upgrades from v26 → v27. ## 1. Upgrade dependencies ```bash # Bump all @react-native-firebase/* packages to v27 together (monorepo versions are aligned) yarn add @react-native-firebase/app@^27.0.0 … cd ios && pod install ``` Confirm the lockfiles resolve **firebase** / firebase-js-sdk **12.18.0+**. ## 2. Agent-oriented search and replace For each area you use, search the listed symbols and apply the replacements: | Area | Search for | Replace with / action | | ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Functions (web/macOS) | `e.message ===`, `error.message ===` on callable failures | Tolerate trailing ` []`; optionally read `customData.url` on `Platform.other` only | | Messaging sound | `notification.sound` (string APNs sound) | `notification.ios.sound` | | Messaging `sentTime` | string/`parseInt`/`* 1000` on `sentTime` (iOS) | Use numeric epoch-ms directly | | Messaging badge | numeric use of `notification.ios.badge` | Parse string (`Number(...)`) when a number is required | | Messaging `onMessageSent` | `({ messageId })` / `.messageId` in the listener | Use the string argument directly | | AI Imagen | `getImagenModel`, `getTemplateImagenModel`, `ImagenModel`, `Imagen*`, `generateImages` | `getGenerativeModel` / `getTemplateGenerativeModel` with `responseModalities` + `imageConfig` | ## 3. Validate ```bash yarn compile # TypeScript consumers: fix compile errors from removed Imagen exports and messaging types # Manually exercise: callable error message handling (web/macOS), FCM notification fields (iOS), onMessageSent, Gemini image generation ``` ## Related PRs (v27 breaking changes) | Area | PR | | ------------------------------------------ | --------------------------------------------------------------------- | | Firebase JS SDK 12.18.0 / `FunctionsError` | [#9218](https://github.com/invertase/react-native-firebase/pull/9218) | | Messaging — APNs string sound path | [#9246](https://github.com/invertase/react-native-firebase/pull/9246) | | Messaging — iOS `sentTime` epoch-ms | [#9247](https://github.com/invertase/react-native-firebase/pull/9247) | | Messaging — iOS badge string | [#9252](https://github.com/invertase/react-native-firebase/pull/9252) | | Messaging — `onMessageSent` string ID | [#9254](https://github.com/invertase/react-native-firebase/pull/9254) | | AI — Imagen API removal | [#9275](https://github.com/invertase/react-native-firebase/pull/9275) | ``` ### Platforms Source: https://rnfirebase.io/platforms ```mdx ## Status By default React Native Firebase supports multiple platforms using the native Firebase SDK for the specific platform: | Platform | Minimum Version | | -------- | -------------------------- | | Android | 6.0 (API 23 / Marshmallow) | | iOS | 15.0 | **Important** - To compile your application for Android, you will need a minimum JDK (Java Development Kit) version of `>= 17`. However, for platforms that we don't provide a Native Module for, React Native Firebase instead implements a fallback Firebase JS SDK implementation to support these 'Other' platforms, e.g.; - Web - macOS - Windows - ...and any other RN based environment. Below is a table outlining which Firebase modules are supported on each platform in React Native Firebase: | Firebase Service | Android | iOS | Other | | ------------------------- | :-----: | :-: | :---: | | ai | ✅ | ✅ | ✅ | | analytics | ✅ | ✅ | ✅ | | app | ✅ | ✅ | ✅ | | app-check | ⚠️ | ⚠️ | ⚠️ | | app-distribution | ✅ | ✅ | ❌ | | auth | ✅ | ✅ | ⚠️ | | crashlytics | ✅ | ✅ | ❌ | | database | ✅ | ✅ | ✅ | | firestore | ✅ | ✅ | ⚠️ | | functions | ✅ | ✅ | ✅ | | in-app-messaging | ✅ | ✅ | ❌ | | installations | ✅ | ✅ | ❌ | | messaging | ✅ | ✅ | ❌ | | ml | ✅ | ✅ | ❌ | | perf | ✅ | ✅ | ❌ | | phone-number-verification | ✅ | ❌ | ❌ | | remote-config | ✅ | ✅ | ✅ | | storage | ✅ | ✅ | ⚠️ | - ✅ (supported) - ⚠️ (partial support) - see notes below - ❌ (not supported) ## Other Platforms Whenever the React Native Firebase SDK is running on platforms other than Android or iOS, the internal implementation uses a fallback platform which is implemented in JavaScript, using the [Firebase JavaScript Modular SDK](https://firebase.google.com/docs/reference/js). No implementation changes are required to use the React Native Firebase SDK on other platforms (with the exception of Async Storage detailed below), as the JavaScript implementation is automatically used when a native platform is not available. This allows you to use the same API across all platforms, regardless of the underlying implementation. There are however some minor limitations or differences in behavior compared to the native platforms. Where a particular method is not supported, an error will be thrown with a code of `unsupported` to indicate the method is not available on the current platform. Further details of Firebase service specific limitations are summarized below. ### Async Storage Some services (currently Auth and Analytics) for our 'Other' platforms implementation require a Async Storage implementation to be provided to enable persistence, React Native Firebase provides an API to set this implementation: ```js import { initializeApp, setReactNativeAsyncStorage } from '@react-native-firebase/app'; import AsyncStorage from '@react-native-async-storage/async-storage'; setReactNativeAsyncStorage(AsyncStorage); await initializeApp({ ... }); ``` > Note: we use `@react-native-async-storage/async-storage` as an example, you should use the Async Storage implementation that is appropriate for your platform that you are targeting. If you do not provide an Async Storage implementation, we use an in memory implementation which will result in resetting the data every time your app is restarted, in the case of Firebase Auth this means your users have to sign in again and for Firebase Analytics the app will generate a new instance id and look like a new installation every time. ### Analytics The other platform implementation of Analytics does not capture automatic metrics like screen view, you must call `logEvent` and other logging based methods to send your events to Firebase. - [Screen Tracking Guide](/analytics/screen-tracking) ### App Check App Check for other platforms only supports the `CustomProvider` provider. Here's how to setup your own custom provider: - [Implement server support to get tokens](https://firebase.google.com/docs/app-check/custom-provider) - Create a custom provider in your app: ```js import { getApp } from '@react-native-firebase/app'; import { CustomProvider, initializeAppCheck } from '@react-native-firebase/app-check'; const myCustomProvider = new CustomProvider({ async getToken: () => { const tokenFromServer = 'some-token-from-server'; const expirationFromServer = 1000 * 60 * 60; const appCheckToken = { token: tokenFromServer, expireTimeMillis: expirationFromServer * 1000 }; return appCheckToken; } }); await initializeAppCheck(getApp(), { provider: myCustomProvider }); ``` ### Authentication Multi-factor authentication is not supported on other platforms. Phone authentication methods are unsupported, specifically: - `signInWithProvider` - `signInWithPhoneNumber` - `verifyPhoneNumberForMultiFactor` - `confirmationResultConfirm` - `verifyPhoneNumber` - `reauthenticateWithProvider` ### Database Offline persistence is not supported on other platforms. Unsupported methods: - `keepSynced` - for offline persistence ### Firestore For performance reasons and to reduce the size of the JavaScript bundle, the Other platform implementation in React Native Firebase uses the JavaScript [lite](https://firebase.google.com/docs/reference/js/firestore_lite) SDK, which does not support methods related to offline & persistence. Specifically, the following methods are not supported: - `loadBundle` - `clearPersistence` - for offline persistence - `disableNetwork` - for offline persistence - `enableNetwork` - for offline persistence - `namedQuery` - `onSnapshot` (for both `CollectionReference` & `DocumentReference`) - `GetOptions.source` ### Storage No-op methods: - `setMaxDownloadRetryTime` (does not throw, but has no effect) Unsupported methods: - `writeToFile` - `putFile` --- ## Known Issues Known issues will be documented here and updated regularly. - There are currently no known issues. ``` ### Release notes Source: https://rnfirebase.io/releases ```mdx Starting from version `10.0.0`, React Native Firebase packages share a single common version, with aggregated release notes available: ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/app.svg?style=for-the-badge&logo=npm) [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/CHANGELOG.md) --- From version `v6.5.0` until `10.0.0`; all React Native Firebase packages were independently versioned with individually generated release notes: | Package | | | | ---------------------- | :------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------: | | Analytics | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/analytics.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/analytics/CHANGELOG.md) | | App | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/app.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/app/CHANGELOG.md) | | App Check | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/app-check.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/app-check/CHANGELOG.md) | | App Distribution | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/app-distribution.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/app-distribution/CHANGELOG.md) | | Authentication | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/auth.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/auth/CHANGELOG.md) | | Cloud Firestore | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/firestore.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/firestore/CHANGELOG.md) | | Cloud Functions | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/functions.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/functions/CHANGELOG.md) | | Cloud Messaging | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/messaging.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/messaging/CHANGELOG.md) | | Cloud Storage | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/storage.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/storage/CHANGELOG.md) | | Crashlytics | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/crashlytics.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/crashlytics/CHANGELOG.md) | | In-app Messaging | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/in-app-messaging.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/in-app-messaging/CHANGELOG.md) | | Installations | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/installations.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/installations/CHANGELOG.md) | | ML | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/ml.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/ml/CHANGELOG.md) | | Performance Monitoring | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/perf.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/perf/CHANGELOG.md) | | Realtime Database | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/database.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/database/CHANGELOG.md) | | Remote Config | ![hide:badge](https://img.shields.io/npm/v/@react-native-firebase/remote-config.svg?style=for-the-badge&logo=npm) | [View Release Notes »](https://github.com/invertase/react-native-firebase/tree/main/packages/remote-config/CHANGELOG.md) | --- To view release notes for versions prior to `v6.5.0` see the table below. | Version | | | ------- | :--------------------------------------------: | | v6.4.0 | [View Release Notes »](/releases/v6.4.0) | | v6.3.0 | [View Release Notes »](/releases/v6.3.0) | | v6.2.0 | [View Release Notes »](/releases/v6.2.0) | | v6.1.0 | [View Release Notes »](/releases/v6.1.0) | | v6.0.3 | [View Release Notes »](/releases/v6.0.3) | | v6.0.2 | [View Release Notes »](/releases/v6.0.2) | | v6.0.1 | [View Release Notes »](/releases/v6.0.1) | | v6.0.0 | [View Release Notes »](/releases/v6.0.0) | ``` ### TypeScript Source: https://rnfirebase.io/typescript ```mdx React Native Firebase ships TypeScript declarations for every module. From v25 onward, modular types and helpers are exported from each package root (for example `@react-native-firebase/auth`) alongside the namespaced default export. If you are setting up TypeScript in a new React Native app, see the official [TypeScript documentation](https://reactnative.dev/docs/typescript). ## Modular API Import modular helpers and types from the package root: ```tsx import { useEffect, useState } from 'react'; import { getAuth, onAuthStateChanged, type User } from '@react-native-firebase/auth'; function App() { const [user, setUser] = useState(null); useEffect(() => { const authInstance = getAuth(); return onAuthStateChanged(authInstance, setUser); }, []); if (!user) { return null; } return user.email; } ``` See [Migrating to v25](/migrating-to-v25) for Auth breaking changes (`FirebaseAuthTypes` deprecation, provider helpers, async `isSignInWithEmailLink`, and other firebase-js-sdk alignment updates). ## Where definitions live Published types are built to `packages//dist/typescript/` (for example `packages/auth/dist/typescript/lib/index.d.ts`). Source lives under `packages//lib/` as TypeScript (`.ts`) since the v25 package migrations. Modular Auth source: [`packages/auth/lib/modular.ts`](https://github.com/invertase/react-native-firebase/blob/main/packages/auth/lib/modular.ts). Public API reference (generated from source JSDoc): [reference API](https://reference.rnfirebase.io/modules.html). ## Definitions per module Each package exports its own types from the package root. Examples: | Module | Modular types (import from package root) | | --------- | --------------------------------------------------------------------------------------------------------- | | Auth | `User`, `Auth`, `UserCredential`, `OAuthProvider`, … | | Firestore | `FirebaseFirestoreTypes` namespace (namespaced) + modular helpers from `@react-native-firebase/firestore` | | App Check | `AppCheck`, `AppCheckTokenResult`, … | For Auth v25 alignment details and intentional firebase-js-sdk differences, see the [Auth compare:types triage](https://github.com/invertase/react-native-firebase/blob/main/okf-bundle/packages/auth/compare-types-triage.md) knowledge document and [`yarn compare:types auth`](https://github.com/invertase/react-native-firebase/blob/main/.github/scripts/compare-types/configs/auth.ts) registry. ``` ### AI Logic Source: https://rnfirebase.io/ai/usage ```mdx # Installation This module requires that the `@react-native-firebase/app` module is already setup and installed. To install the "app" module, view the [Getting Started](/) documentation. ```bash # Install & setup the app module yarn add @react-native-firebase/app # Install the ai module yarn add @react-native-firebase/ai ``` # Platform support | | | | -------------------- | ---------------------------------------------------------------------- | | **Platforms** | Android, iOS, Web (firebase-js-sdk interop) | | **New Architecture** | **Not required** — pure JavaScript package with no native TurboModule. | # What does it do Firebase AI Logic gives you access to the latest generative AI models from Google. If you need to call the Gemini API directly from your mobile or web app — rather than server-side — you can use the Firebase AI Logic client SDKs. These client SDKs are built specifically for use with mobile and web apps, offering security options against unauthorized clients as well as integrations with other Firebase services. # Usage ## Generate text from text-only input You can call the Gemini API with input that includes only text. For these calls, you need to use a model that supports text-only prompts (like Gemini 3.1 Flash-Lite). Use `generateContent()` which waits for the entire response before returning. ```js import React from 'react'; import { AppRegistry, Button, Text, View } from 'react-native'; import { getApp } from '@react-native-firebase/app'; import { getAI, getGenerativeModel } from '@react-native-firebase/ai'; function App() { return (