Migrating to v3

v3 of the Electron SDK includes significant changes to simplify usage and improve maintainability and bundler support. Migration should still be relatively painless!

• If you have trouble migrating, please respond in this issue
• If you find bugs with v3 or you can see areas where it can be improved, please open a new issue

For some advanced technical detail, you may want to check out the relevant Proposal and Pull Request.

New Features:

• Session tracking now enabled by default
• Preload script no longer required for most scenarios
• Optional relative imports for main/renderer/preload entry points
• Offline support
• Additional device context
• Minidumps for GPU crashes
• Browser Tracing now compatible

Major breaking changes:

• Native crashes now consider sampleRate and beforeSend
• Configuration through integrations rather than options

Session Tracking

Session tracking is now enabled by default so you will see Release Health data. Session tracking is via the MainProcessSession integration which as the name suggests, tracks sessions as per the main process lifetime.

Sentry.init({
  dsn: '__DSN__',
  release: '__RELEASE__'
});

If you don’t want to track sessions, this can be disabled by setting autoSessionTracking to false.

Sentry.init({
  dsn: '__DSN__',
  autoSessionTracking: false
});

If you have a use case where sessions should be tracked in a different way, please open an issue!

Relative Imports

The SDK uses multiple package.json fields to ensure that bundlers automatically pickup the the correct entry point for each Electron process when using the root import (const Sentry = require('@sentry/electron') or import * as Sentry from '@sentry/electron'). This allows you to have a sentry.js with your Sentry configuration imported into every process.

However, not all bundlers are created equal and you may want to add specific integrations to only one of the Electron processes.

To support more complex configurations, you can now skip this automatic bundler target detection and import the process specific code directly:

Main Process

const Sentry = require('@sentry/electron/main');
// or
import * as Sentry from '@sentry/electron/main';

Renderer Process

const Sentry = require('@sentry/electron/renderer');
// or
import * as Sentry from '@sentry/electron/renderer';

Preload Code

require('@sentry/electron/preload');
// or
import '@sentry/electron/preload';

Offline Support

The ElectronOfflineNetTransport is now the default transport. It wraps ElectronNetTransport and saves payloads to disk if they cannot be sent

Additional device context

The default enabled AdditionalContext integration includes additional device context like screen resolution and memory usage.

Browser Tracing

The significant refactor now allows the use of Sentry browser tracing in the renderer process:

main.js

import * as Sentry from '@sentry/electron/main';

Sentry.init({
  dsn: '__DSN__'
}); 

renderer.js

import * as Sentry from '@sentry/electron/renderer';
import { Integrations } from '@sentry/tracing';

Sentry.init({
  integrations: [new Integrations.BrowserTracing()],
  tracesSampleRate: 1.0,
}); 

Preload Scripts

As of 3.0.0-beta.2 a preload script is no longer required for Electron >= v5

Native Crashes, sampleRate and beforeSend

Previously, the SDK did not consider sampleRate when sending native crash events and it was not possible to intercept them via the beforeSend hook. Theses are now correctly handled.

Integrations over Options

Previously, the Electron SDK had various configuration options. Most of these have moved to integrations.

With v3, the only Electron specific configuration options are in the main process and are detailed below:

export interface ElectronMainOptions extends NodeOptions {
  /**
   * Inter-process communication mode to receive event and scope from renderers
   *
   * IPCMode.Classic - Configures Electron IPC
   * IPCMode.Protocol - Configures a custom protocol
   * IPCMode.Both - Configures both IPC and custom protocol
   *
   * Defaults to IPCMode.Both for maximum compatibility
   */
  ipcMode: IPCMode;
  /**
   * A function that returns an array of Electron session objects
   *
   * These sessions are used to configure communication between the Electron
   * main and renderer processes.
   *
   * Defaults to () => [session.defaultSession]
   */
  getSessions: () => Session[];
  /**
   * Callback to allow custom naming of renderer processes.
   *
   * If the callback is not set, or it returns `undefined`, the default naming
   * scheme is used.
   */
  getRendererName?: (contents: WebContents) => string | undefined;
}

Native Crash Reporting

For native crash reporting, you have three options

1. SentryMinidump integration (default) Uploads minidump files via the Sentry Envelope endpoint with full breadcrumbs and context
2. ElectronMinidump integration Uploads minidumps via Crashpad/Breakpad built in uploader with partial context

import { init, Integrations} from '@sentry/electron';

init({
  dsn: '__DSN__',
  // Adding the ElectronMinidump integration like this 
  // ensures that it is the first integrations to be initialized
  integrations: defaultIntegrations => {
    return [new Integrations.ElectronMinidump(), ...defaultIntegrations]
  }
}); 

1. No native crash reporting (remove the SentryMinidump integration)

import { init, Integrations } from '@sentry/electron';

init({
  dsn: '__DSN__',
  integrations: defaultIntegrations => {
    return ...defaultIntegrations.filter(i => i.name != Integrations.SentryMinidump.Id);
  }
}); 

WebContents 'unresponsive' Events

By default, the ElectronEvents integrations captures events for unresponsive Electron renderers. If you would like to disable this:

import { init, Integrations } from '@sentry/electron';

init({
  dsn: '__DSN__',
  integrations: [new Integrations.ElectronEvents({ unresponsive: false }];
}); 

[timfish]

3.0.0 has now been released and this migration guide has moved to here.

[AbhiPrasad]

how do you think I should go about improving this? Simply never queue errors originating from the transport?

I can’t ever see a case where these errors are of high value to users, I would just filter them out if possible. We do have the SentryError class for similar logic in the core JS SDK.