Bexer

Browser EXtensions Error Reporter catches global errors, shows notifications and opens error reporter in one click

Report page demo

Table of Contents

• Why
  • Catching Errors Without Bexer
  • Bexer in a Background Script
  • Bexer in a Non-Background Script
• Install
• Usage
  • Formats
  • Import
    • With Bundler
    • Without Bundler
  • Setup
    • Permissions in manifest.json
    • BG Window
  • Debugging
  • Examples of Setups
  • Demo
• Supported Browsers
• API
• Maintainer
• Contribute
• Credits
• License

Why

Catching Errors Without Bexer

There is some mess in how you catch errors in a web-extension:

'use strict'; // Only if you don't use ES6 modules.
/*
  bg-window — background window, main window of a web-extension.
  non-bg-windows — popup, settings and other pages windows of a web-extension, that are not bg-window.
*/

window.addEventListener('error', (errorEvent) => {/* ... */});

// Case 1
throw new Error('Root (caught only in bg-window, not caught in non-bg windows');

// Case 2
setTimeout(
  () => { throw new Error('Timeouted root (caught by handlers'); },
  0,
);

// Case 3
chrome.tabs.getCurrent(() => {

  throw new Error('Chrome API callback (not caught by handlers)');

});

// Case 4
chrome.tabs.getCurrent(() => setTimeout(() => {

  throw new Error('Timeouted Chrome API callback (caught by handlers)');

}, 0));

// Case 5
chrome.tabs.getCurrent(async () => {

  throw new Error(
    'Async Chrome API callback (caught by handlers in Chrome, not caught in FireFox even if timeouted)',
  );

});

So if you want error catchers to work — your code must be wrapped in setTimeout.

This behavior may be a bug and is discussed in https://crbug.com/357568.

Now let's look how to catch errors with Bexer.

Bexer in a Background Script

'use strict'; // Only if you don't use ES6 modules.
// Import and setup Bexer here, see corresponding paragraphs below.

throw new Error('This is caught by Bexer, notification is shown, opens error reporter on click');

Bexer in a Non-Background Script

// In popup, settings and other pages.
'use strict'; // Only if you don't use ES6 modules.

chrome.runtime.getBackgroundPage((bgWindow) =>
  bgWindow.Bexer.ErrorCatchers.installListenersOn({ hostWindow: window, nameForDebug: 'PUP' }, () => {

    // Put all your code inside this arrow body (it is timeouted).

    // Case 1:
    throw new Error('PUPERR (caught by Bexer)');

    // Case 2:
    document.getElementById('btn').onclick = () => {

      throw new Error('ONCLCK! (caught by Bexer)');

    };

    // Case 3:
    chrome.tabs.getCurrent(Bexer.Utils.timeouted(() => {

      throw new Error('Timeouted Chrome API callback (caught by Bexer)');

    }));

  })
);

// Case 4:
chrome.tabs.getCurrent(Bexer.Utils.timeouted(() => {

  throw new Error('Timeouted Chrome API callback (caught by Bexer)');

}));

// Case 5
chrome.tabs.getCurrent(async () => {

  throw new Error(
    'Async Chrome API callback (caught by Bexer in Chrome, never caught in FireFox even if timeouted)',
  );

});

Install

npm install --save @bexer/components

Usage

Formats

tree ./node_modules/bexer
bexer/
├── cjs // Common JS format: `require(...)`
│   ├── error-catchers.js
│   ├── get-notifiers-singleton.js
│   ├── index.js
│   └── utils.js
├── esm // EcmaScript Modules format: `import ...`
│   ├── error-catchers.js
│   ├── get-notifiers-singleton.js
│   ├── index.js
│   └── utils.js
├── package.json
└── umd // Universal Module Definition format: `<script src=...></script>`
    ├── error-catchers.js // Requires `utils` bundle
    ├── get-notifiers-singleton.js // Requires `utils` bundle
    ├── index.js // All in one bundle, no dependencies
    └── utils.js

Import

With Bundler

For webpack, rollup, etc.

import Bexer from 'bexer';

If you need only a part of the API:

import Utils from 'bexer/esm/utils';
import ErrorCatchers from 'bexer/esm/error-catchers';
import GetNotifiersSingleton from 'bexer/esm/get-notifiers-singleton';

Without Bundler

$ cp ./node_modules/bexer/umd/index.js ./foo-extension/vendor/bexer.js
$ cat foo-extension/manifest.json
...
"scripts": [
  "./vendor/optional-debug.js",
  "./vendor/bexer.js",
  ...
],
...

Setup

Permissions in manifest.json

"permissions": [
  "notifications",
  ...
],

BG Window

'use strict'; // Only if you don't use ES6 modules.
// For EcmaScript modules (node_modules/bexer/esm) and CommonJS (node_modules/bexer/cjs):
//   1. Import Bexer somehow.
//   2. window.Bexer = Bexer; // Expose for non-bg windows (popup, settings, etc.).

{
  console.log('Extension started.');

  const { notifyAbout } = window.Bexer.installErrorReporter({
    submissionOpts: {
      sendReportsToEmail: '[e-mail]',
      sendReportsInLanguages: ['en', 'ru'],
    },
  });

  chrome.runtime.onMessage.addListener(Bexer.Utils.timeouted(
    (request /* , sender, sendResponse */) => {
      if (request.type === 'error') {
        notifyAbout(request.errorEvent);
      }
    },
  ));
}

Debugging

1. Bundle visionmedia/debug for your environment and export global debug.
2. Enable it by debug.enable('bexer:*') in extension background window and reload extension.

Examples of Setups

See examples of setups for webpack, rollup or without bundlers.

Demo

clone this repo
npm install
cd examples
npm start
ls dist <- Load as unpacked extension and play (tested on Chrome).

Supported Browsers

Chrome: yes.
Firefox: yes, but notifications are not sticky, unhandled proimise rejections are never caught, clicking notifications sometimes doesn't work.

API

See API.md.

Maintainer

• ilyaigpetrov

Contribute

You are welcome to propose issues, pull requests or ask questions.
By commiting your code you agree to give all the rights on your contribution to ilyaigpetrov. E.g. he may publish code with your contributions under license different from GPL (proprietary, etc.).

Credits

For credits of used assets see https://github.com/error-reporter/error-reporter.github.io

License

This product is dual-licensed under GPL-3.0+ and commercial license, see LICENSE.md. To obtain commercial license contact ilyaigpetrov.