Add BugSnag to your React projects to automatically capture and report errors in production.
New to BugSnag? Create an account
Looking for performance monitoring? See our performance guide
Install BugSnag and the BugSnag / React integration from the npm registry using npm or yarn:
npm install --save @bugsnag/js @bugsnag/plugin-react
# or
yarn add @bugsnag/js @bugsnag/plugin-react
The latest available version of @bugsnag/js
is v8.1.3
.
This documentation is for version 7+ of the BugSnag JavaScript notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.
Depending on which module system you are using, you’ll need to include BugSnag in one of the following ways:
// ES module-style import
import Bugsnag from '@bugsnag/js'
import BugsnagPluginReact from '@bugsnag/plugin-react'
// commonjs/node-style require
var Bugsnag = require('@bugsnag/js')
var BugsnagPluginReact = require('@bugsnag/plugin-react')
To start BugSnag with the React integration, instantiate the BugsnagPluginReact
and pass it along with your API key to Bugsnag.start
as configuration:
Bugsnag.start({
apiKey: 'YOUR_API_KEY',
plugins: [new BugsnagPluginReact()],
otherOptions: value
})
You can find your API key in Project Settings from your BugSnag dashboard.
For information on values that can be set in the configuration object, see configuration options.
The BugSnag ErrorBoundary
allows you to capture React render errors in your application. You can also use the FallbackComponent
to display a custom error screen to your users:
// Start BugSnag first...
Bugsnag.start({...})
// Create the error boundary...
const ErrorBoundary = Bugsnag.getPlugin('react').createErrorBoundary(React)
const ErrorView = () =>
<div>
<p>Inform users of an error in the component tree.</p>
</div>
const App = () => {
// Your main App component
}
export default () =>
<ErrorBoundary FallbackComponent={ErrorView}>
<App />
</ErrorBoundary>
See our guide on capturing render errors
to learn more about the ErrorBoundary
and FallbackComponent
.
Type definitions are provided and will be picked up automatically by the TypeScript compiler when you import any of the top-level @bugsnag/*
packages.
Source maps enable BugSnag to show you the original file, line, method and surrounding code in your stacktraces.
Use the source maps guide to ensure your tooling outputs source maps, and the build integrations guide to find out how to upload them to BugSnag.
After completing installation and basic configuration, unhandled exceptions and unhandled promise rejections will be reported and automatically appear on your BugSnag dashboard.
Sometimes it is useful to manually notify BugSnag of a problem. To do this, call Bugsnag.notify()
. For example:
try {
something.risky()
} catch (e) {
Bugsnag.notify(e)
}
When reporting handled errors, it’s often helpful to send custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.
BugSnag will automatically capture the following data for every exception:
<script/>
tag)It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to BugSnag.
The following adds a map of data to the “company” tab on the BugSnag dashboard for all captured events:
Bugsnag.start({
onError: function (event) {
event.addMetadata('company', {
name: "Acme Co.",
country: "uk"
})
}
})
For more information, see Customizing error reports.
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.
You can set the user information of an error report using the user
configuration property when BugSnag starts or via an onError
callback.
Bugsnag.start({
onError: function (event) {
event.setUser('3', 'bugs.nag@bugsnag.com', 'Bugs Nag')
}
})
For information on doing so, see Adding user data.
In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.
By default, BugSnag captures the following events as breadcrumbs.
You can use the leaveBreadcrumb
method to log potentially useful events in your own applications:
Bugsnag.leaveBreadcrumb('Button clicked')
BugSnag will keep track of the time and order of the breadcrumbs and show them on your dashboard. Additional data can also be attached to breadcrumbs by providing the optional metadata
parameter.
For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.
BugSnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.
Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions
configuration option.
In the browser, BugSnag will automatically report a session each time:
history.pushState()
or history.replaceState()
For more information about manually controlling session tracking, see Capturing sessions.
Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.
Bugsnag.addFeatureFlag('Checkout button color', 'Blue')
Bugsnag.addFeatureFlag('New checkout flow')
For more information, see Feature flags & experiments.
Configure your app version to see the release that each error was introduced in.
Bugsnag.start({ appVersion: '4.10.0' })
Then set up a build tool integration to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.
@bugsnag/js
, the library powering BugSnag for JavaScript, on GitHub