Electron integration guide

Add BugSnag to your Electron (v10.1.4+) projects to automatically capture and report errors in production.

Installation

Install BugSnag from npm or yarn:

npm install --save @bugsnag/electron
# or
yarn add @bugsnag/electron

Basic configuration

To capture errors at any point in the application:

1. Initialize in the main process at the beginning of the application entry point file, usually main.js or index.js.
2. Initialize in each renderer process at the beginning of the first JavaScript file loaded.

Main process

const Bugsnag = require('@bugsnag/electron/main')

In your application entry point, start BugSnag with your API key and any other options as configuration:

Bugsnag.start({
  apiKey: 'YOUR_API_KEY',
  otherOptions: value,
})

You can find your API key in Project Settings from your BugSnag dashboard.

Most configuration options are supplied in the call to Bugsnag.start() from the main process and will be inherited by all renderer processes.

Check out the configuration options reference for a list of available options.

Renderer processes

// ES module-style import
import Bugsnag from '@bugsnag/electron/renderer'

// common-js/node-style import (useful when nodeIntegration=true)
const Bugsnag = require('@bugsnag/electron/renderer')

Start BugSnag along with any renderer-specific configuration as needed:

Bugsnag.start({
  // renderer options
})

The renderer inherits all configuration from the main process. Only some configuration options can be set in the renderer. The configuration options reference shows which processes each option is supported in.

TypeScript support

Type definitions are provided and will be picked up automatically by the TypeScript compiler when you import any of the top-level @bugsnag/* packages.

Our package uses some TypeScript features that are only available in TypeScript 4.5 and above. If you are using an older version of TypeScript, you may need to disable type-checking for the @bugsnag/* packages. To do so, please follow this guide.

Framework integration

BugSnag integrates with JavaScript UI frameworks in the renderer via the use of plugins.

React

BugSnag’s React plugin provides an Error Boundary component that you can use to capture render errors in your React components with added metadata.

import BugsnagPluginReact from '@bugsnag/plugin-react'

Bugsnag.start({
  plugins: [new BugsnagPluginReact()]
})

See the React guide for more information.

Vue

BugSnag’s Vue plugin hooks into Vue’s built-in error handler to automatically report errors from Vue components with added metadata.

import BugsnagPluginVue from '@bugsnag/plugin-vue'

Bugsnag.start({
  plugins: [new BugsnagPluginVue()]
})

See the Vue guide for more information.

Angular

BugSnag’s Angular plugin integrates with Angular’s built-in error handler to automatically report errors from Angular components and services with added metadata.

import Bugsnag from '@bugsnag/electron/main'
import { BugsnagErrorHandler } from '@bugsnag/plugin-angular'

const client = Bugsnag.start();

export function errorHandlerFactory() {
  return new BugsnagErrorHandler(client)
}

@NgModule({
  /* Pass the BugsnagErrorHandler class along to the providers for your module */
  providers: [ { provide: ErrorHandler, useFactory: errorHandlerFactory } ]
  /* other properties passed to the decorator omitted for brevity */
})

See the Angular guide for more information.

Showing full stacktraces

Uploading source maps and symbol files enables you to see the original method names, file paths, and line numbers in stacktraces.

See the showing full stacktraces guide to configure uploading files during your release process.

Reporting unhandled errors

After completing installation and basic configuration, unhandled exceptions, unhandled promise rejections, and native application crashes (minidumps) will be reported and automatically appear on your BugSnag dashboard.

Reporting handled errors

Sometimes it is useful to manually notify BugSnag of a problem. To do this, call Bugsnag.notify(). For example:

try {
  something.risky()
} catch (e) {
  Bugsnag.notify(e)
}

When reporting handled errors, 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

BugSnag will automatically capture the following data for every exception:

• Full stack trace
• App state including running time and time in foreground
• Build information including app name, version/build, and release stage
• Device specification including the operating system version, screen size, and total memory
• System state including free memory, whether the system was idling, and online state
• Script content, if the error originated in an inline <script/> tag
• The current URL, if the error occurred after calling BrowserWindow.loadURL()

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to BugSnag.

The following adds a map of data to the “company” tab on the BugSnag dashboard for all captured events:

Bugsnag.start({
  onError: function (event) {
    event.addMetadata('company', {
      name: "Acme Co.",
      country: "uk"
    })
  }
})

For more information, see Customizing error reports.

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.

You can set the user information of an error report using the user configuration property when BugSnag starts or using Bugsnag.setUser():

Bugsnag.setUser('3', 'erina@example.com', 'Erina')

For information on doing so, see Adding user data.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, BugSnag captures the following events as breadcrumbs:

• App lifecycle events
• Clicks
• Console logs, warnings, and errors
• Display added, removed, and resized events
• Errors
• HTTP requests
• Power state changes, like switching to battery power
• Window visibility changes

For more information or to disable particular classes of automatic breadcrumb generation see configuration options.

Attaching custom breadcrumbs

You can use the leaveBreadcrumb method to log potentially useful events in your own applications:

Bugsnag.leaveBreadcrumb('Button clicked')

BugSnag will keep track of the time and order of the breadcrumbs and show them on your dashboard. Additional data can also be attached to breadcrumbs by providing the optional metadata parameter.

For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.

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

BugSnag will automatically report a session each time the app is launched or enters the foreground after being in the background for at least 60 seconds.

For more information about or to customize session tracking, see Capturing sessions.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

Bugsnag.addFeatureFlag('Checkout button color', 'Blue')
Bugsnag.addFeatureFlag('New checkout flow')

For more information, see Feature flags & experiments.

Identifying crashes at launch

By default BugSnag will identify crashes that occur whilst your app is launching, allowing you to prioritize fixing high-impact launch crashes.

Follow the Identifying crashes at launch guide to configure this functionality.

Checking if the notifier has already been started

You can use Bugsnag.isStarted() to check whether the BugSnag client has been initialized.

Next steps

• View @bugsnag/electron, the library powering BugSnag’s Electron error reporting, on GitHub
• Get support for your questions and feature requests