React integration guide

Add Bugsnag to your React projects to automatically capture and report exceptions in production.

This documentation is for using version 4+ of Bugsnag JavaScript with the bugsnag-react plugin. If you are using previous versions of Bugsnag JavaScript, see our legacy integration.

The React plugin is made for React 16+. For applications on early React versions, see our JavaScript guide instead.

Installation

There are multiple ways you can add bugsnag-react to your project. Choose the one that best fits your setup.

The simplest approach is to include the notifier via a <script/> tag in the <head/> of your HTML:

<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-plugins/v4/bugsnag.min.js"></script>
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-plugins/v1/bugsnag-react.min.js"></script>

For guidance on specifying the bugsnag-js version, see versioning.

npm/yarn

Install bugsnag-js and bugsnag-react via npm or yarn from the command line:

npm i --save bugsnag-js bugsnag-react
# or
yarn add bugsnag-js bugsnag-react

Basic configuration

As of version 16, React supports error handling in components with a feature called error boundaries. The plugin provides an component which can be used to capture errors within component trees. When errors happen, they are reported to Bugsnag along with any React-specific info that was available at the time.

In the dashboard, you’ll see errors reported with “React” tab with the extra debugging info. For example:

img

Depending on how your application is structured, configuration differs slightly. Choose the appropriate configuration below.

Inline script tag

The script tag creates a global function called bugsnag__react which needs to be passed a reference to the React object. Ensure that React is defined before calling this function.

<script>
  window.bugsnagClient = bugsnag('API_KEY')
</script>
<script>
  // in your react app…
  var ErrorBoundary = bugsnagClient.use(bugsnag__react(React))
  ReactDOM.render(
    <ErrorBoundary>
      <YourApp />
    </ErrorBoundary>,
    document.getElementById('app')
  )
</script>

Bundled

// initialize bugsnag ASAP, before other imports
import bugsnag from 'bugsnag-js'
const bugsnagClient = bugsnag('API_KEY')

import ReactDOM from 'react-dom'
import React from 'react'
import createPlugin from 'bugsnag-react'

// wrap your entire app tree in the ErrorBoundary provided
const ErrorBoundary = bugsnagClient.use(createPlugin(React))
ReactDOM.render(
  <ErrorBoundary>
    <YourApp />
  </ErrorBoundary>,
  document.getElementById('app')
)

For information on values that can be set in the configuration object, see configuration options.

TypeScript support

TypeScript definitions are provided. When installed via npm/yarn, simply import bugsnag from 'bugsnag-js' in your .ts files.

If you are using TypeScript in tandem with the CDN/self-hosted approach, you should install bugsnag-js via the bugsnag-js npm package and then refer to the included global.d.ts type definitions with a triple-slash directive:

/// <reference path="./node_modules/bugsnag-js/types/global.d.ts" />

Reporting unhandled exceptions

After completing installation and basic configuration, unhandled exceptions and unhandled promise rejections will be automatically reported.

Reporting handled exceptions

Sometimes it is useful to manually notify Bugsnag of a problem. To do this, call client.notify(). For example:

try {
  something.risky()
} catch (e) {
  bugsnagClient.notify(e)
}

When reporting handled exceptions, it’s often helpful to send custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture the following data for every exception:

  • The current URL
  • Browser name, version, user agent and locale
  • Operating system
  • Release stage (production, beta, staging, etc)

Custom diagnostics

Error reports have a metaData property where arbitrary data can be attached. Top-level properties of metaData will render as tabs in the Bugsnag dashboard. Custom metaData can be supplied globally:

bugsnagClient.metaData = {
  company: {
    name: "Acme Co.",
    country: "uk"
  }
}

For additional options on attaching custom metaData, see customizing error reports.

Leaving breadcrumbs

Breadcrumbs allow you to see a log of actions that led up to an error. Error reports automatically include breadcrumbs for the last 20 events which occurred.

Automatically captured breadcrumbs

By default, Bugsnag captures common events as breadcrumbs including:

  • Clicks
  • Errors
  • Console logs, warnings, and errors
  • Page load, hide, and show
  • DOMContentLoaded events
  • Pop state
  • History push state and replace state
  • Hash change

For more information or to disable particular classes of automatic breadcrumb generation see configuration options.

Attaching custom breadcrumbs

bugsnagClient.leaveBreadcrumb('increased volume')

You can also attach additional diagnostic data to breadcrumbs as follows:

bugsnagClient.leaveBreadcrumb('increased volume', {
  from: 5,
  to: 11
})

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

// Attach to the client object
bugsnagClient.user = {
  id: '3',
  name: 'Bugs Nag',
  email: 'bugs.nag@bugsnag.com'
}

You can modify the user information of an error report using a beforeSend callback. For information on doing so, see customizing error reports.

Tracking deploys

By sending your source revision or application version when you deploy a new version, you’ll be able to see in which deployment each error was introduced and link stacktrace lines with the related code on GitHub. Integrate a call to our deploy tracking API into your deployment process.

Next steps

  • View bugsnag-react and bugsnag-js, the libraries powering this integration, on GitHub
  • For bundled or minified JavaScript, ensure we can access your source maps so that your error reports include the original source code
  • Get support for your questions and feature requests