BugsRadar for Node.js

Updated 1 October 2026 · BugsRadar team

One npm package for servers, workers and command-line tools on Node.js 18 and later: uncaught errors, direct calls, Express, winston and pino. ESM and CommonJS, with TypeScript types.

You need a BugsRadar project with a channel and the project's API key first: see Get started.

Install the package

npm install bugsradar

Create the client

Create one client for the whole process:

import { BugsRadar } from 'bugsradar';

export const bugsRadar = new BugsRadar({
  apiKey: process.env.BUGSRADAR_KEY,
  environment: process.env.NODE_ENV, // optional
});

With CommonJS: const { BugsRadar } = require('bugsradar');. Keep the key out of the source, for example in an environment variable. The key is required: an empty one throws when the client is created.

Uncaught errors

The client reports uncaught exceptions by itself. Unhandled promise rejections become uncaught exceptions in Node.js 15 and later, so they are reported the same way. BugsRadar waits up to shutdownTimeout for the report to leave, then the process exits with code 1, as it would without BugsRadar. If your application has its own uncaughtException handler, the exit is left to it.

To turn this off, pass captureUncaught: false.

Direct calls

Report exceptions or your own events:

import { bugsRadar } from './bugsradar.js';

try {
  await createOrder(orderId);
} catch (error) {
  bugsRadar.sendException(error, { module: 'Orders' });

  // or the full event
  bugsRadar.send({
    exception: error,
    messageTemplate: 'Order {orderId} failed',
    message: `Order ${orderId} failed`,
    properties: { orderId },
    module: 'Orders',
  });
}

send and sendException queue the event and return at once, so reporting an error never adds network time to your own code. Nothing throws: delivery problems are written to the console as warnings.

BugsRadar groups repeats of an error by the exception type and the top frames of the stack, or by the message template. To group by your own key, set fingerprint on the event.

Express, winston and pino

Each integration has a page of its own:

• Express - an error handler that reports every unhandled error of a request with its method and path.
• winston - a transport next to the ones you already have.
• pino - a transport that runs in pino's worker thread.

Before the process exits

Command-line tools, scheduled jobs and serverless functions often exit right after their work. Wait for the queued reports first:

await bugsRadar.flush(); // waits up to shutdownTimeout

How events travel

• Events go to an in-process queue and are sent in the background; your code never waits for the network.
• Repeats of the same error within repeatInterval (5 seconds) are folded into one request with a count. A crash loop costs one request every few seconds, not thousands per second.
• The same Error object seen twice - by Express and by winston, say - is sent once.
• On 429 the client waits as long as the server asks; on 5xx and network failures it retries three times.

Configuration

Browser apps

This package is for Node.js. Code that runs in the browser - React, Angular, Vue - is public, and so would be a key inside it: anyone could take it and fill your channels.

Something doesn't arrive? Write to support@bistriy.com and include the warnings the package wrote to the console.