@react-native-firebase/appinstalled and native config completed per Getting Started (Androidgoogle-services.json, iOSGoogleService-Info.plist, Expo config plugin, or React Native CLI setup). From v26, New Architecture is required for packages with a native bridge.- Install Crashlytics:
npm install --save @react-native-firebase/crashlyticsoryarn add @react-native-firebase/crashlytics, then rebuild native apps (cd ios && pod installon iOS). - Complete Android Additional Setup for React Native CLI Android builds (for Expo, the config plugin covers only steps 2 and 3 of Android Setup).
- Enable Crashlytics for your Firebase project in the Firebase Console. Crashlytics supports only the default Firebase app. There is no firebase-js-sdk web Crashlytics module (
firebase/crashlyticsdoes not exist).
Example Expo Router screen: https://github.com/invertase/react-native-firebase/blob/main/test-expo/app/crashlytics.tsx
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.
# Install & setup the app module
yarn add @react-native-firebase/app
# Install the Crashlytics module
yarn add @react-native-firebase/crashlytics
# If you're developing your app using iOS, run this command
cd ios/ && pod installOnce installed, you must complete the following additional setup steps for Android:
If you're using Expo, make sure to add the
@react-native-firebase/crashlyticsconfig plugin to yourapp.jsonorapp.config.js. On Android it covers only steps 2 and 3 of Android Setup (adding the Crashlytics Gradle plugin dependency and applying the plugin); the Google repository (step 1) and the optional NDK block (step 4) are not added by the plugin, so follow steps 1 and 4 on the Android Setup page. Steps 1 and 4 need a nativeandroid/folder, whichnpx expo prebuildgenerates in an Expo project. Because that folder is regenerated bynpx expo prebuild --cleanand by EAS Build, edits made directly in it may not persist, so a workflow that regenerates it needs those changes made another way (for example a custom config plugin). For instructions on adding the plugin, view the Expo installation section.
You may like reading a short article we wrote that explains how to configure and most importantly verify your crashlytics installation so you are sure it is working. https://invertase.io/blog/react-native-firebase-crashlytics-configuration
{/* prettier-ignore */}
| Platforms | Android, iOS (native Firebase SDK) |
| New Architecture | Required from v26. See Migrating to v26. |
Platform notes: Crashlytics is native-only. The firebase-js-sdk does not ship a modular public API for this product, so there is no web parity surface under firebase/crashlytics. Crashlytics supports only the default Firebase app. React Native Firebase exports SDK_VERSION, getCrashlytics, log, setUserId, setAttribute, setAttributes, recordError, crash, setCrashlyticsCollectionEnabled, checkForUnsentReports, sendUnsentReports, deleteUnsentReports, didCrashOnPreviousExecution and the Crashlytics instance type. The package type declarations also contain a legacy Statics interface, but the package entry point does not export it. Each export is explained in the section that uses it.
Crashlytics helps you to collect analytics and details about crashes and errors that occur in your app. It does this through three aspects:
- Logs: Log events in your app to be sent with the crash report for context if your app crashes.
- Crash reports: Every crash is automatically turned into a crash report and sent.
- Stack traces: Even when an error is caught and your app recovers, the JavaScript stack trace can still be sent.
To learn more, view the Firebase Crashlytics documentation.
Use the log method throughout your app to accumulate extra context for possible crashes that can happen. For additional context, Crashlytics also offers various methods to set attributes for the crash report. You can also test Crashlytics by forcing a crash through the crash method.
Crashlytics also supports sending JavaScript stack traces to the Firebase console. This can be used in any situation where an error occurs but is caught by your own code to recover gracefully. To send a stack trace, pass a JavaScript Error to the recordError method.
In debug builds on Android and iOS, Crashlytics collection is disabled unless
crashlytics_debug_enabledistrueinfirebase.json. While collection is disabled, the native module ignoressetUserId,setAttribute,setAttributesandrecordErrorcalls, andcrashdoes nothing. To enable collection in debug builds, view the enable debug crash logs documentation.
getCrashlytics returns the Crashlytics module instance for the default Firebase app only. Crashlytics does not support secondary Firebase apps. Passing getApp() still resolves that same default-app instance. The firebase-js-sdk does not ship this helper.
import { getApp } from '@react-native-firebase/app';
import { getCrashlytics } from '@react-native-firebase/crashlytics';
function readCrashlyticsInstance() {
const crashlytics = getCrashlytics();
const sameDefaultApp = getCrashlytics(getApp());
console.log('Default app name:', crashlytics.app.name);
console.log('Collection enabled:', crashlytics.isCrashlyticsCollectionEnabled);
console.log('Same instance for default app:', sameDefaultApp === crashlytics);
}Crashlytics is the TypeScript type of that instance (methods such as log and recordError take a Crashlytics as their first argument).
There are various methods to set attributes for the crash report, in order to provide analytics for crashes and help you review them. setUserId identifies the user, setAttribute and setAttributes set custom keys, and log adds a message to the report log.
setUserId,setAttributeandsetAttributesreturn aPromise.logis synchronous and returnsvoid.- Attribute values must be strings.
setAttributethrows if the name or value is not a string, andsetUserIdthrows if the user id is not a string.setAttributesthrows if its argument is not an object. Convert numbers and true or false values withString()before passing them. - While Crashlytics collection is disabled, the native module ignores
setUserId,setAttributeandsetAttributes. It also ignoreslogon Android.
import React, { useEffect } from 'react';
import { View, Button } from 'react-native';
import {
getCrashlytics,
log,
setUserId,
setAttribute,
setAttributes,
crash,
} from '@react-native-firebase/crashlytics';
async function onSignIn(user) {
const crashlytics = getCrashlytics();
log(crashlytics, 'User signed in.');
await Promise.all([
setUserId(crashlytics, user.uid),
setAttribute(crashlytics, 'credits', String(user.credits)),
setAttributes(crashlytics, {
role: 'admin',
followers: '13',
email: user.email,
username: user.username,
}),
]);
}
export default function App() {
useEffect(() => {
log(getCrashlytics(), 'App mounted.');
}, []);
return (
<View>
<Button
title="Sign In"
onPress={() =>
onSignIn({
uid: 'Aa0Bb1Cc2Dd3Ee4Ff5Gg6Hh7Ii8Jj9',
username: 'Joaquin Phoenix',
email: 'phoenix@example.com',
credits: 42,
})
}
/>
{/* WARNING: crash() forces a native crash when collection is enabled and does nothing when it is disabled. Debug builds do not send reports unless crashlytics_debug_enabled is set, and an attached debugger stops the crash first, so test with a release build. */}
<Button title="Test Crash" onPress={() => crash(getCrashlytics())} />
</View>
);
}Even if you catch unexpected errors, in order for your app to recover and behave smoothly you can still report them through
Crashlytics using the recordError method. This will also provide you with the associated stack trace.
recordError(crashlytics, error, jsErrorName?)returnsvoid. The optionaljsErrorNameis added to the report as an extra first stack frame (with the name as the file), which can help you tell reports apart in the console.- The
errorargument must be anErrorinstance. For anything else,recordErrorlogs a console warning and ignores the call. - While Crashlytics collection is disabled, the native module ignores the call.
- Recorded errors are non-fatal events. Crashlytics stores them on the device and sends them with the next fatal event report or when the app restarts.
import React, { useState, useEffect } from 'react';
import { View, Button, Text } from 'react-native';
import { getCrashlytics, log, recordError } from '@react-native-firebase/crashlytics';
export default function App() {
const [status, setStatus] = useState('idle');
useEffect(() => {
log(getCrashlytics(), 'App mounted.');
}, []);
async function loadUsers() {
const crashlytics = getCrashlytics();
log(crashlytics, 'Updating user count.');
try {
const response = await fetch('https://example.com/users.json');
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const users = await response.json();
setStatus(`Loaded ${users.length} users.`);
} catch (error) {
if (error instanceof Error) {
recordError(crashlytics, error, 'LoadUsersError');
setStatus(error.message);
}
console.log(error);
}
}
return (
<View>
<Button title="Load Users" onPress={loadUsers} />
<Text>{status}</Text>
</View>
);
}As Crashlytics will be sending certain information regarding the user, users may want to opt-out of the crash reporting.
This can be done throughout the app with a simple method call to setCrashlyticsCollectionEnabled.
setCrashlyticsCollectionEnabled(crashlytics, enabled)throws ifenabledis not a boolean and returns aPromise.- The module stores the value on the device, so it is used on later launches and takes priority over the
crashlytics_auto_collection_enabledvalue infirebase.json. crashlytics.isCrashlyticsCollectionEnabledis a read-only property that reflects the last value you set, or the startup value if you have not set one.- In a debug build without
crashlytics_debug_enabled, native collection stays disabled even after you callsetCrashlyticsCollectionEnabled(crashlytics, true), although the property then readstrue.
import React, { useState } from 'react';
import { View, Button, Text } from 'react-native';
import {
getCrashlytics,
setCrashlyticsCollectionEnabled,
crash,
} from '@react-native-firebase/crashlytics';
export default function App() {
const [enabled, setEnabled] = useState(getCrashlytics().isCrashlyticsCollectionEnabled);
async function toggleCrashlytics() {
const crashlytics = getCrashlytics();
await setCrashlyticsCollectionEnabled(crashlytics, !enabled);
setEnabled(crashlytics.isCrashlyticsCollectionEnabled);
}
return (
<View>
<Button title="Toggle Crashlytics" onPress={toggleCrashlytics} />
{/* WARNING: crash() forces a native crash when collection is enabled and does nothing when it is disabled. Debug builds do not send reports unless crashlytics_debug_enabled is set, and an attached debugger stops the crash first, so test with a release build. */}
<Button title="Crash" onPress={() => crash(getCrashlytics())} />
<Text>Crashlytics collection is {enabled ? 'enabled' : 'disabled'}</Text>
</View>
);
}When automatic collection is disabled (via firebase.json and/or setCrashlyticsCollectionEnabled), Crashlytics can keep reports on device. The React Native Firebase JS helpers check the isCrashlyticsCollectionEnabled value at the time you call them:
checkForUnsentReportsresolvestruewhen cached unsent reports exist. It throws synchronously if collection is enabled, because reports are sent automatically in that mode.sendUnsentReportsreturnsvoidand calls into native only when collection is enabled. When collection is disabled it is a silent no-op.deleteUnsentReportsdiscards cached reports on the device.didCrashOnPreviousExecutionresolves whether the app crashed during the previous run.
import {
getCrashlytics,
setCrashlyticsCollectionEnabled,
checkForUnsentReports,
sendUnsentReports,
deleteUnsentReports,
didCrashOnPreviousExecution,
} from '@react-native-firebase/crashlytics';
async function reviewQueuedReports() {
const crashlytics = getCrashlytics();
await setCrashlyticsCollectionEnabled(crashlytics, false);
const crashedLastLaunch = await didCrashOnPreviousExecution(crashlytics);
console.log('Crashed on previous execution:', crashedLastLaunch);
// WARNING: checkForUnsentReports throws when Crashlytics collection is enabled.
const hasUnsent = await checkForUnsentReports(crashlytics);
if (hasUnsent) {
// sendUnsentReports only reaches native when collection is enabled;
// with collection disabled it is a silent no-op.
await setCrashlyticsCollectionEnabled(crashlytics, true);
sendUnsentReports(crashlytics);
} else {
await deleteUnsentReports(crashlytics);
}
}Creating a Crashlytics instance installs two handlers, with no code needed on your side:
- A global JavaScript exception handler records unhandled exceptions with their JavaScript stack trace. See Crashlytics Javascript stacktrace issue generation and exception handler chaining for the
firebase.jsonoptions that change this. If@react-native-firebase/analyticsis installed, the handler also logs anapp_exceptionAnalytics event. - A promise rejection tracker records unhandled promise rejections as non-fatal errors with a JavaScript stack trace. This only happens when
__DEV__isfalse, so development builds do not report them.
The native module records nothing while Crashlytics collection is disabled.
The firebase.json options below apply to Android and iOS. See firebase.json for the full list of keys across packages.
Additionally, you can configure whether Crashlytics sends out any reports through the crashlytics_auto_collection_enabled option in
your firebase.json config. If you want users to opt-in, it is recommended that you disable this here and enable it later
with setCrashlyticsCollectionEnabled once they opt-in. When the option is not set, collection is enabled in release builds.
// <project-root>/firebase.json
{
"react-native": {
"crashlytics_auto_collection_enabled": false
}
}Because you have stack traces readily available while you're debugging your app, Crashlytics collection is disabled in debug builds unless you set the crashlytics_debug_enabled option to true in your firebase.json. The option has no effect on release builds, and in a debug build it takes priority over crashlytics_auto_collection_enabled and setCrashlyticsCollectionEnabled.
// <project-root>/firebase.json
{
"react-native": {
"crashlytics_debug_enabled": true
}
}The React Native Firebase Android module depends on the Crashlytics NDK library, so Crashlytics NDK reporting is included in your app. It captures crashes in native C and C++ code.
Symbols for native libraries are not uploaded by default. To get readable native stack traces, enable nativeSymbolUploadEnabled as described in step 4 of Android Setup and run the symbol upload task after each build.
React Native Crashlytics module by default installs a global javascript exception handler, and it records a crash with a javascript stack trace any time an unhandled javascript exception is thrown. Sometimes it is not desirable behavior since it might duplicate issues in combination with the default mode of javascript global exception handler chaining. We recommend leaving JS crashes enabled and turning off exception handler chaining. However, if you have special crash handling requirements, you may disable this behavior by setting the appropriate option to false.
When this option is false and chaining is also false, an unhandled javascript exception is neither recorded nor passed on to the previously installed handler.
// <project-root>/firebase.json
{
"react-native": {
"crashlytics_is_error_generation_on_js_crash_enabled": false
}
}React Native Crashlytics module's global javascript exception handler by default chains to any previously installed global javascript exception handler after logging the crash with the javascript stack trace. In default react-native setups, this means in development you will then see a "red box" and in release mode you will see a second native crash in the Crashlytics console with no javascript stack trace. These duplicate crash reports are probably not desirable, and the one from the chained handler will not have the javascript stack trace. We recommend disabling this once Crashlytics is integrated in testing. It is enabled by default, which makes initial integration testing easier. You may disable exception handler chaining by setting the appropriate option to false. With chaining disabled, the module records the error with its javascript stack trace and then terminates the app itself instead of passing the exception on.
// <project-root>/firebase.json
{
"react-native": {
"crashlytics_javascript_exception_handler_chaining_enabled": false
}
}In case you need to log non-fatal (handled) exceptions on the native side (for example from a try / catch block), you may use the following static methods.
import io.invertase.firebase.crashlytics.ReactNativeFirebaseCrashlyticsNativeHelper;
try {
throw new Exception("Handled native failure");
} catch (Exception e) {
ReactNativeFirebaseCrashlyticsNativeHelper.recordNativeException(e);
}#import <RNFBCrashlytics/RNFBCrashlyticsNativeHelper.h>
@try {
@throw [NSException exceptionWithName:@"HandledNativeFailure"
reason:@"Example handled native failure"
userInfo:nil];
} @catch (NSException *exception) {
NSMutableDictionary *info = [NSMutableDictionary dictionary];
[info setValue:exception.name forKey:@"ExceptionName"];
[info setValue:exception.reason forKey:@"ExceptionReason"];
[info setValue:exception.callStackReturnAddresses forKey:@"ExceptionCallStackReturnAddresses"];
[info setValue:exception.callStackSymbols forKey:@"ExceptionCallStackSymbols"];
[info setValue:exception.userInfo forKey:@"ExceptionUserInfo"];
NSError *error = [[NSError alloc] initWithDomain:@"com.example.app" code:1 userInfo:info];
[RNFBCrashlyticsNativeHelper recordNativeError:error];
}SDK_VERSION is the React Native Firebase Crashlytics package version string exported from @react-native-firebase/crashlytics. The firebase-js-sdk does not export SDK_VERSION from a Crashlytics entry point (there is no @firebase/crashlytics modular package).
import { SDK_VERSION } from '@react-native-firebase/crashlytics';
console.log('Crashlytics package version:', SDK_VERSION);The legacy Statics interface describes the old firebase.crashlytics statics shape that exposed SDK_VERSION. The entry point does not export it, so import SDK_VERSION from @react-native-firebase/crashlytics.

Core / App