https://github.com/bugsplat-git/bugsplat-js
🐛💥🕵️ BugSplat error reporting for modern browsers
https://github.com/bugsplat-git/bugsplat-js
callstack crash crash-report error error-handling errors exception exception-handling exceptions stacktrace
Last synced: 10 months ago
JSON representation
🐛💥🕵️ BugSplat error reporting for modern browsers
- Host: GitHub
- URL: https://github.com/bugsplat-git/bugsplat-js
- Owner: BugSplat-Git
- License: mit
- Created: 2017-06-13T18:53:30.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-11-27T23:27:34.000Z (about 1 year ago)
- Last Synced: 2025-02-28T22:51:08.465Z (10 months ago)
- Topics: callstack, crash, crash-report, error, error-handling, errors, exception, exception-handling, exceptions, stacktrace
- Language: TypeScript
- Homepage: https://docs.bugsplat.com/introduction/getting-started/integrations/web/javascript
- Size: 388 KB
- Stars: 5
- Watchers: 4
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://bugsplat.com)
#
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](https://app.bugsplat.com/v2/sign-up) as a new BugSplat user.
* [Log In](https://app.bugsplat.com/auth0/login) using your email address.
## 🏗 Installation
Install `bugsplat` via npm. This package currently requires Node.js 18 or later.
```sh
npm i bugsplat --save
```
If you need to use a version of Node.js older than 18, you can install bugsplat@7.1.4.
## ⚙️ Configuration
Depending on your project's module system, you can either `import` or `require` BugSplat:
### ESM
```ts
import { BugSplat } from 'bugsplat';
```
### CommonJS
```ts
const { BugSplat } = require('bugsplat');
```
### Deno
```ts
import { BugSplat } from 'https://esm.sh/bugsplat@8.0.1';
```
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:
```ts
const bugsplat = new BugSplat(database, application, version);
```
Listen for `window.onerror` events and post them to BugSplat:
```ts
window.onerror = async (event, source, lineno, colno, error) => {
await bugsplat.post(error);
}
```
Also listen for `window.unhandledpromiserejection` events and post them to BugSplat:
```ts
window.onunhandledrejection = async (rejection) => {
await bugsplat.post(rejection.reason)
}
```
Throw an exception after the event handler has been added.
```ts
throw new Error('BugSplat!');
```
You can use bugsplat-js to capture errors that originate inside of try-catch blocks:
```ts
try {
throw new Error('BugSplat');
} catch(error) {
await bugsplat.post(error);
}
```
You can also use bugsplat-js to post errors from promise rejections:
```ts
Promise.reject(new Error('BugSplat!')).catch(error => bugsplat.post(error, {}));
```
## ✅ Verification
After posting an error with bugsplat-js, navigate to the [Crashes](https://app.bugsplat.com/v2/crashes?database=Fred&c0=appName&f0=CONTAINS&v0=my-react-crasher) 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](https://app.bugsplat.com/v2/crash?database=Fred&id=94338) 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:
```ts
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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/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](https://github.com/BugSplat-Git/bugsplat-js) and send us a pull request.
## 👷 Support
If you have any additional questions, please email or [support](mailto:support@bugsplat.com) team, join us on [Discord](https://discord.gg/K4KjjRV5ve), or reach out via the chat in our web application.