React Integration Guide

Source CodeIssues

Installation

Add honeybadger-react as a dependency.

# npm
npm add @honeybadger-io/react --save

# yarn
yarn add @honeybadger-io/react

In your main.js:

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

import './index.css'
import App from './App'
import Honeybadger from 'honeybadger-js'
import ErrorBoundary from '@honeybadger-io/react'

const config = {
    api_key: 'Your Honeybadger API key',
    environment: 'production',
    revision: 'git SHA/project version'
}

const honeybadger = Honeybadger.configure(config)

ReactDOM.render(<ErrorBoundary honeybadger={honeybadger}><App /></ErrorBoundary>, document.getElementById('root'))

HoneyBadgerErrorBoundary Props

honeybadger
The Honeybadger config object.
children
Your root <App /> component.
ErrorComponent (optional — default: "DefaultErrorComponent")
The component that will be rendered in ErrorBoundary children's place when an error is thrown during React rendering. The default value for this prop is the DefaultErrorComponent.

DefaultErrorComponent

class DefaultErrorComponent extends Component {
  render() {
    return (
      <div className='error'>
        <div>An Error Occurred</div>
        <div>{this.error}</div>
        <div>{this.info}</div>
      </div>
    )
  }
}

Reporting errors

Using the example configuration above, you'll install honeybadger-react as React's error handler.

Additionally, by default, an error handler for all JavaScript errors will be attached to the window.onerror handler for JavaScript errors that may originate from React components or other JavaScript on the page.

Because React doesn't intercept all errors that may occur within a React component, errors that bubble up to the window.onerror handler may be missing some React component contextual information, but the stack trace will be available.

If, for some reason, you do not wish to install Honeybadger's error handler on the global window.onerror handler, you may add { onerror: false } to the configuration you're passing to Honeybadger.configure.

You may also manually report errors by directly invoking the honeybadger-js API.

    honeybadger.notify(error)

See the full documentation for more options.

Note: React handles exceptions slightly differently in development mode than in production. As a result, in development mode only, the error boundary component you create will capture the error and add React context, but React will essentially re-throw the error and it will bubble up to the window.onerror handler (without the React context data). This behavior will not occur when your React application is built for production.

Identifying users

Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with honeybadger.setContext:

honeybadger.setContext({
  user_id: 123,
  user_email: 'user@example.com'
});

Sending additional context

Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke setContext.

honeybadger.setContext({
  active_organization: 55,
  custom_configuration: false  
});

Clearing context

If your user logs out or if your context changes during the React component lifetime, you can set new values as appropriate by invoking setContext again.

Additionally, if needed, you can clear the context by invoking resetContext:

// Set the context to {}
honeybadger.resetContext();

Advanced usage

honeybadger-react is built on honeybadger-js.

See the Honeybadger JavaScript integration documentation for additional customization options.

Tracking deploys

As with vanilla JavaScript applications, you can notify Honeybadger when you've deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the 'revision' field in the configuration passed to Honeybadger.configure).

Here's a simple curl script to record a deployment:

HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="git SHA/project version" \
HONEYBADGER_API_KEY="project api key" \
  curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&api_key=$HONEYBADGER_API_KEY"

Be sure that the same revision is also configured in the honeybadger-react library. Read more about deploy tracking in the API docs.

Source map support

Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. Learn more about source maps.

If you're building your React app with Webpack, you can automatically upload your source maps to honeybadger using the honeybadger-webpack plugin. You can see examples of different configuration options in the honeybadger-webpack documentation.

Sample application

A minimal implementation is included in the example/ folder in the honeybadger-react repository.

To run it from the command line, enter the following commands in your shell:

cd example
yarn install
REACT_APP_HONEYBADGER_API_KEY=yourkey yarn start

Observe the command-line output to determine the appropriate URL to connect to in your browser (usually http://localhost:3000/).