@upgoose/browser

Lightweight error tracking SDK for browser applications. Captures unhandled exceptions, promise rejections, and manual error reports — with breadcrumbs, PII scrubbing, and zero dependencies.

Install

npm install @upgoose/browser

Quick start

import upgoose from '@upgoose/browser';

upgoose.init({
  dsn: 'https://[email protected]/<PROJECT_ID>',
  environment: 'production',
});

Errors are captured automatically. That's it.

dsn supplies apiKey and apiUrl in one value — or pass them separately if you prefer. release is optional: if you use @upgoose/vite-plugin, it injects the build's release automatically so symbolicated stack traces line up with your uploaded source maps. Otherwise set it yourself:

upgoose.init({
  apiKey: 'ug_...',
  apiUrl: 'https://api.upgoose.app',
  release: '1.2.3',          // match the release your source maps were uploaded under
});

Manual capture

// Capture an exception
try {
  riskyOperation();
} catch (err) {
  upgoose.captureException(err);
}

// Capture a message
upgoose.captureMessage("Payment flow failed", "warning");

User context

upgoose.setUser({ id: '123', email: '[email protected]' });

Tags

upgoose.setTag('team', 'checkout');

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | dsn | string | — | https://<API_KEY>@api.upgoose.app/<PROJECT_ID> — supplies apiKey + apiUrl. Provide this or apiKey + apiUrl. | | apiKey | string | required if no dsn | API key from your project DSN | | apiUrl | string | required if no dsn | Upgoose API base URL | | environment | string | — | e.g. 'production', 'staging' | | release | string | injected by the Vite plugin | App version or git SHA | | sampleRate | number | 1 | 0–1, fraction of events to capture | | maxBreadcrumbs | number | 50 | Max breadcrumbs retained | | beforeSend | function | — | Transform or drop events before send | | captureConsole | boolean | true | Log console.error/warn as breadcrumbs | | captureClicks | boolean | true | Log click events as breadcrumbs | | captureNavigation | boolean | true | Log route changes as breadcrumbs | | captureNetwork | boolean | true | Log fetch/XHR as breadcrumbs | | captureUnhandled | boolean | true | Global error + rejection handlers | | captureCSP | boolean | false | Capture CSP violations as warning events |

CSP violation reporting

Enable captureCSP to capture Content-Security-Policy violations as warning-level events:

upgoose.init({
  apiKey: '...',
  apiUrl: '...',
  captureCSP: true,
});

Each violation is fingerprinted by directive + blocked origin (e.g. script-src from https://evil.com), so repeated violations from the same source are grouped together instead of flooding your error list.

Events include tags for filtering: csp.directive, csp.disposition (enforce vs report-only), and csp.blocked_origin. Violations also appear as breadcrumbs in the trail for subsequent errors.

This is opt-in because browser extensions can generate noise. Use beforeSend to filter out known false positives:

upgoose.init({
  apiKey: '...',
  apiUrl: '...',
  captureCSP: true,
  beforeSend(event) {
    // Ignore violations from browser extensions
    if (event.tags?.['csp.blocked_origin']?.includes('extension://')) return null;
    return event;
  },
});

What gets captured

• Unhandled exceptions (window.onerror)
• Unhandled promise rejections
• CSP violations (opt-in via captureCSP)
• Breadcrumbs: clicks, navigation, console, fetch/XHR, CSP (with timing)
• Browser context: user agent, viewport, language
• Page URL (sensitive query params automatically redacted)

What doesn't get sent

• No cookies, localStorage, or session data
• No DOM snapshots or session replay
• No performance traces
• Sensitive URL params (token, key, secret, password, auth, session, jwt) are redacted before leaving the browser

Filtering events

upgoose.init({
  apiKey: '...',
  apiUrl: '...',
  beforeSend(event) {
    // Drop events from browser extensions
    if (event.stack?.includes('chrome-extension://')) return null;
    // Redact custom fields
    delete event.context?.sensitiveField;
    return event;
  },
});

Bundle size

~3 KB gzipped. Zero dependencies.

Documentation

Full integration guide: upgoose.app/docs

Switching from another error tracking tool? Upgoose accepts standard error event payloads — migration guide

License

BSD-3-Clause