This version contains many breaking changes. It is part of an effort to unify our notifier libraries across platforms, making the user interface more consistent, and implementations better on multi-layered environments where multiple Bugsnag libraries need to work together (such as React Native).
As a result of upgrading, your project may see new error groups for existing errors. This is because JavaScript errors are grouped by comparing the surrounding code.
In most applications, the desire is to create a single Bugsnag client – it's rare that you'd want to instantiate multiple clients. We've made static initialization the primary interface, so that the user experience is optimized around the main use case – creating a single client:
- import bugsnag from '@bugsnag/js'
+ import Bugsnag from '@bugsnag/js'
- const bugsnagClient = bugsnag(/ * opts */)
+ Bugsnag.start(/ * opts */)You can choose to hold on to the Client returned by Bugsnag.start(), or not. After ensuring Bugsnag.start() is called first, you can call any Client method on the static interface, which forwards the method call onto the initialized client:
Bugsnag.notify()Bugsnag.leaveBreadcrumb()Bugsnag.startSession(),Bugsnag.pauseSession(),Bugsnag.resumeSession()Bugsnag.setContext(),Bugsnag.getContext()Bugsnag.setUser(),Bugsnag.getUser()Bugsnag.addMetadata(),Bugsnag.getMetadata(),Bugsnag.clearMetadata()Bugsnag.getPlugin()
A common pattern when implementing Bugsnag pre-v7 is to do something like the following, initializing a Bugsnag client which can then be imported in various parts of the application:
lib/bugsnag.js
// OLD EXAMPLE
import bugsnagClient from '@bugsnag/js'
const bugsnagClient = bugsnag(/* your opts here */)
export bugsnagClientindex.js
// OLD EXAMPLE
import bugsnagClient '/lib/bugsnag'
import HelloWorld from './components/HelloWorld'
bugsnagClient.leaveBreadcrumb('App starting…')components/HelloWorld.js
// OLD EXAMPLE
import bugsnagClient from '/lib/bugsnag'
export function render () {
bugsnagClient.notify(new Error('render failed'))
}This update means lib/bugsnag.js can go away. As long as you ensure Bugsnag.start() is called first, you can simply do:
index.js
// NEW EXAMPLE
import Bugsnag from '@bugsnag/js'
Bugsnag.start(/* your opts here */)
Bugsnag.leaveBreadcrumb('App starting…')components/HelloWorld.js
// NEW EXAMPLE
import Bugsnag from '@bugsnag/js'
export function render () {
Bugsnag.notify(new Error('render failed'))
}If you need to create multiple clients, you can use the Bugsnag.createClient(…) method:
- const bugsnagClient = bugsnag(/* opts */)
+ const bugsnagClient = Bugsnag.createClient(/* opts */)Many options have been renamed, reworked or replaced.
{
- notifyReleaseStages: ['staging','production'],
+ enabledReleaseStages: ['staging','production'],
- autoNotify: false,
+ autoDetectErrors: false,
// When autoDetectErrors is true, this option
// sets which kinds of errors to detect
+ enabledErrorTypes: {
+ unhandledExceptions: false,
+ unhandledRejections: false
+ },
- autoBreadcrumbsEnabled: false,
- consoleBreadcrumbsEnabled: false,
- interactionBreadcrumbsEnabled: false,
- navigationBreadcrumbsEnabled: false,
- networkBreadcrumbsEnabled: false,
+ enabledBreadcrumbTypes: [
+ 'navigation', 'request', 'process', 'log', 'user', 'state', 'error', 'manual'
+ ],
- autoCaptureSessions: false,
+ autoTrackSessions: false,
// beforeSend callbacks have been renamed to onError
// and now receive an event parameter rather than report
- beforeSend: (report) => {}
+ onError: (event) => {}
- filters: [],
+ redactedKeys: []
- metaData: {},
+ metadata: {},
+ onSession: (session) => {
+ // a callback to run each time a session is created
+ }
+ onBreadcrumb: (breadcrumb) => {
+ // a callback to run each time a breadcrumb is created
+ }
// plugins must now be supplied in config rather than via client.use()
+ plugins: []
}Before, app, device, request, user, metaData and context were simply properties hanging off of the client that could be mutated at-will. Now, their structure and how/where they are set is more strictly controlled.
version, type and releaseStage can now only be supplied in configuration and are deemed immutable after the client has been initialized.
- bugsnagClient.app.version = '1.2.3'
+ Bugsnag.start({ appVersion: '1.2.3' })- bugsnagClient.app.releaseStage = 'staging'
+ Bugsnag.start({ releaseStage: 'staging' })- bugsnagClient.app.type = 'worker'
+ Bugsnag.start({ appType: 'worker' })The app section of the payload is now reserved for properties defined by Bugsnag. If you want to send information to be displayed under the "App" tab in the dashboard, provide it under an app section in metadata.
- bugsnagClient.app.gitSha = 'c6f0f2'
+ Bugsnag.addMetadata('app', 'gitSha', 'c6f0f2')The app data provided in config and collected automatically by Bugsnag is accessible in onError callbacks under the event.app property. Any data that needs to be inspected, removed or changed can be done here if necessary.
Similarly, the device section of the payload is now reserved for properties defined by Bugsnag. If you want to send information to be displayed under the "Device" tab in the dashboard, provide it under a device section in metadata.
- bugsnagClient.device.browserPlugins = navigator.plugins
+ Bugsnag.addMetadata('device', 'browserPlugins', navigator.plugins)The device data collected automatically by Bugsnag is accessible in onError callbacks under the event.device property. Any data that needs to be inspected, removed or changed can be done here if necessary.
Setting a user's id, email and name must now be done via the setUser(id, email, name) method. If you want to send more information to be displayed under the "User" tab in the dashboard, provide it under a user section in metadata.
- client.user = { id: '123', email: 'bug@sn.ag', name: 'Bug S. Nag', roles: [ 'admin', 'subscriber' ] }
+ Bugsnag.setUser('123', 'bug@sn.ag', 'Bug S. Nag')
+ Bugsnag.addMetadata('user', 'roles', [ 'admin', 'subscriber' ])It remains possible to specify the user { id, email, name } in configuration:
- bugsnag({
+ Bugsnag.start({
user: {
id: '123',
email: 'bug@sn.ag',
name: 'Bug S. Nag'
}
})The consistent mis-capitalisation of "metaData" has been corrected to "metadata" 🎉
The client.metaData property has now been removed, and metadata is managed via the following methods, which control the metadata which is attached to every event:
Bugsnag.addMetadata(section, key, value)
Bugsnag.addMetadata(section, { [key]: value, …})
Bugsnag.getMetadata(section, key)
Bugsnag.clearMetadata(section, key)The same methods are available on an event, to control the metadata that is included with only that event:
event.addMetadata(section, key, value)
event.addMetadata(section, { [key]: value, … })
event.getMetadata(section, key)
event.clearMetadata(section, key)It remains possible to supply initial metadata in configuration:
- bugsnag({
+ Bugsnag.start({
- metaData: {
+ metadata: {
section: { key: value }
}
})Previously, it was possible to add "top-level" metadata, i.e. data that you did not provide a specific section name for. In the dashboard, this would display under a tab with the heading "Custom". Since a section name is now required, for continuity both visually and for any custom filters you may have set up based on such data, you should set the section name to 'custom':
- bugsnagClient.metaData = { processId: 'aa874cbd', role: 'image-resizer' }
+ Bugsnag.addMetadata('custom', { processId: 'aa874cbd', role: 'image-resizer' })On the client, context is now managed via get/setContext():
- client.context = 'Account > Manage addresses'
+ Bugsnag.setContext('Account > Manage addresses')In an onError callback, event.context is simply a property that can be mutated directly.
- report.context = document.location.href
+ event.context = document.location.hrefAnd it remains possible to supply initial context in configuration:
- bugsnag({
+ Bugsnag.start({
context: document.location.href
})Note that by manually setting context at any point, this will switch off any automatic context setting.
The signature of notify() has changed. Before, the second parameter opts allowed specifying some of the report's properties, as well as a callback to run. Now, the only way to provide extra information to an error report is to provide a callback to run. onError is the new name for beforeSend and it now receives an event, the new name for report.
- bugsnagClient.notify(err, opts, cb)
+ Bugsnag.notify(err, onError, cb)Here are some examples:
// changing severity
- bugsnagClient.notify(err, { severity: 'info' })
+ Bugsnag.notify(err, event => { event.severity = 'info' })
// adding metadata
- bugsnagClient.notify(err, {
- metaData: {
- component: {
- instanceId: component.instanceId
- }
- }
- })
+ Bugsnag.notify(err, event => {
+ event.addMetadata('component, {
+ instanceId: component.instanceId
+ }
+ })
// preventing send
- bugsnagClient.notify(err, report => {
+ Bugsnag.notify(err, event => {
- if (report.context === '/test-error-page') {
+ if (event.context === '/test-error-page') {
return false
}
})
// updating error class/message
- bugsnagClient.notify(err, {
- beforeSend: report => {
- report.errorClass = 'MyCustomError'
- report.errorMessage = 'Something went wrong'
- }
- })
+ Bugsnag.notify(err, event => {
+ event.errors[0].errorClass = 'MyCustomError'
+ event.errors[0].errorMessage = 'Something went wrong'
+ })And here is the full difference between the report and event interface:
- class Report {
+ class Event {
// These properties remain intact and unchanged
apiKey
app
device
request
context
breadcrumbs
groupingHash
severity
originalError
// the event implements the same metadata methods as the client
- metaData
- updateMetaData(section, key, value)
- removeMetaData(section, key)
+ addMetadata(section, key, value)
+ getMetadata(section, key)
+ clearMetadata(section, key)
// an event can now contain multiple errors
- errorClass
- errorMessage
- stacktrace
+ errors [
+ { errorClass, errorMessage, stacktrace, type }
+ ]
- user
+ getUser()
+ setUser(id, name, email)
- session
// now the only way to ignore an error report is
// to return false from an onError callback
- ignore()
- isIgnored()
}The method to reset the event count, preventing the maxEvents limit from being hit has been renamed:
- bugsnagClient.refresh()
+ Bugsnag.resetEventCount()Previously it was valid to supply a notify endpoint without supplying a sessions endpoint. Now if you supply one, you must supply the other. Note, this only applies when configuring the notifier for Bugsnag On-Premise.
{
endpoints: {
notify: 'https://custom-bugsnag-notify.yourdom.ain'
+ sessions: 'https://custom-bugsnag-sessions.yourdom.ain'
}
}Plugins must now be supplied in configuration, and the client.use() method has been removed. For users of the following plugins, some changes are required:
- import bugsnagReact from '@bugsnag/plugin-react'
+ import BugsnagPluginReact from '@bugsnag/plugin-react'
- const bugsnagClient = bugsnag('YOUR_API_KEY')
+ Bugsnag.start({ apiKey: 'YOUR_API_KEY', plugins: [new BugsnagPluginReact(React)] })
- bugsnagClient.use(bugsnagReact, React)- import bugsnagVue from '@bugsnag/plugin-vue'
+ import BugsnagPluginVue from '@bugsnag/plugin-vue'
- const bugsnagClient = bugsnag('YOUR_API_KEY')
+ Bugsnag.start({ apiKey: 'YOUR_API_KEY', plugins: [new BugsnagPluginVue(Vue)] })
- bugsnagClient.use(bugsnagVue, Vue)Since these plugins don't need any input, their usage is simpler and follows this pattern
- bugsnagClient.use(plugin)
+ Bugsnag.start({
+ plugins: [plugin]
+ })See the full documentation for more information.
This change only affects users that are sending via a proxy in Node.
The only major change from 5 to 6 is the removal of request from the @bugsnag/delivery-node. This means that no changes are required for users of the browser package.
Only if you were using the proxy option or an http(s)_proxy environment variable in Node do you need to make changes.
From now on, you need to supply a proxy agent, which Bugsnag will use for all its HTTP(s) requests. For example:
+ const HttpsProxyAgent = require('https-proxy-agent')
const bugsnagClient = bugsnag({
- proxy: 'http://corporate-proxy:3128/'
+ agent: new HttpsProxyAgent('http://corporate-proxy:3128/')
})@bugsnag/js v5 is the first "universal" JavaScript release.
There are minimal external API changes from bugsnag-js v4 -> @bugsnag/js, so the migration is very simple.
Upgrading from bugsnag-node requires a more significant update.
Users of the CDN just need to update the link:
- https://d2wy8f7a9ursnm.cloudfront.net/v4.7.3/bugsnag.min.js
+ https://d2wy8f7a9ursnm.cloudfront.net/v5.0.0/bugsnag.min.jsUsers of the bugsnag-js browser JS package will need to remove that dependency and add @bugsnag/js.
# npm
npm rm --save bugsnag-js
npm install --save @bugsnag/js
# yarn
yarn remove bugsnag-js
yarn add @bugsnag/js
Subsequently, in the application, any requires/imports should be updated (this should be a simple find and replace):
- import bugsnag from "bugsnag-js"
+ import bugsnag from "@bugsnag/js"- var bugsnag = require('bugsnag-js')
+ var bugsnag = require('@bugsnag/js')The plugin interface has changed slightly and these packages have been migrated to the @bugsnag namespace.
Remove the old module and install the new module:
# npm
npm rm --save bugsnag-{vue|react|angular}
npm install --save @bugsnag/plugin-{vue|react|angular}
# yarn
yarn remove bugsnag-{vue|react|angular}
yarn add @bugsnag/plugin-{vue|react|angular}
- const bugsnagVue = require('bugsnag-vue')
+ const bugsnagVue = require('@bugsnag/plugin-vue')
- bugsnagClient.use(bugsnagVue(Vue))
+ bugsnagClient.use(bugsnagVue, Vue)- const bugsnagReact = require('bugsnag-react')
+ const bugsnagReact = require('@bugsnag/plugin-react')
- bugsnagClient.use(bugsnagReact(React))
+ bugsnagClient.use(bugsnagReact, React)
- const ErrorBoundary = bugsnagClient.use(createPlugin(React))
+ const ErrorBoundary = bugsnagClient.getPlugin('react')- import BugsnagErrorHandler from 'bugsnag-angular'
+ import { BugsnagErrorHandler } from '@bugsnag/plugin-angular'Users of the existing bugsnag (node) package should note that this upgrade is not backwards compatible and should follow the new integration guides.
Please note the signature of the notify() function is similar, but has some noteworthy differences:
bugsnagClient.notify(error, opts)
- Previously
metaDatacould be provided by passing arbitrary keys toopts. Now, it must be passed explicitly asopts.metaData. groupingHashis no longer an option, but it can be set usingreport.groupingHashin abeforeSendcallback.
Please refer to the documentation, since notify() will ignore opts that it doesn't recognize.
TypeScript definitions are bundled with each of the published modules and should "just work".
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.
If you're loading Bugsnag from the CDN you may have got used to transparent rolling updates. Since this is a major update with breaking changes, you'll need to update the URL your script tag is pointing to. Be sure to also make changes to your application where it configures and uses the Bugsnag client!
- <script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-3.min.js" data-apikey="API_KEY"></script>
+ <script src="//d2wy8f7a9ursnm.cloudfront.net/v4/bugsnag.min.js"></script>
+ <script>window.bugsnagClient = bugsnag('API_KEY')</script>If you're using a package manager, you should run something like
npm install --save bugsnag-js@4
# or
yarn add bugsnag-js@4
Before, the client would simply "exist" already on the page – like a singleton. Now you have to explicitly create your client with some configuration options (or simply an API key).
This might seem like a little more work, but it gives you more granular control:
- Bugsnag won't start until you tell it to.
- It will do exactly as its told based on the config provided. Previously, it would start doing all the default behavior and you'd have to go and switch it all off, which was rather messy.
- There's now no lost-in-translation in the options. The options are declared as JS values rather than being extracted from strings, which should mean fewer surprises.
- <script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-3.min.js" data-apikey="API_KEY"></script>
+ <script src="//d2wy8f7a9ursnm.cloudfront.net/v4/bugsnag.min.js"></script>
<script>
- Bugsnag.notify(err)
+ window.bugsnagClient = bugsnag('API_KEY')
+ bugsnagClient.notify(err)
</script>We've changed how our configuration system works.
As mentioned, we've removed the ability to configure the library with HTML attributes. Additionally many of the configuration options have been updated or changed.
All options are now provided by a single configuration object passed to the client.
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.
The only methods supported to report errors and leave breadcrumbs now are:
bugsnagClient.notify(err, opts)
bugsnagClient.leaveBreadcrumb('name', { /* metaData */ })That means the following usage is DEPRECATED:
Bugsnag.notifyException(err)
Bugsnag.notify(name, message)To convert examples of this usage, do the following:
- Bugsnag.notifyException(err)
+ bugsnagClient.notify(err)- Bugsnag.notify('NetworkError', 'max retries exceeded')
+ bugsnagClient.notify({ name: 'NetworkError', message: 'max retries exceeded'})Previously, notify/notifyException could be called in different ways to set severity and metaData. Now there is one consistent opts object structure to customize reports:
- Bugsnag.notifyException(err, {
- 'special info': {
- request_id: 12345,
- message_id: 854
- }
- }, 'warning')
+ bugsnagClient.notify(err, {
+ severity: 'warning',
+ metaData: {
+ 'special info': {
+ request_id: 12345,
+ message_id: 854
+ }
+ }
+ })Refer to the exact spec of the opts object for more information.
v1 to 3 of the notifier valiantly supported IE 6 and 7. However, supporting these old ancient browsers came with some pretty serious caveats. Now that we’ve dropped support, we're able to move the library forward and make our reporting delivery mechanism more robust.
If you’re still supporting users on IE6/7, you can still use v3. We will continue to support v3 along side v4, however it will enter "maintenance" mode where no new features will be added. For more information, see the v3 integration guide.
Before, due to the esoteric payload format the JS notifier would post to a JS-specific route (/js) on the notify server. Now, payload has been homogenized, so requests go to the root (/) of the notify host like reports from other platforms.
For hosted Bugsnag, the default URL is now //notify.bugsnag.com. If you didn't configure this, you shouldn't need to make a change. For On-Premise, after updating the latest version make sure you configure endpoint without /js in the URL.
- endpoint: '//notify-bugsnag.example.com/js'
+ endpoint: '//notify-bugsnag.example.com'