@errorgap/browser

Browser notifier for Errorgap. Captures uncaught errors and unhandled promise rejections, parses cross-browser stack traces, and ships notices to an Errorgap server. Includes an opt-in React error boundary.

When production source maps are available, the SDK resolves generated frames to their original files and sends a bounded source excerpt with each frame. This makes application and vendor source immediately available in Errorgap without a repository integration. Missing or inaccessible maps gracefully fall back to the generated stack trace.

Install

npm install @errorgap/browser

Or via CDN (UMD/IIFE bundle exposes window.Errorgap):

<script src="https://cdn.jsdelivr.net/npm/@errorgap/browser"></script>
<script>
  Errorgap.init({
    endpoint:    "https://errorgap.example.com",
    projectSlug: "your-project",
    apiKey:      "flk_...",
  });
</script>

Configure

Initialize as early as possible in the app entry point:

import { Errorgap } from "@errorgap/browser";

Errorgap.init({
  endpoint:    "https://errorgap.example.com",
  projectSlug: "your-project",
  apiKey:      "flk_...",
  environment: "production",
  release:     __APP_VERSION__,
});

init installs window listeners for error and unhandledrejection by default — pass captureGlobals: false to skip.

Manual notification

try {
  await risky();
} catch (err) {
  await Errorgap.notify(err, { context: { component: "checkout" } });
  throw err;
}

notify returns a DeliveryResult ({ status, body } on success, { error } on failure, { queued: true, status: 202 } in async mode, { sampled: true } if dropped by sampleRate). The SDK never throws.

React

import { ErrorgapBoundary } from "@errorgap/browser/react";

export function App() {
  return (
    <ErrorgapBoundary fallback={<p>Something went wrong.</p>}>
      <Routes />
    </ErrorgapBoundary>
  );
}

ErrorgapBoundary accepts a fallback (node or render function) and an onError(error, info) callback.

Configuration reference

| Option | Default | Notes | |---|---|---| | endpoint | (required) | Base URL of your Errorgap instance | | projectSlug | (required) | | | projectId | — | Optional, embedded in payload | | apiKey | — | Sent as x-errorgap-project-key | | environment | "production" | | | release | — | App version; embedded in payload | | sampleRate | 1.0 | Drop notices client-side at this rate | | sourceMaps | true | Resolve frames and source excerpts from deployed source maps | | async | true | Fire-and-forget delivery | | logger | console | Pass null to silence | | filterKeys | ["password", "token", "secret", ...] | Substring, case-insensitive | | captureGlobals | true | Install error and unhandledrejection listeners |

For source mapping, deploy the bundle's referenced .map file and include sourcesContent in it. The generated script and map must be readable by the browser; cross-origin assets therefore need suitable CORS headers. Set sourceMaps: false to disable runtime map fetching.

CORS

The browser sends notices cross-origin, so the Errorgap server must respond with Access-Control-Allow-Origin permitting your site. The SDK sets credentials: "omit" so no cookies cross the boundary.

Graceful flush

await Errorgap.flush();

Use this before navigating away or shutting down a single-page app to make sure queued notices are sent.

Development

npm install
npm test
npm run build

License

MIT.