Electron
7 minute read

BugSplat supports collection of both Node.js and Breakpad (aka CrashReporter) errors in Electron applications. For most applications collecting Node.js errors is sufficient, however if your team runs a custom build of Electron, or contributes to the official Electron repo BugSplat also supports collecting Breakpad error reports via Electron’s CrashReporter. Before continuing with the integration please complete the following tasks:

 

Node.js Configuration


To collect Node.js errors in your application, run the following command in terminal or cmd at the root of your project to install BugSplat’s npm package:

npm install --save bugsplat

Require bugsplat at the entry point of your application (usually main.js) by adding the following code snippet. Be sure to replace DatabaseName, ApplicationName and the version number with the correct values for your application:

const bugsplat = require("bugsplat")("DatabaseName", "ApplicationName", "1.0.0.0");

Add the bugsplat.post function as an event handler for uncaught exceptions:

process.on("uncaughtException", bugsplat.post);

If your application uses promises you will also want to listen for unhandled promise rejections. Please note that this will only work for native promises:

process.on("uncaughtRejection", bugsplat.post);

Provide a callback method that executes after the error has been posted to BugSplat. It is recommended that you exit your application if an uncaughtException occurs. You may also want to display an alert to your user with information regarding their problem:

bugsplat.setCallback((error, responseBody) => { 
   // Display an alert and quit the application here
})

Many Electron applications run multiple Node.js processes. For instance, the electron-quick-start application runs both a main and a renderer process. You will need to require bugsplat in each process you want to capture errors. To capture errors in the renderer process, add the following to renderer.js:

window.onerror = (messageOrEvent, source, lineno, colno, error) => bugsplat.post(error);

Sometimes it is desirable to reload or quit the application when an error occurs in the renderer process. BugSplat’s callback function can be used to invoke functions in the main thread. The following is an example of how to invoke the main process from the renderer:

renderer.js

const electron = require('electron')
  const ipcRenderer = electron.ipcRenderer
  const bugsplat = require(""bugsplat")("DatabaseName", "ApplicationName", "1.0.0.0")
  bugsplat.setCallback((error, responseBody) => {
    ipcRenderer.send('rendererCrash')
  })

main.js

const electron = require('electron')
  const ipcMain = electron.ipcMain
  ipcMain.on('rendererCrash', function () {
    // Display an error and reload or quit the app here
    })
Test your BugSplat integration by throwing a new error in either the main or renderer process:
throw new Error("BugSplat!");

Navigate to the All Crashes page in BugSplat and you should see a new crash report for the application you just configured. Click the link in the Id column to see details about your crash on the Individual Crash page:

Integrating BugSplat with Electron Integrating BugSplat with Electron

That’s it! Your Electron application is now configured to post Breakpad crash reports to BugSplat.

Node.js API

In addition to the configuration demonstrated above, there are a few public methods that can be used to customize your BugSplat integration:

bugsplat.setAppKey (appKey) ; // A unique identifier for your application
  bugsplat.setUser(user); // The name or id of your user
  bugsplat.setEmail(email); // The email of your user 
  bugsplat.setDescription(description); // Additional info about your crash that gets reset after every post
  bugsplat.addAdditionalFile(pathToFile); // Path to a file to be added at post time (limit 1MB)
  bugsplat.setCallback(callback); // Function that accepts 2 parameters (err, responseBody) that runs after post
  bugsplat.post(error); // Post an arbitrary Error object to BugSplat

Breakpad

To enable collection of Breakpad crash reports add the following to each process you wish to capture errors from. Replace company name, product name, database name, application version, user email and comment accordingly:

const electron = require('electron')
electron.crashReporter.start({
    companyName: '<<company name>>',
    productName: '<<product name>>',
    submitURL: 'http://<<database name>>.bugsplat.com/post/bp/crash/postBP.php',
    autoSubmit: true,
    extra: {
        'prod': '<<product name>>',
        'key': '<<application version>>',
        'email': '<<user email>>',
        'comments': '<<comment>>'
    }
})

Follow our Breakpad docs to upload symbol files using symupload. Symbols for official Electron releases can be found on the releases page of the official git repository.

Important: if you are sending symbols from OS X there is no command line option to increase the upload timeout. We have created a fork of symupload with the timeout increased to 100 seconds (from 10 seconds). You will need to use a modified version of symupload to upload larger files such as “Electron Framework.sym”. You can download the modified archive here:

process.crash()

Navigate to the All Crashes page in BugSplat and you should see a new crash report for the application you just configured. Click the link in the Id column to see details about your crash on the Individual Crash page:

Integrating BugSplat with Electron Integrating BugSplat with Electron

Contributing


BugSplat loves open source software! If you have suggestions on how we can improve this integration, please reach out to support@bugsplat.com, create an issue in our GitHub repo or send us a pull request.