fix: Dispatch correctly for bundlers like webpack

README.md

@@ -90,3 +90,4 @@ Sentry.captureEvent({
 
 * [Releases](https://github.com/getsentry/sentry-electron/releases)
 * [Bug Tracker](https://github.com/getsentry/sentry-electron/issues)
+* [Example App](https://github.com/getsentry/sentry-electron/tree/master/example)

docs/config.rst

@@ -53,24 +53,39 @@ possible.
 Sandbox Mode
 ------------
 
-Currently, the SDK does not support `sandbox mode`_. Official support for this
-will be added in a future release.
+`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.
 
-To still receive JavaScript errors, you can work around this limitation by
-configuring the Browser SDK instead. However, breadcrumbs and context
-information are not synchronized between renderers and the main process anymore.
-Also, Electron-specific event metadata will be missing, most notably the
-``release`` field.
+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:
 
 .. code-block:: javascript
 
-    // Use @sentry/browser in place of @sentry/electron
-    const { init } = require('@sentry/browser');
-    init({ dsn: '___PUBLIC_DSN___' });
+    module.exports = {
+      externals: {
+        electron: 'commonjs electron',
+      },
+      // ...
+    };
+
+Or for Rollup:
+
+.. code-block:: javascript
 
-Even in Sandbox mode, you can still receive native crash reports by activating
-the crash reporter manually. For a detailed description, see
-:ref:`electron-native-manual`.
+    export default {
+      external: ['electron'],
+      plugins: [commonjs()],
+      // ...
+    };
 
 Options
 -------
@@ -264,5 +279,5 @@ call. All available options are documented below:
           }
         }
 
-.. _sandbox mode: https://github.com/electron/electron/blob/master/docs/api/sandbox-option.md
-.. _Electron CrashReporter: https://github.com/electron/electron/blob/master/docs/api/crash-reporter.md
+.. _Sandbox mode: https://electronjs.org/docs/api/sandbox-option
+.. _Electron CrashReporter: https://electronjs.org/docs/api/crash-reporter

docs/index.rst

@@ -128,11 +128,6 @@ 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 :doc:`sourcemaps`.
 
-.. admonition:: Known Issue
-
-    Sentry does not show source code context alongside stack traces in renderer
-    crashes. This is a known issue and will be fixed in a future SDK update.
-
 Deep Dive
 ---------
 
@@ -150,6 +145,6 @@ there is additional documentation available that covers all the rest:
 
 .. _next generation JavaScript SDKs: https://github.com/getsentry/raven-js/tree/next#readme
 .. _Sentry DSN: https://docs.sentry.io/hosted/quickstart/#configure-the-dsn
-.. _Electron CrashReporter: https://github.com/electron/electron/blob/master/docs/api/crash-reporter.md
-.. _Sandbox mode: https://github.com/electron/electron/blob/master/docs/api/sandbox-option.md
+.. _Electron CrashReporter: https://electronjs.org/docs/api/crash-reporter
+.. _Sandbox mode: https://electronjs.org/docs/api/sandbox-option
 .. _Source Maps: http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/

docs/native.rst

@@ -101,4 +101,4 @@ full Electron SDK:
 .. _releases page: https://github.com/electron/electron/releases/latest
 .. _Crashpad: https://chromium.googlesource.com/crashpad/crashpad/
 .. _Breakpad: https://chromium.googlesource.com/breakpad/breakpad
-.. _Electron CrashReporter: https://github.com/electron/electron/blob/master/docs/api/crash-reporter.md
+.. _Electron CrashReporter: https://electronjs.org/docs/api/crash-reporter

docs/sourcemaps.rst

@@ -187,7 +187,7 @@ the release with the following command:
 For convenience, you can alternatively pass the ``--finalize`` flag to the
 ``new`` command which will immediately finalize the release.
 
-.. _sandboxing: https://github.com/electron/electron/blob/master/docs/api/sandbox-option.md
+.. _sandboxing: https://electronjs.org/docs/api/sandbox-option
 .. _releases API: https://docs.sentry.io/api/releases/
 .. _Sentry CLI: https://docs.sentry.io/learn/cli/
 .. _Webpack plugin: https://github.com/getsentry/sentry-webpack-plugin

example/README.md

@@ -0,0 +1,44 @@
+<p align="center">
+  <a href="https://sentry.io" target="_blank" align="center">
+    <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280">
+  </a>
+  <br />
+</p>
+
+# Sentry Crash Test
+
+This is an example Electron app that sends reports to Sentry for JavaScript and
+native crashes. It uses `webpack` to build the renderer JavaScript.
+
+![Screenshot](https://user-images.githubusercontent.com/1433023/39999656-f07bd98a-5789-11e8-9bc7-d68c1e03d897.png)
+
+## Usage
+
+To run the example application, install its dependencies, build renderer assets
+and start the app:
+
+```sh
+yarn         # Install dependencies
+yarn build   # Build renderer assets
+yarn start   # Run the application
+```
+
+## Development
+
+For local development, use `yarn link` to use your local checkout of the SDK
+over the version downloaded from npm:
+
+```sh
+# cd /path/to/sentry-electron
+yarn build
+yarn link
+
+# cd /path/to/example
+yarn link @sentry/electron
+yarn build
+yarn start
+```
+
+When making changes to the SDK, always remember to execute `yarn build` in the
+SDK folder before rebuilding the example app. Otherwise, changes will not
+reflect in the bundle.

example/app/index.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="UTF-8">
+  <title>Sentry Crash Test</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+
+<body>
+  <div class="main">
+    <img src="sentry.png" alt="Sentry" height="125">
+
+    <h1>Sentry Crash Test</h1>
+    <div class="group">
+      <h3 class="group-head">JavaScript</h3>
+      <a href="javascript:errorMain()" class="crash">[ Main Process ]</a>
+      <a href="javascript:errorRenderer()" class="crash">[ Renderer Process ]</a>
+    </div>
+    <div class="group">
+      <h3 class="group-head">Native Crash</h3>
+      <a href="javascript:crashMain()" class="crash">[ Crash ]</a>
+      <a href="javascript:crashRenderer()" class="crash">[ Crash Renderer ]</a>
+    </div>
+  </div>
+
+  <footer class="footer">
+    Node.js
+    <script>document.write(versions.node)</script>
+    <br> Chromium
+    <script>document.write(versions.chrome)</script>
+    <br> Electron
+    <script>document.write(versions.electron)</script>
+    <br>
+  </footer>
+</body>
+
+</html>

example/renderer.js → example/app/index.js

@@ -1,21 +1,27 @@
 // Activate the Sentry Electron SDK as early as possible in every process.
 // The SDK must be installed in the main process for this to work.
-require('./sentry');
+require('../sentry');
 
 const { ipcRenderer } = require('electron');
 
-document.querySelector('#error-main').addEventListener('click', () => {
+window.errorMain = () => {
   ipcRenderer.send('demo.error');
-});
+};
 
-document.querySelector('#error-render').addEventListener('click', () => {
+window.errorRenderer = () => {
   throw new Error('Error triggered in renderer process');
-});
+};
 
-document.querySelector('#crash-main').addEventListener('click', () => {
+window.crashMain = () => {
   ipcRenderer.send('demo.crash');
-});
+};
 
-document.querySelector('#crash-render').addEventListener('click', () => {
+window.crashRenderer = () => {
   process.crash();
-});
+};
+
+window.versions = {
+  chrome: process.versions.chrome,
+  electron: process.versions.electron,
+  node: process.versions.node,
+};

example/app/style.css

@@ -0,0 +1,62 @@
+html,
+body {
+  height: 100%;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  -webkit-app-region: drag;
+  background: url(pattern.png);
+  font-family: Helvetica, sans-serif;
+  font-weight: 300;
+  flex-direction: column;
+  justify-content: space-between;
+  display: flex;
+}
+
+.main {
+  background: white;
+  border: 1px solid #c7d0d4;
+  border-radius: 5px;
+  margin: auto;
+  text-align: center;
+  width: 80%;
+}
+
+h1 {
+  font-weight: 500;
+  margin-bottom: 1em;
+}
+
+.group {
+  font-size: 140%;
+  width: 40%;
+  display: inline-block;
+}
+
+.group-head {
+  text-transform: uppercase;
+  font-weight: 700;
+  font-size: 80%;
+}
+
+.footer {
+  background: linear-gradient(0deg, white, transparent);
+  color: #aaa;
+  text-align: center;
+  padding: 1em;
+}
+
+.crash {
+  cursor: pointer;
+  color: inherit;
+  display: block;
+  text-decoration: none;
+  margin-bottom: 1em;
+}
+
+.crash:hover {
+  font-weight: 500;
+}