Electron

@sentry/electron is the official Sentry SDK for Electron applications. It can capture JavaScript exceptions in the main process and renderers, as well as collect native crash reports (Minidumps).

const { init } = require('@sentry/electron');
init({
    dsn: '___PUBLIC_DSN___',
    enableNative: false,
});

Wizard

Our Sentry Wizard can help with the setup process. Make sure you have installed the @sentry/wizard npm package globally, then run:

$ npm install -g @sentry/wizard
$ sentry-wizard --integration electron

This will guide you through the installation and configuration process and suggest useful tools for development. If you instead prefer to setup manually, keep reading.

Configuring the Client

After configuring the SDK the Electron CrashReporter for native app crashes and captures any uncaught JavaScript exceptions using the JavaScript SDKs under the hood. Be sure to call this function as early as possible in the main process and all renderer processes to also catch errors during startup.

Browser integration

We recommend to put the initialization in a separate JavaScript module, to keep configuration options consistent. This also allows to use it as preload script when creating new BrowserWindow instances:

mainWindow = new BrowserWindow({
  width: 800,
  height: 600,
  webPreferences: {
    preload: path.join(__dirname, 'sentry.js')
  }
});

After this, the SDK is ready to capture any uncaught exception and native crashes that occur in those processes.

Node Integration

The SDK requires some NodeJS APIs to operate properly. When creating windows without Node integration, the SDK must be loaded in a preload script, as described above. Doing so also ensures that the SDK is loaded as early as possible.

mainWindow = new BrowserWindow({
  width: 800,
  height: 600,
  webPreferences: {
    nodeIntegration: false,
    preload: path.join(__dirname, 'sentry.js')
  }
});

Sandbox Mode

Sandbox mode fully isolates the renderer processes from the operating system using OS-specific methods. Since most node APIs require system access, they are not available in sandbox mode, most notably require(). See the linked documentation for a detailed description of sandbox restrictions.

The Electron SDK can still be used from within a preload script. However, it needs to be bundled into a single file using bundlers like Webpack or Rollup due to the missing require() function. Please refer to the respective documentation your chosen tool for all possible configuration options.

The SDK is written in a way that prevents bundlers from processing any code that is only meant to be executed in the main process. The only remaining external dependency is electron, which must be explicitly excluded from inlining. For Webpack, this would be:

module.exports = {
  externals: {
    electron: 'commonjs electron',
  },
  // ...
};

Or for Rollup:

export default {
  external: ['electron'],
  plugins: [commonjs()],
  // ...
};

Uploading Debug Information

To get symbolicated stack traces for native crashes, you have to upload debug symbols to Sentry. Sentry Wizard creates a convenient sentry-symbols.js script that will upload the Electron symbols for you. After installing the SDK and every time you upgrade the Electron version, run this script:

$ node sentry-symbols.js

If your app uses a custom Electron fork, contains modules with native extensions or spawns subprocesses, you have to upload those symbols manually using Sentry CLI. For more information, see Native Usage.

Dealing with Minified Source Code

The Electron SDK supports Source Maps. If you upload source maps in addition to your minified files that data becomes available in Sentry. For more information see Source Maps.

Deep Dive

For more detailed information about how to get most out of the Electron SDK, there is additional documentation available that covers all the rest: