The BugSnag web-worker package can be used to report handled errors from inside a web worker or service worker.
Install @bugsnag/web-worker npm package from the npm registry using npm or yarn:
npm install --save @bugsnag/web-worker
# or
yarn add @bugsnag/web-worker
Include BugSnag in your worker in one of the following ways:
// commonjs/node-style require
var Bugsnag = require('@bugsnag/web-worker')
// ES module-style import
import Bugsnag from '@bugsnag/web-worker'
The simplest way to configure BugSnag is to provide your API key as a string as early as possible in your worker script:
Bugsnag.start('YOUR_API_KEY')
You can find your API key in Project Settings from your BugSnag dashboard.
To specify any additional configuration options, supply an object instead:
Bugsnag.start({
apiKey: 'YOUR_API_KEY',
otherOptions: value
})
For information on values that can be set in the configuration object, see configuration options.
BugSnag can be configured to run in different ways inside a worker depending on its relationship with the “host” web app that spawns it.
By default the BugSnag web-worker package will not report unhandled errors from the worker script. This is to allow errors to propagate up to the browser context and be reported by BugSnag running in your host web app. As these errors are in the same context as the browser sessions, they will impact the web app’s stability score. However they will not contain any breadcrumbs or metadata added from within the worker context: these will only be present in handled errors.
If you choose to enable automatic error detection in the web-worker using the autoDetectErrors configuration option, errors are reported from within the worker and will have the breadcrumbs and metadata set within the worker. However these errors will not be tied to the browser sessions and will not impact the stability score of the host web app.
Bugsnag.start({
apiKey: 'YOUR_API_KEY',
autoDetectErrors: true
})
If auto-detecting errors within the worker you may also wish to prevent these errors from being reported by any BugSnag instance in the host web app:
const worker = new Worker('worker.js', { type: 'module' })
worker.onerror = function (e) {
e.preventDefault()
}
Errors inside service workers do not propagate up to the browser context and so won’t be reported by a BugSnag instance running in the host web app. You should therefore enable autoDetectErrors configuration option on any BugSnag instance running inside a service worker to report these errors.
If you are using BugSnag in a service worker as part of a browser extension, please note that in a Chrome extension the chrome.runtime API will not trigger the onerror handler due to a limitation of the Chrome platform. To report exceptions you will need to catch them manually, pass them to Bugsnag.notify() and then re-throw them from the catch block.
You can amend the unhandled property so they are correctly reported in your dashboard:
try {
something.risky();
} catch (e) {
Bugsnag.notify(e, function(event) {
event.unhandled = true;
});
throw e;
}
The BugSnag web-worker package does not report sessions by default. If you are using a web worker hosted in your own web app the sessions should be managed by the host web app as it is this that users engage with directly. However, if you wish to treat either a web worker or a service worker independently from the host web app, automatic session tracking can be enabled in the web-worker package using the autoTrackSessions configuration option.
Bugsnag.start({
apiKey: 'YOUR_API_KEY',
autoTrackSessions: true
})