Searchโ€ฆ
Node.js

Introduction

BugSplat's bugsplat-node package provides error reporting for Node.js and Electron applications. Before integrating your application with BugSplat, make sure to review the Getting Started resources and complete the simple startup tasks listed below.
    โ€‹Sign up for a BugSplat account
    โ€‹Log in using your email address
    Create a new database for your application
Need any further help? Check out the full BugSplat documentation here, or email the team at [email protected].

Configuration

To add the bugsplat package to your application, run the following shell command at the root of your projectโ€™s directory:
1
npm i bugsplat-node --save
Copied!
Require bugsplat at the entry point of your application (usually main.js) by adding the following code snippet:
1
const BugSplat = require('bugsplat-node');
Copied!
Create a new instance of the BugSplat class being sure to replace the database, application, and version with the correct values for your application:
1
const bugsplat = new BugSplat(database, application, version);
Copied!
Set the bugsplat.post function as an event handler for uncaught exceptions:
1
process.on('uncaughtException', async (error) => await bugsplat.postAndExit(error));
Copied!
You will also want to listen for unhandled promise rejections. Please note that this will only work for native promises:
1
process.on('unhandledRejection', async (error) => await bugsplat.postAndExit(error))
Copied!
Throw an exception after the event handler has been added:
1
throw new Error('BugSplat!');
Copied!
You can also use bugsplat-node to post errors from non-fatal promise rejections and errors that originate inside of try-catch blocks:
1
Promise.reject(new Error('BugSplat!')).catch(async (error) => await bugsplat.post(error, options));
Copied!
1
try {
2
throw new Error('BugSplat!');
3
} catch (error) {
4
await bugsplat.post(error, options));
5
}
Copied!
After posting an error with bugsplat-node, navigate to the 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 Crash page:
Node.js Crashes
Node.js Crash
Thatโ€™s it! Your application is now configured to post crash reports to BugSplat.

Source Maps

BugSplat has the ability to map uglified and minified JavaScript function names, file names, and line numbers back to their original values via source maps. For information on how to configure your application to upload source maps to BugSplat, please see the link below.

API

In addition to the configuration demonstrated above, there are a few public methods that can be used to customize your BugSplat integration:
1
bugsplat.setDefaultAppKey(appKey); // Additional metadata that can be queried via BugSplat's web application
2
bugsplat.setDefaultUser(user); // The name or id of your user
3
bugsplat.setDefaultEmail(email); // The email of your user
4
bugsplat.setDefaultDescription(description); // A description placeholder that can be overridden at crash time
5
bugsplat.setDefaultAdditionalFilePaths([paths]); // Paths to files to be sent to BugSplat at post time (limit 1MB)
6
bugsplat.postAndExit(error, options); // Wrapper for post that calls process.exit(1) after posting error to BugSplat
7
bugsplat.post(error, options); // Aysnc function that posts an arbitrary Error object to BugSplat
8
// If the values options.appKey, options.user, options.email, options.description, options.additionalFilePaths are set the corresponding default values will be overwritten
9
// 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)
10
view rawbugsplat-node-api.js hosted with โค by GitHub
Copied!

Additional Considerations

It is recommended that you exit and restart your application after an uncaughtException or unhandledRejection occurs. Packages such as pm2 and forever can be configured to restart your application.
Additionally you can use domains to handle errors differently across various parts of your application. Domains are pending deprecation according the the Node.js documentation, however a suitable replacement has not been added yet.
More information regarding domain deprecation can be found here.

Contributing

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