@errortracking/browser-sdk

Error tracking SDK for browser apps. Catches uncaught errors and unhandled promise rejections and sends them to your Error Tracker dashboard. With source maps uploaded, errors resolve to your original source instead of minified output.

Install

npm install @errortracking/browser-sdk

Peer dependency: react >=17 is required only if you use the ErrorBoundary component. It is otherwise optional.

Setup

Call init once, as early as possible in your app's entry file:

import { init } from "@errortracking/browser-sdk";

init({
  apiKey: "et_live_your_key_here",
  apiUrl: "https://error-tracking-server.onrender.com",
  release: "1.0.0", // must match the release you upload source maps under
});

What it catches

• Uncaught JavaScript errors (window error events)
• Unhandled promise rejections (window unhandledrejection events)

These cover most runtime errors. They do not cover errors that happen during React rendering -- for those, use ErrorBoundary (see below).

React: ErrorBoundary

React render errors are swallowed by React and never reach window.error. Wrap your app with ErrorBoundary so render-phase errors are also tracked:

import { init } from "@errortracking/browser-sdk";
import { ErrorBoundary } from "@errortracking/browser-sdk/react";

init({
  apiKey: "et_live_your_key_here",
  apiUrl: "https://error-tracking-server.onrender.com",
  release: "1.0.0",
});

export default function Root() {
  return (
    <ErrorBoundary fallback={<p>Something went wrong</p>}>
      <App />
    </ErrorBoundary>
  );
}

ErrorBoundary accepts an optional fallback prop. When a render error occurs, it captures the error (including the React component stack) and renders the fallback. If no fallback is provided it renders <p>Something went wrong</p>.

Manually capturing errors

You can also send errors yourself:

import { captureError } from "@errortracking/browser-sdk";

captureError({
  name: "CustomError",
  message: "Something specific went wrong",
  stackTrace: error.stack,         // optional
  metadata: { userId: "u_123" },   // optional, any extra fields
});

Options

| Option | Required | Default | Description | | --------- | -------- | ----------------------- | ------------------------------------------------- | | apiKey | yes | | Your project API key (et_live_...) | | apiUrl | no | http://localhost:5000 | Your Error Tracker backend URL | | release | no | | Version tag, must match your uploaded source maps |

Seeing your original code (source maps)

Production browser bundles are minified, so raw errors point to something like main.a1b2c3.js:1. To see the real source file and line, do two things:

1. Build with source maps enabled. In Vite:

// vite.config.js
export default {
  build: { sourcemap: true },
};

2. Upload the maps after each build using the CLI, with the same release you passed to init:

npx @errortracking/cli upload --release 1.0.0 ./dist

The release in init() and the --release you upload under must be identical. If they differ, errors arrive but still show minified locations.

Using a script tag (no bundler)

<script type="module">
  import { init } from "https://cdn.jsdelivr.net/npm/@errortracking/browser-sdk/dist/index.js";
  init({
    apiKey: "et_live_your_key_here",
    apiUrl: "https://error-tracking-server.onrender.com",
    release: "1.0.0",
  });
</script>

Notes

• All network calls fire and forget. A send failure never throws into your app.
• captureError is re-entrant safe: if an error occurs inside the send path, the SDK will not recurse.