untracker

Error-handling mechanics without project knowledge: CustomError, a typed error-catalog builder, and a pluggable transport interface. The module provides the machinery; the project provides the data — the error catalog, translations and toast UI stay in the consuming app.

Zero runtime dependencies. Rollbar, Hawk and React are optional peers.

Install

npm i untracker

Composition root

The transport is created by the project and passed in — the module never reads process.env, so it works outside Next.js too.

// app/lib/error-handler.ts
import { createErrorHandler, setGlobalErrorHandler } from "untracker";
import { rollbarTransport } from "untracker/rollbar";

export const errorHandler = createErrorHandler({
  transport: rollbarTransport({
    accessToken: process.env.NEXT_PUBLIC_ROLLBAR_CLIENT_TOKEN!,
  }),
  environment: process.env.NODE_ENV,
  release: process.env.NEXT_PUBLIC_APP_RELEASE,
  beforeSend: (event) => {
    delete event.context.password;
    return event;
  },
});

setGlobalErrorHandler(errorHandler);

After setGlobalErrorHandler, the free functions work anywhere without threading the instance through:

import { captureException } from "untracker";

captureException(err, { action: "checkout" });

Before it, calls fall back to consoleTransport — they log rather than throw, so no try/catch boilerplate is needed at call sites.

Error catalog

The builder lives here, the table lives in the project:

// app/lib/errors.ts
import { defineErrors } from "untracker";
import { errorHandler } from "./error-handler";

export const { Errors, ErrorCodes, createError, isErrorCode } = defineErrors({
  INVALID_CREDENTIALS: { status: 401, kind: "auth",       message: "Invalid email or password" },
  QUERY_FAILED:        { status: 500, kind: "database",   message: "Database query failed" },
  VALIDATION_ERROR:    { status: 400, kind: "validation", message: "Validation failed" },
}, {
  onCreate: (err) => errorHandler.captureException(err),
});

export type AppErrorCode = keyof typeof Errors;

createError is typed to the project's codes — createError("QUERY_FILED") is a compile error.

throw createError("VALIDATION_ERROR", { field: "email", message: "Email is required" });
createError("QUERY_FAILED", { report: false });   // skip onCreate for this call

Domain is expressed as kind, not subclasses — it survives serialization across a server-action boundary, where instanceof does not:

if (err.kind === "validation") { /* … */ }
CustomError.is(err, "QUERY_FAILED");   // reliable even if the package is duplicated in the bundle

Handler API

interface ErrorHandler {
  captureException(error: unknown, context?: Context): void;
  captureMessage(message: string, level?: Level, context?: Context): void;
  setUser(user: UserInfo | null): void;
  setContext(key: string, value: unknown): void;
  addBreadcrumb(breadcrumb: Breadcrumb): void;
  child(context: Context): ErrorHandler;
  flush(timeoutMs?: number): Promise<boolean>;
}

child() scopes context per request instead of repeating it at each call:

const log = errorHandler.child({ requestId, userId });
log.captureException(err);

flush() matters on Vercel/Lambda, where the process freezes right after the response:

await errorHandler.flush(2000);

Transports

| Import | Transport | |---|---| | untracker/rollbar | rollbarTransport({ accessToken }) | | untracker/hawk | hawkTransport({ token }) — resolves to the browser or node SDK automatically | | untracker | consoleTransport(), noopTransport() |

A custom transport is a small object:

import type { ErrorTransport } from "untracker";

export const httpTransport = (url: string): ErrorTransport => ({
  name: "http",
  captureException: (error, event) => {
    void fetch(url, { method: "POST", body: JSON.stringify({ ...event, stack: error.stack }) });
  },
  captureMessage: (message, event) => {
    void fetch(url, { method: "POST", body: JSON.stringify(event) });
  },
});

The core assembles the ErrorEvent — merging scope context, user, breadcrumbs and running beforeSend — so transports stay thin.

React

import { ErrorHandlerProvider } from "untracker/react";
import { addToast } from "@heroui/react";
import { useTranslations } from "next-intl";

const tErrors = useTranslations("Errors");

<ErrorHandlerProvider
  handler={errorHandler}
  notify={({ title }) => addToast({ title, color: "danger" })}
  translate={(code) => tErrors(code)}
>
  {children}
</ErrorHandlerProvider>

The provider takes a ready instance — the transport is live from module import, not from the first effect, so errors thrown during the initial render are not lost. The toast library and i18n stay in the project.

const handler = useErrorHandler();
const { notifyError } = useErrorNotification();

notifyError(err);                              // resolves the code through `translate`
notifyError(err, { code: "UNKNOWN_ERROR" });   // fallback when the error carries none

<ErrorBoundary fallback={(error, reset) => <Failed error={error} onRetry={reset} />}>
  {children}
</ErrorBoundary>

Testing

noopTransport() records instead of sending:

const transport = noopTransport();
const handler = createErrorHandler({ transport });

handler.captureException(new Error("boom"), { action: "save" });
expect(transport.events[0].context).toMatchObject({ action: "save" });

Development

npm install
npm test
npm run typecheck
npm run build