Add BugSnag to your JavaScript projects to automatically capture and report errors in production.
This documentation is for version 6 of the BugSnag JavaScript notifier. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.
Our universal JavaScript notifier automatically detects whether it is running in Node.js or in the browser. That means this guide is the same whether you are running on the front-end, back-end or both. Platform-specific differences where they do exist will be noted.
This page contains a general guide to error reporting with BugSnag. If you use a particular framework listed below, click through to see a specifically tailored guide:
The best way to install BugSnag is to get the @bugsnag/js npm package from the npm registry using npm or yarn:
npm install --save @bugsnag/js
# or
yarn add @bugsnag/js
Alternatively, if you only want to use BugSnag in the browser, for the most simple installation you can load it from our CDN:
<script src="//d2wy8f7a9ursnm.cloudfront.net/v6/bugsnag.min.js"></script>
<script>window.bugsnagClient = bugsnag('API_KEY')</script>
See the CDN guide for more information.
Depending on which module system you are using, you’ll need to include BugSnag in one of the following ways:
// commonjs/node-style require
var bugsnag = require('@bugsnag/js')
// ES module-style import
import bugsnag from '@bugsnag/js'
Note: if you are using the CDN, bugsnag will be defined as a global variable and you don’t need to import or require it.
The simplest way to configure the client is to provide your API key as a string:
var bugsnagClient = bugsnag('YOUR_API_KEY')
To specify any additional configuration options, supply an object instead:
var bugsnagClient = bugsnag({
apiKey: 'YOUR_API_KEY',
otherOptions: value
})
For information on values that can be set in the configuration object, see configuration options.
Type definitions provided and will be picked up automatically by the TypeScript compiler when you import any of the top-level @bugsnag/* packages.
After completing installation and basic configuration, unhandled exceptions and unhandled promise rejections will be automatically reported.
Sometimes it is useful to manually notify BugSnag of a problem. To do this, call bugsnagClient.notify(). For example:
try {
something.risky()
} catch (e) {
bugsnagClient.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)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.
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.
By default, BugSnag captures the following events as breadcrumbs.
For more information or to disable particular classes of automatic breadcrumb generation see configuration options.
You can can use the leaveBreadcrumb(message, metadata) method to log potentially useful events in your own applications:
bugsnagClient.leaveBreadcrumb('User clicked a button')
The time and order of breadcrumbs will be recorded and shown in the dashboard.
The metadata argument is optional and can be used to attach to additional information to a breadcrumb. This can be a one-level-deep key → value mapping object:
bugsnagClient.leaveBreadcrumb('Order summary requested', {
amount: 4500,
currency: 'EUR',
nItems: 21
})
Breadcrumbs are not yet supported on Node.
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 provide or modify the user information of an error report by supplying the user option to a notify call, or using a beforeSend callback to modify report.user. For information on doing so, see customizing error reports.
In the browser, or in other environments where your process will only be serving a single user (such as a CLI app in Node.js), you can attach user info directly on the bugsnagClient instance. This will then be sent along with all subsequent errors.
// Attach to the client object
bugsnagClient.user = {
id: '3',
name: 'Bugs Nag',
email: 'bugs.nag@bugsnag.com'
}
Configure your app version to see the release that each error was introduced in.
bugsnag({ 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 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 autoCaptureSessions configuration option.
In the browser, BugSnag will automatically report a session each time:
history.pushState() or history.replaceState()If you want control over what is deemed a session, you can switch off automatic session tracking with the autoCaptureSessions option, and call bugsnagClient.startSession() when appropriate for your application.
By default, sessions are only reported in Node.js if you are using one of the server integrations:
@bugsnag/plugin-express@bugsnag/plugin-restify@bugsnag/plugin-koaWhen using one of these integrations, BugSnag will record a session every time a request is served. A summary of sessions recorded will periodically sent to BugSnag.
If you are working with different kind of application or not using one of the server integrations above, you should call bugsnagClient.startSession() to indicate each time a session has started.
@bugsnag/js, the library powering BugSnag’s JavaScript error reporting, on GitHub