JavaScript upgrade guide

The Bugsnag JS library has seen major improvements. Follow this guide to access the most up-to-date features.

Upgrading to version 4

Our JS library has gone through some major improvements, and there are some changes you’ll need to make to get onto the new version.

Using the Bugsnag script tag

In the past, you could load Bugsnag from the CDN without specifying a version. Since this major update has breaking changes, you will need to update the url your script tag points to.

- <script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-3.min.js" data-apikey="API_KEY"></script>
+ <script src="//d2wy8f7a9ursnm.cloudfront.net/v4/bugsnag.js"></script>
+ <script>window.bugsnagClient = bugsnag('API_KEY')</script>

Using npm/yarn

If you’re using a package manager, you should run something like:

npm install --save bugsnag-js@4
# or
yarn add bugsnag-js@4

Create the bugsnag client

Previously, Bugsnag loaded automatically after the script tag was imported. In version 4, you’ll need to explicitly create your client with configuration options (by default, the only option specified is the API key).

<script>
-  Bugsnag.notify(err)
+  window.bugsnagClient = bugsnag('API_KEY')
+  bugsnagClient.notify(err)
</script>

Configuration

Here’s an example of how to configure the library with the most common options:

window.bugsnagClient = bugsnag({
  apiKey: 'API_KEY'
  appVersion: '1.2.3',
  releaseStage: 'staging',
  notifyReleaseStages: [ 'staging', 'production' ],
  metaData: { /* some metaData to attach to every report */ },
  user: { id: '123', name: 'B. Nag', email: 'bugs.nag@bugsnag.com' },
  beforeSend: function (report) { /* amend or ignore the report */ }
})

See the full configuration options documentation for more information.

Usage

The syntax for reporting errors and leaving breadcrumbs in version 4 is as follows:

bugsnagClient.notify(err, opts)
bugsnagClient.leaveBreadcrumb('name', { /* metaData */ })

The following usage will no longer work:

Bugsnag.notifyException(err)
Bugsnag.notify(name, message)

Dropping support for IE6/7

We have removed support for IE 6 and 7. If you are still interested in reporting errors from users on IE6/7, v3 can be used, but note that it will be in maintenance mode (no new features will be added). For more information, see the version 3 integration guide.

Endpoint

Previous versions of the bugsnag-js notifier sent error reports to a js-specific endpoint. From v4 forward, errors will be sent to the general notify.bugsnag.com endpoint.

On-premise Bugsnag users should note that if they have configured the endpoint field, they’ll need to make the following change:

- endpoint: '//notify-bugsnag.example.com/js'
+ endpoint: '//notify-bugsnag.example.com'

If you have not configured the endpoint field, you do not need to make the change.