> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arguserror.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Argus Browser SDK: Automatic JavaScript Error Capture

> Install @argusdev/sdk-browser to automatically capture uncaught exceptions and unhandled promise rejections from any web application.

The Argus Browser SDK hooks into two global browser APIs — `window.onerror` and the `unhandledrejection` event — to automatically capture every uncaught exception and unhandled promise rejection in your web application and send it to your Argus project. The SDK has zero runtime dependencies and attaches the current page URL to every event automatically.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @argusdev/sdk-browser
  ```

  ```bash yarn theme={null}
  yarn add @argusdev/sdk-browser
  ```

  ```bash pnpm theme={null}
  pnpm add @argusdev/sdk-browser
  ```
</CodeGroup>

## Initialization

<Steps>
  ### Import and call `init()`

  Call `init()` as early as possible in your application's entry file — before any other logic — so the global error handlers are registered before anything can throw.

  ```typescript theme={null}
  import { init } from '@argusdev/sdk-browser';

  init({
    dsn: 'https://YOUR_PUBLIC_KEY@your-domain.com/YOUR_PROJECT_ID',
    environment: 'production',
    release: '1.0.0',
  });
  ```

  ### Configure `InitOptions`

  `init()` accepts a single `InitOptions` object:

  ```typescript theme={null}
  export interface InitOptions {
    /** Your project DSN (required). Format: https://PUBLIC_KEY@host/PROJECT_ID */
    dsn: string;

    /** The environment name shown in Argus (e.g. 'production', 'staging'). */
    environment?: string;

    /** Your application's release version (e.g. '1.4.2' or a git SHA). */
    release?: string;

    /** Capture web vitals + a page.load transaction per page view (default: true). */
    vitals?: boolean;
  }
  ```

  | Property      | Type      | Required | Description                                                                                                                                         |
  | ------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `dsn`         | `string`  | ✅        | Your Argus project DSN. A malformed DSN throws loudly at startup — fix it before deploying.                                                         |
  | `environment` | `string`  | —        | The deployment environment (e.g. `'production'`, `'staging'`). Shown as a filter in Argus.                                                          |
  | `release`     | `string`  | —        | Your application version or release identifier. Use it to correlate errors with deploys.                                                            |
  | `vitals`      | `boolean` | —        | Web-vitals capture (LCP, CLS, FCP, TTFB) + a `page.load` transaction per page view. **Defaults to `true`**; set `false` to opt out. Requires v0.2+. |
</Steps>

## Web Vitals & Performance (v0.2+)

With `vitals` enabled (the default), the SDK observes **LCP, CLS, FCP, and TTFB** via buffered `PerformanceObserver`s and reports **one `page.load` transaction per page view** when the page is hidden or unloaded — sent with `keepalive` so it survives navigation. See [Performance](/platform/performance) for how the dashboard aggregates this data.

## Manual Capture

Automatic capture handles all uncaught errors, but you can also capture exceptions from inside `try/catch` blocks where you want to handle the error locally and still report it to Argus.

```typescript theme={null}
import { captureException } from '@argusdev/sdk-browser';

async function loadUserProfile(userId: string) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    return await response.json();
  } catch (err) {
    await captureException(err);
    // Handle the error gracefully in the UI — Argus has the full report.
    return null;
  }
}
```

`captureException` normalizes non-`Error` values automatically. If you pass a plain string or object, the SDK wraps it in an `Error` before sending.

## How It Works

When you call `init()`, the SDK saves a reference to any `window.onerror` handler your application already registered, then installs its own. It **chains** rather than replaces — after Argus captures the error, it calls your previous handler and returns its return value. Your existing error reporting is never disrupted.

```typescript theme={null}
// Simplified from init.ts
const previousOnError = window.onerror;
window.onerror = (message, source, lineno, colno, error) => {
  if (error) {
    void captureException(error);
  }
  if (previousOnError) {
    return previousOnError.call(window, message, source, lineno, colno, error);
  }
  return false; // Don't suppress the console error
};
```

Every event sent to Argus automatically includes `request.url` set to `window.location.href` at the moment of the crash — so you always know which page the user was on.

<Note>
  The SDK returns `false` from `window.onerror` intentionally. This preserves the browser's default behavior of logging the error to the DevTools console, so your developers still see uncaught errors during local development.
</Note>

## Cross-Origin Scripts

If your page loads scripts from a different origin (a CDN, a third-party widget, etc.) and those scripts throw, the browser enforces the same-origin policy on error details. Argus captures whatever the browser makes available — typically only the message `"Script error."` with no stack trace and no line number.

To get full stack traces from your own cross-origin scripts, add the `crossorigin="anonymous"` attribute to the `<script>` tag and serve the script with a `Access-Control-Allow-Origin: *` response header. Argus then receives the complete error.

```html theme={null}
<!-- Full stack traces from your own CDN-hosted scripts -->
<script src="https://cdn.example.com/app.js" crossorigin="anonymous"></script>
```

## Exported API

| Symbol             | Kind        | Description                                                                                                                             |
| ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `init`             | `function`  | Initializes the SDK and registers global handlers.                                                                                      |
| `captureException` | `function`  | Manually captures and sends an exception to Argus. Signature: `captureException(err: unknown, extra?: EnvelopeOptions): Promise<void>`. |
| `InitOptions`      | `interface` | TypeScript type for the `init()` options object.                                                                                        |

```typescript theme={null}
import { init, captureException } from '@argusdev/sdk-browser';
import type { InitOptions } from '@argusdev/sdk-browser';
```