BugSplat

Crash and error reporting built for busy developers.

👋 Introduction

BugSplat-js is a JavaScript error-reporting system for web applications. Before continuing with the tutorial, please make sure you have completed the following checklist:

• Sign Up as a new BugSplat user.
• Log In using your email address.

🏗 Installation

Install bugsplat via npm. This package currently requires Node.js 18 or later.

npm i bugsplat --save

If you need to use a version of Node.js older than 18, you can install [email protected].

⚙️ Configuration

Depending on your project's module system, you can either import or require BugSplat:

ESM

import { BugSplat } from 'bugsplat';

CommonJS

const { BugSplat } = require('bugsplat');

Deno

import { BugSplat } from 'https://esm.sh/[email protected]';

Create a new instance of the BugSplat class with the name of your BugSplat database, the name of your application and the version of your application:

const bugsplat = new BugSplat(database, application, version);

Listen for window.onerror events and post them to BugSplat:

window.onerror = async (event, source, lineno, colno, error) => {
  await bugsplat.post(error);
}

Also listen for window.unhandledpromiserejection events and post them to BugSplat:

window.onunhandledrejection = async (rejection) => {
  await bugsplat.post(rejection.reason)
}

Throw an exception after the event handler has been added.

throw new Error('BugSplat!');

You can use bugsplat-js to capture errors that originate inside of try-catch blocks:

try {
    throw new Error('BugSplat');
} catch(error) {
    await bugsplat.post(error);
}

You can also use bugsplat-js to post errors from promise rejections:

Promise.reject(new Error('BugSplat!')).catch(error => bugsplat.post(error, {}));

✅ Verification

After posting an error with bugsplat-js, navigate to the Crashes page. 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 Crash page:

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

🧩 API

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

bugsplat.setDefaultAppKey(appKey); // Additional metadata that can be queried via BugSplat's web application
bugsplat.setDefaultUser(user); // The name or id of your user
bugsplat.setDefaultEmail(email); // The email of your user
bugsplat.setDefaultDescription(description); // Additional info about your crash that gets reset after every post
async bugsplat.post(error, options); // Posts an arbitrary Error object to BugSplat
// If the values options.appKey, options.user, options.email, options.description are set the corresponding default values will be overwritten
// Returns a promise that resolves with properties: error (if there was an error posting to BugSplat), response (the response from the BugSplat crash post API), and original (the error passed by bugsplat.post)

📢 Upgrading

If you are developing a Node.js application and were using bugsplat-js <= 5.0.0 please upgrade to bugsplat-node. BugSplat-node has the same consumer APIs as bugsplat-js <= 5.0.0. Additionally, support for file attachments and exiting the Node process in the error handler have been moved to bugsplat-node so that bugsplat-js can be run in browsers as well as Node.js environments.

🧑‍💻 Contributing

BugSplat loves open source software! Please check out our project on GitHub and send us a pull request.

👷 Support

If you have any additional questions, please email or support team, join us on Discord, or reach out via the chat in our web application.