@hawk.so/nodejs

中文文档
3.3.2发布于 2026/02/12AGPL-3.0-onlyTypeScriptESM + CJS近 30 天下载 5829

Node.js catcher for Hawk

原始使用文档
文档目录11 节
  1. Initial params
  2. Usage
  3. Install
  4. Require HawkCatcher module
  5. Init HawkCatcher
  6. Global context
  7. Releases
  8. Catch exceptions manually
  9. Breadcrumbs
  10. Sensitive data filtering
  11. License

@hawk.so/nodejs

Node.js errors Catcher module for Hawk.so

Initial params

Initialization params:

nametyperequireddescription
tokenstringrequiredYour project's Integration Token
releasestringoptionalUnique identifier of the release.
contextobjectoptionalAny data you want to pass with every message.
disableGlobalErrorsHandlingbooleanoptionalDo not initialize global errors handling
beforeSendfunction(event) => event | false | voidoptionalFilter data before sending. Return modified event, false to drop the event.
breadcrumbsfalse or objectoptionalPass false to disable. Pass options object to configure (see Breadcrumbs). Default: enabled.

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:

ParamTypeIs requiredDescription
idstring|numberrequiredUser's identifier
namestring-User's name
urlstring-User's profile url
imagestring-User's profile pic url
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

OptionTypeDefaultDescription
maxBreadcrumbsnumber15Maximum number of breadcrumbs to store. When the limit is reached, oldest breadcrumbs are removed (FIFO).
beforeBreadcrumbfunctionundefinedHook called before each breadcrumb is stored. Receives (breadcrumb, hint). Return modified breadcrumb to keep it, false to discard.

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.

版本与发布记录

@hawk.so/nodejs 共发布 32 个版本,首次发布于 2020/06/09;过去 12 个月发布了 4 个版本。

版本发布日期距今
3.3.2latest2026/02/129 个月前
3.3.12026/02/119 个月前
3.3.02026/02/089 个月前
3.2.02025/12/1511 个月前
3.1.62025/09/241.1 年前
3.1.52024/12/061.9 年前

关于 @hawk.so/nodejs 的常见问题

@hawk.so/nodejs 是什么?

Node.js catcher for Hawk

如何安装 @hawk.so/nodejs?

在项目目录运行 npm install @hawk.so/nodejs,或使用 pnpm add / yarn add / bun add。

@hawk.so/nodejs 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hawk.so/nodejs 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hawk.so/nodejs 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js 24.x。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hawk.so/nodejs 可以商用吗?

@hawk.so/nodejs 使用 AGPL-3.0-only 许可。最严格的 Copyleft:除分发外,通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括,不构成法律意见,请以许可原文为准。

@hawk.so/nodejs 的下载量有多少?

根据 npm 官方下载统计,@hawk.so/nodejs 在 2026/10/18 – 2026/11/16 这 30 天内被下载 5,829 次,日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hawk.so/nodejs 还在维护吗?

最新版本 3.3.2 发布于 2026/02/12(9 个月前);至今共发布 32 个版本,其中过去 12 个月发布了 4 个;首次发布于 2020/06/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。