errsight-js

JavaScript/React client for ErrSight error tracking. Captures errors and log events from browser apps and ships them to the ErrSight API in batches.

Requirements

• Modern browser (Fetch API + visibilitychange event)
• React >= 16.8 (optional — only required for the React integration)

Installation

npm install errsight
# or
yarn add errsight

For CDN / <script> tag use:

<script src="https://unpkg.com/errsight/dist/errsight.browser.min.js"></script>
<script>
  Errsight.init({ apiKey: "elp_your_api_key" });
</script>

Quick start

Call init once at the top of your entry point before any other code runs:

import Errsight from "errsight";

Errsight.init({
  apiKey: "elp_your_api_key",
  environment: "production",
});

By default init also registers window.onerror and unhandledrejection handlers, so uncaught exceptions and rejected promises are captured automatically.

Configuration

Errsight.init({
  apiKey: "elp_your_api_key",     // required
  environment: "production",       // default: "production"
  minLevel: "error",               // default: "error" — minimum severity to capture
  captureGlobalErrors: true,       // default: true — attach window.onerror + unhandledrejection
  batchSize: 10,                   // default: 10 — events per HTTP request
  flushInterval: 2000,             // default: 2000 ms — background flush cadence (0 to disable)
  beforeSend: (event) => event,    // optional — mutate or drop events (return null to drop)
  sendDefaultPii: false,           // default: false — when false, query string + fragment are stripped from URL
  sampleRate: 1.0,                 // default: 1.0 — probability that any event is sent
  maxQueueSize: 256,               // default: 256 — in-memory queue cap; new events drop when full
});

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Your project API key (required) | | environment | string | "production" | Environment tag attached to every event | | minLevel | string | "error" | Minimum level: debug info warning error fatal | | captureGlobalErrors | boolean | true | Auto-capture uncaught errors and rejected promises | | host | string | "https://errsight.com" | Override the API endpoint host | | batchSize | number | 10 | Max events sent in a single HTTP request | | flushInterval | number | 2000 | Milliseconds between background flushes (0 = timer disabled) | | beforeSend | function | — | Hook called for every event before queueing. Return a modified event or null to drop. | | sendDefaultPii | boolean | false | When false, query strings and URL fragments are stripped before being attached to events | | sampleRate | number | 1.0 | Fraction of events sent (0.0–1.0). Useful for high-volume apps. | | maxQueueSize | number | 256 | Hard cap on the in-memory queue. New events are dropped when the queue is full. |

Scrubbing PII

By default ErrSight strips the query string and fragment from window.location.href so secrets like reset tokens, OAuth state, and email addresses in URLs don't leave the browser. To scrub additional fields (request bodies, breadcrumb data, user identifiers) use beforeSend:

Errsight.init({
  apiKey: "elp_your_api_key",
  beforeSend(event) {
    if (event.user?.email) event.user.email = "[redacted]";
    if (event.message.includes("password")) return null;
    return event;
  },
});

Usage

Log a message

import { getClient } from "errsight";

const logger = getClient();

logger.debug("Fetching user profile");
logger.info("User signed in");
logger.warn("Slow API response", { metadata: { duration_ms: 3200 } });
logger.error("Checkout failed");
logger.fatal("Database connection lost");

Capture an Error object

try {
  await processPayment(cart);
} catch (err) {
  logger.captureError(err, { metadata: { cart_id: cart.id } });
}

captureError (and its alias captureException) fills in the stack trace automatically and sets the level to error. It safely handles non-Error throws like throw "string" or throw { code: 404 }.

Identify a user

logger.setUser({ id: 42, email: "[email protected]" });
// ...
logger.clearUser();

Flush and shut down

Events are flushed automatically on visibilitychange and pagehide. To flush explicitly:

logger.flush();

To tear down the client completely (removes global handlers, clears the flush timer, drains the queue):

logger.destroy();

destroy() is called automatically when init() is invoked a second time, so React Strict Mode double-invocations and HMR reloads do not leak event listeners.

React integration

Import from errsight/react:

import { ErrsightProvider, useErrsight, ErrorBoundary } from "errsight/react";

1. Wrap your app with ErrsightProvider

import Errsight from "errsight";
import { ErrsightProvider } from "errsight/react";

Errsight.init({ apiKey: "elp_your_api_key" });

function Root() {
  return (
    <ErrsightProvider>
      <App />
    </ErrsightProvider>
  );
}

2. Log from any component with useErrsight

function CheckoutButton({ cart }) {
  const logger = useErrsight();

  async function handleClick() {
    try {
      await submitOrder(cart);
      logger.info("Order submitted", { metadata: { cart_id: cart.id } });
    } catch (err) {
      logger.captureError(err, { metadata: { cart_id: cart.id } });
    }
  }

  return <button onClick={handleClick}>Buy now</button>;
}

3. Catch render errors with ErrorBoundary

<ErrorBoundary fallback={({ error, reset }) => (
  <div>
    <p>{error.message}</p>
    <button onClick={reset}>Try again</button>
  </div>
)}>
  <Dashboard />
</ErrorBoundary>

ErrorBoundary calls captureError automatically and passes the React component stack as metadata.

How it works

Events are queued in memory and flushed to POST /api/v1/events in batches. Flushes are triggered by:

1. A background timer (every flushInterval ms).
2. The queue reaching batchSize.
3. The page becoming hidden (visibilitychange) or unloading (pagehide).
4. An explicit flush() or destroy() call.

Requests use fetch with keepalive: true so in-flight POSTs survive page unloads. The SDK retries once on 5xx and network errors (2 second delay), and honours Retry-After on 429 responses. The in-memory queue is capped at maxQueueSize events so a runaway error loop in a customer app cannot saturate the browser.

Every event automatically includes url, user_agent, and platform: "javascript" from the browser context. URLs are stripped of query string and fragment by default — set sendDefaultPii: true to include them.

Bundle size

The browser bundle (errsight.browser.min.js) is ~2.6 KB gzipped.

License

MIT