React Native

Installation

In the root of your React Native project, install raven-js via npm:

$ npm install --save raven-js

At the top of your main application file (e.g. index.ios.js and/or index.android.js), add the following code:

var React = require('react');

var Raven = require('raven-js');
require('raven-js/plugins/react-native')(Raven);

Configuring the Client

Now we need to set up Raven.js to use your Sentry DSN:

Raven
  .config('___PUBLIC_DSN___', { release: RELEASE_ID })
  .install();

RELEASE_ID is a string representing the “version” of the build you are about to distribute. This can be the SHA of your Git repository’s HEAD. It can also be a semantic version number (e.g. “1.1.2”), pulled from your project’s package.json file. More below.

About Releases

Every time you build and distribute a new version of your React Native app, you’ll want to create a new release inside Sentry. This is for two important reasons:

  • You can associate errors tracked by Sentry with a particular build
  • You can store your source files/source maps generated for each build inside Sentry

Unlike a normal web application where your JavaScript files (and source maps) are served and hosted from a web server, your React Native code is being served from the target device’s filesystem. So you’ll need to upload both your source code AND source maps directly to Sentry, so that we can generate handy stack traces for you to browse when examining exceptions triggered by your application.

Generating and Uploading Source Files/Source Maps

To generate both an application JavaScript file (main.jsbundle) and source map for your project (main.jsbundle.map), use the react-native CLI tool:

react-native bundle \
  --dev false \
  --platform ios \
  --entry-file index.ios.js \
  --bundle-output main.jsbundle \
  --sourcemap-output main.jsbundle.map

This will write both main.jsbundle and main.jsbundle.map to the current directory. Next, you’ll need to create a new release and upload these files as release artifacts.

Naming your Artifacts

In Sentry, artifacts are designed to be “named” using the full URL or path at which that artifact is located (e.g. https://example.org/app.js or /path/to/file.js/). Since React Native applications are installed to a user’s device, on a path that includes unique device identifiers (and thus different for every user), the React Native plugin strips the entire path leading up to your application root.

This means that although your code may live at the following path:

/var/containers/Bundle/Application/{DEVICE_ID}/HelloWorld.app/main.jsbundle

The React Native plugin will reduce this to:

/main.jsbundle

Therefore in this example, you should name your artifacts as “/main.jsbundle” and “/main.jsbundle.map”.

Source Maps with the Simulator

When developing with the simulator, it is not necessary to build source maps manually, as they are generated automatically on-demand.

Note however that artifact names are completely different when using the simulator. This is because instead of those files existing on a path on a device, they are served over HTTP via the React Native packager.

Typically, simulator assets are served at the following URLs:

If you want to evaluate Sentry’s source map support using the simulator, you will need to fetch these assets at these URLs (while the React Native packager is running), and upload them to Sentry as artifacts. They should be named using the full URL at which they are located, including the query string.

Expanded Usage

It’s likely you’ll end up in situations where you want to gracefully handle errors. A good pattern for this would be to setup a logError helper:

function logException(ex, context) {
  Raven.captureException(ex, {
    extra: context
  });
  /*eslint no-console:0*/
  window.console && console.error && console.error(ex);
}

Now in your components (or anywhere else), you can fail gracefully:

var Component = React.createClass({
    render() {
        try {
            // ..
        } catch (ex) {
            logException(ex);
        }
    }
});