react-3rddigital-exception-tracking

Exception tracking SDK for React web projects. It captures browser JavaScript errors, unhandled promise rejections, React render errors, and manually reported exceptions, then posts them to the 3rdDigital exception ingestion API.

Install

npm install react-3rddigital-exception-tracking

Setup

Call setupExceptionTracking once, before rendering your React app.

import React from "react";
import ReactDOM from "react-dom/client";
import {
  ExceptionBoundary,
  setupExceptionTracking,
} from "react-3rddigital-exception-tracking";
import App from "./App";

setupExceptionTracking({
  url: process.env.REACT_APP_BASE_URL,
  apiKey: process.env.REACT_APP_EXCEPTION_API_KEY ?? "",
  projectKey: process.env.REACT_APP_EXCEPTION_PROJECT_KEY ?? "",
  appVersion: process.env.REACT_APP_VERSION,
  buildNumber: process.env.REACT_APP_BUILD_NUMBER,
  allowedInDevMode: false,
  enabled: true,
  reactTrackingEnabled: true,
  capacitorTrackingEnabled: true,
  source: "auto",
  userInfo: {
    id: currentUser?.id,
    email: currentUser?.email,
  },
  extraData: {
    environment: process.env.NODE_ENV,
  },
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <ExceptionBoundary fallback={null}>
    <App />
  </ExceptionBoundary>,
);

The SDK posts to:

{url}/exceptions/ingest/{projectKey}

If url already includes /exceptions/ingest/{projectKey}, that exact endpoint is used.

Enable or Disable Tracking

Use enabled as the master switch. When it is false, the SDK does not require API configuration, does not install global handlers, does not build exception payloads for automatic captures, and does not call the API. This only disables this package; it does not override or disable other tools such as Firebase Crashlytics, Sentry, or any other error library.

setupExceptionTracking({
  // ...
  enabled: false,
});

By default, tracking is disabled in NODE_ENV=development. Enable debug or local development reporting with:

setupExceptionTracking({
  // ...
  allowedInDevMode: true,
});

You can also control React web and Capacitor native reporting separately:

setupExceptionTracking({
  // ...
  reactTrackingEnabled: true,
  capacitorTrackingEnabled: false,
  source: "auto",
});

Backend Keys

The backend uses a few top-level fields for grouping, filtering, and counting. This package sends those fields directly:

• source is react for normal browser React apps and capacitor when running on a native Capacitor platform.
• deviceId is a lightweight generated id for React web reports unless you provide one in context; Capacitor apps use Device.getId().identifier.
• pageUrl, screenName, appVersion, buildNumber, userInfo, deviceInfo, browserInfo, osInfo, and metadata are sent as first-class payload fields.
• Dashboard display keys are populated directly: deviceInfo.model for Device and osInfo.name for OS.
• The detailed error origin, such as window.onerror, window.unhandledrejection, resource, or manual, is sent as metadata.errorSource and stackSource.

Capacitor Details

The package works in normal React projects without requiring a native Capacitor app. It includes @capacitor/app and @capacitor/device so native Capacitor builds can enrich payloads with app, OS, battery, language, and device details.

Capacitor enrichment is enabled by default when the app is running on a native Capacitor platform. Disable it with:

For native Capacitor reports, browserInfo is intentionally sent as an empty object. Raw Device.getInfo() values are copied into deviceInfo, Device.getInfo().name is used for the dashboard Device field, and Device.getId(), Device.getBatteryInfo(), language, app version, and build details are sent through deviceId, deviceInfo, osInfo, batteryInfo, memoryInfo, storageInfo, metadata, and otherDetails.

setupExceptionTracking({
  // ...
  enrichWithCapacitor: false,
});

If your app runtime cannot expose Capacitor detection early enough, force the backend source:

setupExceptionTracking({
  // ...
  source: "capacitor",
});

Manual Capture

import { captureException } from "react-3rddigital-exception-tracking";

try {
  await doSomething();
} catch (error) {
  captureException(error, { feature: "task-upload" });
}

Context

Attach data that should be included with future exception reports.

import {
  clearExceptionContext,
  setCurrentScreen,
  setExceptionContext,
} from "react-3rddigital-exception-tracking";

setCurrentScreen("/projects");
setExceptionContext({ userId: "123", role: "admin" });
clearExceptionContext(["role"]);

Options

| Option | Required | Description | | ---------------------------- | -------- | --------------------------------------------------------------------------------------------- | | url | Yes | Base API URL or full ingest URL. | | apiKey | Yes | Sent as the Api-Key header. | | projectKey | Yes | Project identifier used in the ingest URL and payload. | | headers | No | Extra request headers. | | appVersion | No | Version included in every payload. Defaults to 1.0.0. | | buildNumber | No | Build number included in every payload. | | userInfo | No | User data stored in the backend userInfo field. | | extraData | No | Static custom context merged into every payload. | | enabled | No | Master switch for all reporting. false skips handlers and API calls. | | allowedInDevMode | No | Enables reporting in NODE_ENV=development. Defaults to false. | | reactTrackingEnabled | No | Enables React/browser reporting when the active source is react. Defaults to true. | | capacitorTrackingEnabled | No | Enables native Capacitor reporting when the active source is capacitor. Defaults to true. | | installGlobalHandlers | No | Captures window.error and promise rejections. Defaults to true. | | captureUnhandledRejections | No | Captures unhandled promise rejections. Defaults to true. | | captureResourceErrors | No | Captures failed script/image/link loads. Defaults to false. | | enrichWithCapacitor | No | Loads optional Capacitor details in native builds. Defaults to true. | | source | No | auto, react, or capacitor. Defaults to auto. | | beforeSend | No | Mutate or drop payloads before upload. Return null to skip. | | onError | No | Called when the SDK fails to upload an exception. |

Payload

Each payload includes:

• Error title, message, stack trace, backend source, detailed error source, timestamp, project key, app version, and build number.
• Stable device id, friendly device model, page URL, screen name, browser, OS, device, screen, network, memory, storage, document, history, performance, and referrer details.
• Static userInfo, static extraData, current context, per-call extraData, and metadata.

Cleanup

setupExceptionTracking returns a cleanup function for tests or micro-frontends.

const cleanup = setupExceptionTracking(options);
cleanup();