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

It is possible to set your BugSnag API key here but usually you would set it in your app.json. You can find your API key in your project settings from your BugSnag dashboard:

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

appStateBreadcrumbsEnabled

By default, breadcrumbs are collected when the application enters or exits the foreground.

Setting this option explicitly will override the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable app state breadcrumbs
bugsnag({ appStateBreadcrumbsEnabled: false })

// disable all other breadcrumbs but enable app state
bugsnag({ autoBreadcrumbs: false, appStateBreadcrumbsEnabled: true })

appVersion

The version from your app.json will be picked up automatically, but if you need to you can override it here:

bugsnag({ appVersion: '4.10.0' })

appType

If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.

This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appTypes.

bugsnag({ appType: 'rider' })
bugsnag({ appType: 'passenger' })

These examples are just for illustration. BugSnag doesn’t set appType by default, so it’s up to you if and how you use it.

autoBreadcrumbs

By default, BugSnag will collect various kinds of breadcrumbs. To switch all of these off, set the autoBreadcrumbs option to false:

bugsnag({ autoBreadcrumbs: false })

For more granularity, there are options to toggle each kind of automatic breadcrumb, see:

• consoleBreadcrumbsEnabled
• networkBreadcrumbsEnabled
• orientationBreadcrumbsEnabled
• connectivityBreadcrumbsEnabled
• appStateBreadcrumbsEnabled

autoCaptureSessions

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

bugsnag({ autoCaptureSessions: false })

BugSnag will automatically report a session each time:

• The JS bundle is executed

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
  }
})

Asynchronous beforeSend callbacks

We recommend using the synchronous interface as shown above, but it is possible to provide an asynchronous beforeSend callback using a Node-style error-first callback or a Promise.

Anything that can take a long time or cause subsequent errors should be discouraged – if this is a particularly catastrophic error then you want to avoid doing any work that might prevent the report from sending.

bugsnag({
  beforeSend: report =>
    new Promise((resolve, reject) => {
      // doing some asynchronous work, resolving when done
      resolve()
      // if an error happened, you can reject the promise but this error won't
      // prevent the report from being sent (or other callbacks from being run)
      reject(err)
      // to stop the report from being sent resolve with false
      resolve(false)
      // or call report.ignore()
      report.ignore()
      resolve()
    })
  }
})

bugsnag({
  beforeSend: (report, cb) =>
    // do some async work, calling cb(err, ignore?) when done
    cb(null)

    // if an error happens call cb(err) – this won't prevent
    // the report from being sent
    cb(err)

    // prevent report from sending
    cb(null, false)
    // or
    report.ignore()
    cb(null)
  }
})

For examples on how to modify reports and what is available on the report object, see customizing error reports.

connectivityBreadcrumbsEnabled

By default, breadcrumbs are collected when the device’s network connection changes state.

Setting this option explicitly will override the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable connectivity breadcrumbs
bugsnag({ connectivityBreadcrumbsEnabled: false })

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

#consoleBreadcrumbsEnabled

Wrapping console methods to leave breadcrumbs has the side effect of messing with line numbers in log messages. Therefore when releaseStage='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 })

endpoints

By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.

If you are using BugSnag On-premise you’ll need to set these to your Event Server and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.

bugsnag({
  endpoints: {
    notify: 'https://bugsnag-notify.example.com',
    sessions: 'https://bugsnag-sessions.example.com'
  }
})

filters

Filter out properties from the payloads that are sent to BugSnag using strings (for exact matches) and regexes (for pattern matching).

Use this option to ensure you don’t send sensitive data such as passwords, and credit card numbers to our servers. Any property whose key matches a provided string or regex in this array will be filtered and replaced with [Filtered].

By default, this array contains 'password'. Be aware that if you supply a new value, it will replace the default, so include 'password' in your own array if you want to filter that.

The array can include both strings and regexes.

bugsnag({
  filters: [
    'access_token', // exact match: "access_token"
    /^password$/i,  // case-insensitive: "password", "PASSWORD", "PaSsWoRd"
    /^cc_/          // prefix match: "cc_number" "cc_cvv" "cc_expiry"
  ]
})

logger

By default, the notifier’s log messages are prefixed with [bugsnag] and output to the console (if the platform has a useful console object). You can supply your own logger instead, or switch off logging completely by setting logger: null.

If you supply a logger, it must have the following methods: debug, info, warn and error.

// switch off logging
bugsnag({ logger: null })

// supply a custom logger
var myCustomLogger = {
  debug: function () {},
  info: function () {},
  warn: function () {},
  error: function () {}
}
bugsnag({ logger: myCustomLogger })

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 })

#networkBreadcrumbsEnabled

By default, breadcrumbs are left for network requests initiated via the XMLHttpRequest constructor and fetch() calls. Metadata includes HTTP method, request URL and status code (if available).

Setting this option explicitly will override the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable network breadcrumbs
bugsnag({ networkBreadcrumbsEnabled: false })

// disable all other breadcrumbs but enable network breadcrumbs
bugsnag({ autoBreadcrumbs: false, networkBreadcrumbsEnabled: 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' ] })

orientationBreadcrumbsEnabled

By default, breadcrumbs are collected when the device’s orientation changes.

Setting this option explicitly will override the autoBreadcrumbs setting.

// enable autoBreadcrumbs but disable orientation breadcrumbs
bugsnag({ orientationBreadcrumbsEnabled: false })

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

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.

bugsnag({ releaseStage: 'staging' })

If the application has been published with expo publish, or is running in a standalone application as a result of expo build:ios|android, releaseStage default to "production".

In development, if the application is running in “production mode” releaseStage will default to "local-prod", otherwise it will be "local-dev".

Client properties

client.app.releaseStage

If the release stage of the application is available when BugSnag is configured, it’s preferable to set this in the releaseStage configuration option, but you can set this as a property on the client:

bugsnagClient.app.releaseStage = 'staging'

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"
  }
}

user

If supplied, user id, name and email are automatically available for filtering in your BugSnag dashboard. The id property is also used to determine the number of users affected by a particular error.

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

You can attach additional user information to metaData.user to which will be displayed in the “User” tab of your events along with the id, name and email properties:

 bugsnagClient.metaData.user = {
   roles: [ 'subscriber', 'premium member' ],
   last_visit: '2019-04-09T13:48:47.260Z'
 }

Client methods

client.notify(err, opts, cb)

Report a handled error to BugSnag. This method is described in detail in the reporting handled errors section.

• err [required] should be an error, which will provide the best stacktrace information. If something other than an error is passed, notify() will do its best to extract meaningful information from it.
• opts [optional] is an object used to provide or modify information on the error report, and to provide a beforeSend callback
• cb [optional] a function with the signature cb(err, report). If err=null the report either sent successfully, or it was enqueued to send later. report is the report object that was delivered (or enqueued).

client.leaveBreadcrumb(message, metaData, type, timestamp)

Adds a breadcrumb.

• message [required] a meaningful summary of the event
• metaData [optional] a one-level-deep key → value mapping object of additional data associated with the event
• type [optional] [default: manual] a string indicating the breadcrumb type. This is not a free text field, and is typically reserved for automatic breadcrumbs.
• timestamp [optional] an ISO 8601 string representing when the event happened. Unless this value is provided, it is set to the time that leaveBreadcrumb() was called.

client.startSession()

Reports a new session. Depending on the platform, this method behaves slightly differently.

Single user processes

In single user processes (such as the browser and React Native) you can call this method and discard its return value. References to the original client get updated with the new session. In these processes, the session is enqueued to send as soon as possible.

Multi-user processes

In processes that can potentially handle multiple users (i.e. a web server in Node), it is important to hold on to the return value of this method because it returns a new client which is bound to the session that was created. To illustrate, see the following example:

// this starts a session
var sessionClient = client.startSession()

// this error is reported with session information
sessionClient.notify(new Error('boom'))

// this error is not reported with session information
// because it uses the original client
client.notify(new Error('bam'))

In these processes, sessions are created immediately, but they are buffered and sent in batches periodically.

client.use(plugin, ...args)

Provide a plugin for the client to use, along with any necessary arguments.

• plugin [required] a plugin definition
• …args [optional] extra arguments that may be required by the plugin

Example: @bugsnag/plugin-vue

This plugin requires the Vue instance to be passed in:

var Vue = require('vue')
var bugsnagVue = require('@bugsnag/plugin-vue')
client.use(bugsnagVue, Vue)

client.getPlugin(name)

Access the return value of a plugin.

• string [required] the plugin’s name

Example: @bugsnag/plugin-react

The React plugin returns an ErrorBoundary component

import { createRoot } from 'react-dom/client'

const ErrorBoundary = Bugsnag.getPlugin('react')
  .createErrorBoundary(React)

const root = createRoot(document.getElementById('app'))
root.render(
  <ErrorBoundary>
    <YourApp />
  </ErrorBoundary>
)