Node.js errors Catcher module for Hawk.so

Initial params

Initialization params:

Usage

1. Create an account and get an Integration Token.
2. Add @hawk.so/nodejs package to your project.
3. Require and initialize module.

Install

Use NPM or Yarn to install Catcher @hawk.so/nodejs.

$ npm install @hawk.so/nodejs --save

$ yarn add @hawk.so/nodejs

Require HawkCatcher module

For CommonJS projects

const HawkCatcher = require('@hawk.so/nodejs').default;

For ESM projects

import HawkCatcher from '@hawk.so/nodejs';

Init HawkCatcher

Initialize HawkCatcher in the entry file of your project by passing a project token.

const HAWK_TOKEN = 'eyJhb...VPsc=';
HawkCatcher.init(HAWK_TOKEN);

HawkCatcher adds listeners for uncaughtException and unhandledRejection itself.

Disable global errors handling

If you don't want to initialize handlers for global exceptions then use disableGlobalErrorsHandling param.

HawkCatcher.init({
  token: HAWK_TOKEN,
  disableGlobalErrorsHandling: true,
});

Then you can catch events manually.

Global context

You can define global context for all event to be caught.

HawkCatcher.init({
  token: HAWK_TOKEN,
  context: {
    myOwnDebugInfo: '1234'
  }
});

Releases

To mark events to specific release pass the release identifier string to intial config.

HawkCatcher.init({
  token: 'INTEGRATION TOKEN',
  release: process.env.releaseId
})

Catch exceptions manually

After initializing you can catch exceptions manually in try-catch constructions in any project's place.

Just require HawkCatcher and call .send() method.

try {
  throw new Error('My lovely error');
} catch (e) {
  HawkCatcher.send(e);
}

If HawkCatcher was not initialized then .send() method will do nothing.

Event context

You can pass any information as context param for a single event.

try {
  throw new Error('User not found');
} catch (e) {
  HawkCatcher.send(e, {
    myOwnDebugInfo: '1234'
  });
}

This context object will be merged with global context if it exists.

User

You can send user data as a third param.

Available fields:

try {
  throw new Error('Cannot create a new post');
} catch (e) {
  HawkCatcher.send(e, {}, {
    id: 1234,
    name: 'Taly'
});
}

Breadcrumbs

Breadcrumbs track events leading up to an error, providing context for debugging. Same API as @hawk.so/javascript (add, get, clear); in Node there is no automatic tracking of fetch/navigation/clicks, only manual breadcrumbs.

Default configuration

By default, breadcrumbs are enabled (custom breadcrumbs only):

HawkCatcher.init({
  token: 'INTEGRATION_TOKEN'
  // breadcrumbs enabled by default
});

Disabling breadcrumbs

To disable breadcrumbs entirely:

HawkCatcher.init({
  token: 'INTEGRATION_TOKEN',
  breadcrumbs: false
});

Custom configuration

Configure breadcrumbs (same options as JS where applicable):

HawkCatcher.init({
  token: 'INTEGRATION_TOKEN',
  breadcrumbs: {
    maxBreadcrumbs: 20,
    beforeBreadcrumb: (breadcrumb, hint) => {
      if (breadcrumb.category === 'auth' && breadcrumb.data?.userId) {
        return false; // Discard
      }
      return breadcrumb;
    }
  }
});

Breadcrumbs options

Manual breadcrumbs

Add custom breadcrumbs manually. Breadcrumbs accumulate in a buffer and are attached to every event until explicitly cleared via HawkCatcher.breadcrumbs.clear():

HawkCatcher.breadcrumbs.add({
  type: 'logic',
  category: 'auth',
  message: 'User logged in',
  level: 'info',
  data: { userId: '123' }
});

Breadcrumb methods

Same as in JS catcher:

// Add a breadcrumb
HawkCatcher.breadcrumbs.add(breadcrumb, hint);
// Get current breadcrumbs
const breadcrumbs = HawkCatcher.breadcrumbs.get();
// Clear all breadcrumbs
HawkCatcher.breadcrumbs.clear();

Sensitive data filtering

Use the beforeSend() hook to filter data before sending to Hawk.

• Return modified event — the modified event will be sent
• Return false — the event will be dropped entirely
• Any other value is invalid — the original event is sent as-is (a warning is logged)

HawkCatcher.init({
  token: 'INTEGRATION TOKEN',
  beforeSend(event) {
    // Strip sensitive user data
    if (event.user && event.user.name) {
      delete event.user.name;
    }
    return event;
  }
});

Drop an event entirely:

HawkCatcher.init({
  token: 'INTEGRATION TOKEN',
  beforeSend(event) {
    if (event.title.includes('ignore-me')) {
      return false;
    }
    return event;
  }
});

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for the full text.