@errcheck/js-server

Errcheck's error-tracking SDK for server-side JavaScript.

uncaughtException/unhandledRejection handlers, AsyncLocalStorage-backed per-request isolation, and an HTTP transport.

Works in both JavaScript and TypeScript projects — type definitions are bundled in.

Install

npm install @errcheck/js-server
# or
pnpm add @errcheck/js-server
# or
yarn add @errcheck/js-server

import * as Errcheck from "@errcheck/js-server";

Errcheck.init({
  dsn: "https://[email protected]/1234567890abcdef", // add project dsn here
  environment: process.env.NODE_ENV,
});

Per-request isolation

Wrap each incoming request in an isolation scope so tags, user, and breadcrumbs never leak between concurrent requests:

app.use((req, res, next) => {
  Errcheck.withIsolationScope(() => {
    Errcheck.setUser({ id: req.user?.id });
    next();
  });
});

sequenceDiagram
    participant A as Request A
    participant B as Request B
    participant S as AsyncLocalStorage-backed<br/>isolation scope

    A->>S: withIsolationScope(() => setUser(userA))
    B->>S: withIsolationScope(() => setUser(userB))
    Note over S: Concurrent requests never share<br/>tags, user, or breadcrumb state
    A-->>A: captureException() → tagged with userA only
    B-->>B: captureException() → tagged with userB only

Without this, an error thrown while handling one request could be captured with breadcrumbs or user context left over from a different, concurrent request.

API

| Function | Description | | --- | --- | | init(options) | Initializes the SDK. Call once, as early as possible. | | captureException(error, hint?) | Reports an Error (or any thrown value). Returns the event ID. | | captureMessage(message, level?) | Reports a plain message instead of an exception. | | addBreadcrumb(breadcrumb) | Appends a breadcrumb to the current scope's trail. | | setUser(user \| undefined) | Attaches user context to subsequent events. Pass undefined to clear. | | setTag(key, value) | Attaches a searchable key/value tag to subsequent events. | | setContext(key, context) | Attaches a structured, non-searchable context object to subsequent events. | | flush(timeout?) | Waits for pending events to send, up to timeout ms. Call before process exit. | | getClient() | Returns the active client instance, if any. | | withIsolationScope(callback) | Runs callback with a fresh isolation scope, per-request. |

Full configuration reference: see the root README.

License

MIT