Installing and Configuring React Native Firebase Crashlytics

Hello there! Crash reporting is fundamental to improving and maintaining app quality, and @react-native-firebase/crashlytics has some useful improvements even long-time users will love. This article shows new users the easiest path integrating crash reporting in their apps for the first time, and helps existing users take advantage of the new features.

For new users integrating Crashlytics into their app for the first time, please make sure you follow the installation instructions first – including the Android-specific ones, then come back here and continue reading.

Testing Your Configuration

The most important part of a crash-reporting integration is testing it to make sure you can trust it in production. In @react-native-firebase/crashlytics v11.3.0+, we improved all of the Crashlytics configuration-related log messages to make verifying your integration easier.

The path detailed below is our recommendation to configure and verify your integration. All of these instructions assume you are on a macOS machine so you may test both platforms.

Android Installation Verification

1. Create a firebase.json file in the root directory of your react-native app, with these Crashlytics-related keys set to these specific values:

{
  "react-native": {
    "crashlytics_debug_enabled": true,
    "crashlytics_disable_auto_disabler": true,
    "crashlytics_auto_collection_enabled": true,
    "crashlytics_is_error_generation_on_js_crash_enabled": true,
    "crashlytics_javascript_exception_handler_chaining_enabled": true
  }
}

2. Add a Button element to the App.js file that creates a JavaScript crash when you touch it:

 {
    undefinedVariable.notAFunction();
  }}
/>

3. Start the Android emulator

4. Start the react-native bundler (yarn start or similar)

5. Watch the emulator logs for crashlytics items with this command in a terminal:

adb logcat | grep -i crash

6. Start the app! You should see a lot of Crashlytics-related initialization information in the logcat as your app starts. They should show that Crashlytics is installed and running, and they will show exactly how Crashlytics is configured. Pay careful attention to these messages – this is how you confirm that crash collection is enabled for your current config and how you confirm future changes as needed

7. Tap on the “Javascript Crash Now” button. You should see log messages in logcat indicating that a crash was handled, and react-native should show you a “red box error” displaying crash details as well

8. Crash reports are only sent to the Firebase console when the app restarts. Close the app on the emulator and start it again. You should see more information in the android logs indicating the crash report is sent. After a reasonable delay – maybe a few minutes, sometimes longer – you should see the report in the Crashlytics console for your android app.

Congratulations! You have successfully proven a correct Crashlytics integration on Android.

iOS Installation Verification

For iOS we reuse the first 2 steps from Android configuration above (creating the firebase.json config and adding a crash button to App.js). Then we continue with these steps:

1. Make sure pods are installed (npx pod-install can help)

2. Start the app with yarn ios (or your preferred method) to make sure the iPhone Simulator is running

3. Follow the Simulator logs to see crash-related messages with a command like this from the terminal:

xcrun simctl spawn booted log stream --level debug --style compact | grep -i crash

4. Close the app and restart it from the Terminal. Verify that you see the crashlytics startup messages showing crashlytics is integrated and initialized correctly. Note: debuggers intercept crash reports before crashlytics can get them. If you start the iOS app from Xcode, there will be a debugger attached to the app, meaning you will not see the crash reports in the Firebase web console. New in v11.3.0+ of @react-native-firebase/crashlytics is a log message that warns you of this situation even, since that has been a source of developer confusion in the past

5. Tap the “Javascript Crash Now” button, and make sure you see that crashlytics has recorded the error

6. Reports are sent at app start, so close and restart the app to send the report. Now verify that you see the error in the Firebase web console for your iOS app and that is a “Crash” event type

Congratulations! You have now successfully proven a correct integration on iOS

Production Configuration / New Feature

This section is where long-time users should pay attention, as there is one new configuration setting you may alter and we recommend you take advantage of it.

Now that you have proven you can successfully capture reports and see them in the crashlytics console, you should have confidence your integration is working. However, with the configuration testing settings we used, you will see duplicate reports for crashes in production and you will be collecting crash reports in debug builds – things most people do not want in their final configuration.

We recommend making these changes once you have tested your integration:

1. Set “crashlytics_debug_enabled” to false – you have direct access to crash traces in your development environment, no need to clutter the console with development reports
2. Set “crashlytics_javascript_exception_handler_chaining_enabled” to false – this is new and useful for long-time users – details below

Configurable Exception Handler Chaining

@react-native-firebase/crashlytics included the ability to log javascript-level stack traces for a long time, and by default it logged and reported javascript errors. However, they were logged as “Non-Fatal” crashes so they were easy to miss. Additionally, the react-native framework installs a default javascript global exception handler that performs a native crash for unhandled javascript exceptions. These show up in the Firebase console as a Fatal crash for the same error but with no javascript stack, resulting in one Non-Fatal crash (with javascript stack) and one Fatal crash (with a less useful stack trace) for the same error.

With @react-native-firebase/crashlytics v11.3.0+, Firebase Crashlytics now has the ability to flag javascript-level crashes as “Fatal”. This is a big new feature for Crashlytics! It makes the javascript-level crash reports, with javascript stacktraces, much more useful.

To take full advantage of this, our new recommendation is to disable chaining to the default react-native global exception handler in your normal configuration. This means that you will see one fatal / crash report in the Firebase Crashlytics console for each javascript error, and no duplicate reports. You will still receive native crash reports for non-javascript errors as you would expect, but you will not receive duplicate reports for javascript errors.

We understand some apps have very specific error reporting requirements, or they may have default exception handlers of their own. If this sounds like your app, carefully consider how you use this new setting. Though we recommend turning off exception handler chaining, to be safe by default and make sure no exceptions are missed we leave exception handler chaining on by default.

Conclusion

That’s it!

In the past developers have had a hard time verifying that Crashlytics was working, and it was difficult to receive useful, actionable reports. But if you completed the above steps, now you can:

• Easily confirm any crashlytics integration is successfully configured the way you expect by viewing native logs
• Test crash reporting any time, with the knowledge you must avoid debuggers and restart the app to see the report in the console
• Carefully control how reports are generated when exceptions happen, so you only get the reports you want

Happy Coding!

-Mike H