Configuration options

The object passed to bugsnag({ … }) can be used to configure and customize the behaviour of the library. Additionally, some properties of the client object returned by the bugsnag(…) function can be set.

apiKey

Set your Bugsnag API key. You can find your API key in your project settings from your Bugsnag dashboard:

bugsnag('API_KEY')
bugsnag({ apiKey: 'API_KEY' })

appVersion

Setting the appVersion lets you see at a glance when errors first and last happened in your code:

bugsnag({ appVersion: '4.10.0' })

autoBreadcrumbs

By default, Bugsnag will collect navigation, interaction and console breadcrumbs. To switch all of these off, set the autoBreadcrumbs option to false:

bugsnag({ autoBreadcrumbs: false })

For more options on specifying specific types of breadcrumbs, see consoleBreadcrumbsEnabled, interactionBreadcrumbsEnabled, maxBreadcrumbs.

autoNotify

By default, we will automatically notify Bugsnag of any uncaught exceptions and unhandled promise rejections. If you want to stop this from happening, you can set autoNotify to false:

bugsnag({ autoNotify: false })

beforeSend

To modify error reports before they are sent, or to prevent them from being sent at all, beforeSend provides access the report data structure and the means to mutate or ignore it:

bugsnag({
  beforeSend: function (report) {
    // Adjust report here
  }
})

For more information, see Customizing error reports.

consoleBreadcrumbsEnabled

Wrapping console methods to leave breadcrumbs has the side effect of messing with line numbers in log messages. Therefore when realeseStage='development' console breadcrumbs are disabled. If you want to disable them in other environments, or switch them on in development, use this option.

Setting this option explicitly will trump the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable console breadcrumbs
bugsnag({ consoleBreadcrumbsEnabled: false })

// disable all other breadcrumbs but enable console breadcrumbs
bugsnag({ autoBreadcrumbs: false, consoleBreadcrumbsEnabled: true })

endpoint

By default, Bugsnag sends reports to //notify.bugsnag.com. Note the protocol-relative address. This means that if the page is loaded via http:// it will send reports to http://notify.bugsnag.com and via https:// it will send reports to https://notify.bugsnag.com. This is important for older browsers, such as IE8/9 which will only send cross-domain requests to addresses with a matching protocol.

You will need to configure the endpoint if you are running Bugsnag On-premise.

bugsnag({ endpoint: '//notify-bugsnag.example.com' })

interactionBreadcrumbsEnabled

By default, breadcrumbs are left when the user clicks/touches the page.

Setting this option explicitly will trump the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable interaction breadcrumbs
bugsnag({ interactionBreadcrumbsEnabled: false })

// disable all other breadcrumbs but enable interaction breadcrumbs
bugsnag({ autoBreadcrumbs: false, interactionBreadcrumbsEnabled: true })

maxBreadcrumbs

By default, up to 20 breadcrumbs will be sent along with each error report. You can optionally configure this up to a hard limit of 40.

bugsnag({ maxBreadcrumbs: 40 })

maxEvents

Configure the maximum number of events that can be sent per page. The count is reset each time the location changes via pushState/replaceState. The default value is 10 and the maximum allowed value is 100.

bugsnag({ maxEvents: 100 })

By default, breadcrumbs are left on page loads, DOMContentLoaded events, pushState/replaceState calls, and popstate/hashchange events.

Setting this option explicitly will override the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable navigation breadcrumbs
bugsnag({ navigationBreadcrumbsEnabled: false })

// disable all other breadcrumbs but enable navigation breadcrumbs
bugsnag({ autoBreadcrumbs: false, navigationBreadcrumbsEnabled: true })

notifyReleaseStages

By default, we will notify Bugsnag of exceptions that happen in any releaseStage. If you would like to change which release stages notify Bugsnag of errors you can set notifyReleaseStages.

bugsnag({ notifyReleaseStages: [ 'production', 'staging' ] })

releaseStage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to Bugsnag.

By default, if the URL contains localhost this is set to development, otherwise it takes the value from process.env.NODE_ENV. The default value in all other circumstances is production.

bugsnag({ releaseStage: 'staging' })

Client properties

client.app.version

You should set client.app.version to your application’s version number/identifier (if it has one). This is useful for finding out when errors are introduced or fixed. Additionally Bugsnag can re-open closed errors if a later version of the app has a regression.

bugsnagClient.app.version = '1.2.3'

client.app.releaseStage

Set the release stage that is reported to Bugsnag. Note that you can also set releaseStage via this interface.

bugsnagClient.app.releaseStage = 'staging'

context

By default, Bugsnag sets the context for each report to window.location.pathname. Context is given high visual prominence in the dashboard, so if the pathname is not useful to you in tracking down errors, you can set it to something else.

bugsnagClient.context = 'ctx-id-1234'

device

By default, the notifier will set some device properties: time, locale and userAgent. If you want to collect additional information or override one of these values you can do so here.

bugsnagClient.device = { orientation: 'portrait', hasTouch: true }

metaData

Set any metaData that you want to send with all reports by attaching it to the client object.

bugsnagClient.metaData = {
  company: {
    name: "Acme Co.",
    country: "uk"
  }
}

request

By default, the notifier will capture { url: window.location.href } when a report is sent. You can capture any other useful information about the request that loaded the page here.

bugsnagClient.request = { body: 'item=1234,' }

user

The user property is used to populate the “User” tab of reported errors on your Bugsnag dashboard, and the id property is used to determine the number of users affected by a particular error. You can attach any additional user information here.

bugsnagClient.user = {
  id: '3',
  name: 'Bugs Nag',
  email: 'bugs.nag@bugsnag.com',
  roles: [ 'subscriber' ]
}