@honeybadger-io/react-native

Honeybadger for React Native

A React Native library for integrating Honeybadger into your React Native iOS and Android apps.

Installation

From the root directory of your React Native project:

npm install "@honeybadger-io/react-native"
cd ios && pod install

The above will download the Honeybadger React Native library and add it as a dependency of your project. The iOS step is required to properly add the library to the Xcode project through CocoaPods. Android doesn't require a separate step.

Initialization

Add the following to your App.js file to initialize the Honeybadger library.

import Honeybadger from "@honeybadger-io/react-native";

export default function App() {
  Honeybadger.configure("{{PROJECT_API_KEY}}");
  // ...
}

You can log into your Honeybadger account to obtain your API key.

Configuration

The configure method takes additional configuration options.

Name	Type	Required	Default	Example
apiKey	String	YES	""	"hb-api-key-1234"
reportErrors	Boolean	NO	true
revision	String	NO	""	"8afb34a"
projectRoot	String	NO	""	"/path/to/project"

  Honeybadger.configure(
    "hb-api-key-1234",
    "8afb34a",
    "/path/to/project"
  );

The reportErrors parameter determines if errors are to be sent to Honeybadger. This is set to true by default. In certain environments, say, during development, it could be useful to set reportErrors to false to prevent errors from being posted to your Honeybadger account.

Usage Examples

iOS, Android, and JavaScript errors will be automatically handled by the Honeybadger React Native library, by default. But you can also use the following API to customize error handling in your application.

Honeybadger.notify(error, additionalData)

You can use the notify method to send any kind of error, exception, object, String, etc. If sending an error or exception, the Honeybadger React Native library will attempt to extract a stack trace and any relevant information that might be useful. You can also optionally provide additionalData to the notify method, as either a string or an object, to include any relevant information.

Honeybadger.setContext(context)

If you have data that you would like to include whenever an error or an exception occurs, you can provide that data using the setContext method. Provide an object as an argument. You can call setContext as many times as needed. New context data will be merged with any previously-set context data.

Honeybadger.setContext({
  user_id: "123abc",
  more: "some additional data",
});

Honeybadger.resetContext()

If you've used Honeybadger.setContext() to store context data, you can use Honeybadger.resetContext() to clear that data.

Honeybadger.setLogLevel(logLevel)

Sets the logging level for the Honeybadger library.

  Honeybadger.setLogLevel("debug");

The following values are accepted:

Value	Meaning
"debug"	Everything will be logged to console.
"warning"	Only warnings will be logged to console.
"error"	Only errors will be logged to console.

The default logging level is "warning".

Source Maps

This package includes a script that will help you generate source maps for your project. To generate source maps for both iOS and Android, run the following from your project root directory.

npx honeybadger-generate-sourcemaps

The operation might take some time, as React Native needs to build production-ready bundles and their respective source map files for both iOS and Android. Upon completion, you will find the sourcemap-ios and sourcemap-android files in your project root directory. You can then upload these files to Honeybadger to view descriptive stack trace symbols in your production builds.

Example Projects

The examples directory contains two minimal React Native projects, demonstrating the use of the Honeybadger library. One was created using the React Native CLI Quickstart instructions and one using the Expo Go Quickstart instructions from react-native. Please review those instructions, as you may need to install Android Studio, Xcode, etc.

react-native-cli

npm install
cd ios && pod install && cd ..
npx react-native start

In a new shell:

npx react-native run-ios

or

npx react-native run-android

expo-app

npm install
npm run ios

or

npm install
npm run android

When the app opens, enter your API key, press "Configure", and then test your setup by using the button to throw an error.

License

The Honeybadger React Native library is MIT-licensed. See the MIT-LICENSE file in this folder for details.

Changelog

5.2.0 (2023-03-27)

Features

• core: accept a backtrace passed in the notice (#1049) (9c56a9f)