Backbone integration guide

Add Bugsnag to your browser-based JavaScript projects to automatically capture and report exceptions in production.

This documentation is for using version 4+ of Bugsnag JavaScript. If you are using a previous version of Bugsnag JavaScript, see our legacy integration.


There are multiple ways you can add Bugsnag 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="//"></script>
<script>window.bugsnagClient = bugsnag('API_KEY')</script>

Loading the script in this way creates a global function called bugsnag() which can be used to configure and initialize the Bugsnag client.

For guidance on specifying the version, see versioning.


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

# npm
npm install --save bugsnag-js

# yarn
yarn add bugsnag-js

At this point, bugsnag-js will be in your node_modules directory. You can proceed by serving Bugsnag from node_modules or using a bundler.

Serving from node_modules

You can simply serve the bugsnag-js script from your node_modules directory. node_modules/bugsnag-js/dist consists of the following:

File Description
bugsnag.min.js minified, production ready bundle source map for bugsnag.min.js
bugsnag.js unminified, development build

Using a bundler

If you are using something like Browserify, Webpack, or Rollup to bundle your browser JavaScript, you can import Bugsnag in one of the following ways:

// commonjs/node-style import
var bugsnag = require('bugsnag-js')

// ES module-style import
import bugsnag from 'bugsnag-js'

var bugsnagClient = bugsnag('API_KEY')

When considering this approach, be aware that Bugsnag cannot report any errors until it has loaded.

Be sure to initialize Bugsnag at the start of your bundle, or consider creating a separate bundle of high priority code that you can include in the <head/> of your HTML.

Basic configuration

The bugsnag() function initializes the notifier and returns a client object. It can be called either simply with an API key or with a configuration object.

   apiKey: 'API_KEY',
   otherOptions: value

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 {
} catch (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
  • HTTP requests

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: ''

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

Tracking releases

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.

Session tracking

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 behaviour can be disabled using the autoCaptureSessions configuration option.

Bugsnag will automatically report a session each time:

  • The page loads
  • The URL changes via 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.

Next steps

  • View bugsnag-js, the library 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