Electron

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

Install

Copied
# Using yarn
yarn add @sentry/electron

# Using npm
npm install @sentry/electron

Configure

You need to call init in the main process and every renderer process you spawn.

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

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

Once configured, all unhandled exceptions and native crashes 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.

Wizard

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

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

If you are using preload scripts, have contextIsolation enabled and want to capture errors from the isolated preload context, you should call init early in that context too.

App userData Directory

If you change the userData directory used by your app, ensure this change is made before you configure the SDK as this path is used to cache scope and events between application restarts.

Copied
import { app } from "electron";
import * as Sentry from "@sentry/electron";

app.setPath("userData", "~/.config/my-app");
Sentry.init({ dsn: "https://examplePublicKey@o0.ingest.sentry.io/0" });

Bundler Configuration

The SDK attempts to ensure JavaScript bundlers pick up the correct entry point for the Electron process type, but this is not foolproof. If the incorrect entry point is selected, your bundler may throw an error or an error will be thrown at runtime. If this occurs you can use relative imports to ensure that the correct code is bundled for the process.

In the main process:

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

In the renderer processes:

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

Inter-Process Communication

To give detailed information for all events including native crashes, the SDK merges context, scope and breadcrumbs from all processes in the Electron main process.

By default, the SDK attempts to establish communication from renderer to main via Electron IPC API's and if that fails, falls back to using a custom HTTP protocol. You can change this default via the ipcMode option which can be one of Classic, Protocol or Both.

Copied
const { init, IPCMode } = require("@sentry/electron");

init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  debug: true,
  ipcMode: IPCMode.Protocol,
});

Preload Injection

The SDK attempts to inject a preload script via session.setPreloads(preloads) and by default only does this for the defaultSession. If you are using other sessions, you can pass custom sessions via the getSessions option in the main process:

Copied
import { session } from "electron";
import * as Sentry from "@sentry/electron";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  getSessions: () => [
    session.defaultSession,
    session.fromPartition("persist:my-session"),
  ],
});

If your app bundles the main process JavaScript, the SDK cannot automatically inject preload scripts because the script will be missing from the packaged app. In this case, the SDK will send events and scope updates via a custom HTTP protocol and window.fetch.

Manual Preload

If you would like to manually bundle and configure the preload script, you should import the SDK preload code into your own preload script:

Copied
import "@sentry/electron/preload";

This script exposes IPC to the isolated renderer via Electrons contextBridge API.

Check out the example apps for how to do this.

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:

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

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:

Copied
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:

Copied
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:///.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").