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

Install

# Using yarn
yarn add @sentry/electron

# Using npm
npm install @sentry/electron

Configure

import * as Sentry from "@sentry/electron";

Sentry.init({ dsn: "https://examplePublicKey@o0.ingest.sentry.io/0" });

Once this is done, all unhandled exceptions are automatically captured by Sentry.

Important: Note your DSN. The DSN (Data Source Name) tells the SDK where to send events. If you forget it, view Settings -> Projects -> Client Keys (DSN) in the Sentry web UI.

Webpack Configuration

If you are seeing an issue similar to TypeError: mod.require is not a function, it means that Webpack is bundling your browser and node code together. To fix this, change the import statement of Sentry's init method to:

const { init } =
  process.type === "browser"
    ? require("@sentry/electron/dist/main")
    : require("@sentry/electron/dist/renderer");

And use the Webpack's DefinePlugin plugin to specify the process type:

plugins: [
  // main process
  new webpack.DefinePlugin({
    "process.type": '"browser"',
  }),

  // renderer process
  new webpack.DefinePlugin({
    "process.type": '"renderer"',
  }),
];

With these changes, when bundling the code for each of processes, Webpack will replace process.type with the constant and removes the inaccessible code:

const { init } =
  "browser" === "browser"
    ? require("@sentry/electron/dist/main")
    : require("@sentry/electron/dist/renderer");

// becomes >

const { init } = true ? require("@sentry/electron/dist/main") : undefined;

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

Start by configuring the SDK as described in the above. This will enable the Electron CrashReporter for native app crashes and capture 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.

Native

Sentry can process Minidumps created when the Electron process or one of its renderers crashes. To do so, the SDK needs to upload those files once the application restarts (or immediately for renderer crashes). All event meta data including user information and breadcrumbs are included in these uploads.

Due to restrictions of macOS app sandboxing, native crashes cannot be collected in Mac App Store builds. In this case, native crash handling will be disabled, regardless of the enableNative setting.

Providing Debug Information

To allow Sentry to fully process native crashes and provide you with symbolicated stack traces, you need to upload Debug Information Files (sometimes also referred to as Debug Symbols or just Symbols).

First, make sure that the Electron Symbol Server is enabled for your project. Go to Project Settings > Debug Files and choose Electron from the list of Builtin Repositories. You can add more symbol servers for the platforms you are deploying to, depending on your needs.

If your application contains custom native extensions or you wish to symbolicate crashes from a spawned child process, upload their debug information manually during your build or release process. See Debug Information Files for a detailed description of how to set up Sentry for native development. Additionally, see Uploading Debug Information for the upload process.

Child Processes

The SDK relies on the Electron CrashReporter to generate the crash dumps. To receive crash reports for child processes, you need to make sure the crash reporter is activated by either the SDK or manually (see below).

An exception to this is macOS, where the crash reporter only needs to be started in the main process and watches all its child processes. The SDK already takes care of this difference, so there is no need to manually disable enableNative.

For custom child processes, especially ones not written in JavaScript, you need to integrate a library that can generate Minidumps. These are most notably Crashpad and Breakpad. Please refer to their respective documentation on how to build and integrate them. Configure them with the following upload URL:

https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey

It currently not possible create breadcrumbs or other event meta data from native code. This has to happen in JavaScript. Support for this is planned in future releases.

Manual Crash Reporting

You can also capture native crashes by starting the Electron CrashReporter manually. Sentry is able to provide symbolicated stack traces and show system information, but no Electron-specific metadata, breadcrumbs or context information will be present. This is useful in cases where you cannot use the full Electron SDK:

const { crashReporter } = require("electron");
crashReporter.start({
  companyName: "YourCompany",
  productName: "YourApp",
  ignoreSystemCrashHandler: true,
  submitURL: "https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey",
});

Source Maps

To find out why Sentry needs your source maps and how to provide them visit: Source Maps

Native Application

To allow Sentry to match source code references to uploaded source maps or source files, make sure your tool outputs files relative to your project root folder and prefixes them either with / or with ~/. Some tools do this automatically (e.g. Webpack), or have a configuration option (e.g. TypeScript). For others, please see the section on rewriting source maps before uploading.

The SDK will rewrite stack traces before sending them to Sentry. If your application generates manual stack traces for some reason, make sure stack frames always contain relative paths from the project root starting with ~/ or app:///.