@alby-sh/browser

Official Alby error-tracking SDK for web browsers. Tiny (< 10 KB gzipped IIFE), zero runtime dependencies, works with a <script> tag or any bundler.

• Conforms to the Alby Ingest Protocol v1.
• Captures uncaught exceptions (window.onerror) and unhandled promise rejections automatically.
• Auto-breadcrumbs: click, fetch, XMLHttpRequest, console.error/warn, history navigation.
• sendBeacon fallback on page unload so last-second errors aren't lost.
• Retry with exponential backoff (1s / 5s / 15s), respects Retry-After.
• TypeScript types shipped.

Install

npm install @alby-sh/browser

Or drop it on the page directly:

<script src="https://unpkg.com/@alby-sh/browser/dist/alby.iife.js"></script>
<script>
  Alby.init({
    dsn: 'https://<PUBLIC_KEY>@alby.sh/ingest/v1/<APP_ID>',
    release: '1.4.2',
    environment: 'production',
  })
</script>

Usage (npm)

import { Alby } from '@alby-sh/browser'

Alby.init({
  dsn: 'https://<PUBLIC_KEY>@alby.sh/ingest/v1/<APP_ID>',
  release: '1.4.2',
  environment: 'production',
})

// Manual capture
try {
  doSomethingRisky()
} catch (err) {
  Alby.captureException(err)
}

// Scoped metadata
Alby.setUser({ id: 'u_412', email: '[email protected]' })
Alby.setTag('region', 'eu-west-3')
Alby.setContext('app', { route: '/checkout' })
Alby.addBreadcrumb({ category: 'auth', message: 'user signed in' })

// Before navigating away / in SPAs:
await Alby.flush(2000)

API

| Method | Description | |---|---| | Alby.init(options) | Initialize the SDK. Required. | | Alby.captureException(err, overrides?) | Send an exception event. Returns the event_id. | | Alby.captureMessage(msg, level?) | Send a plain message event. | | Alby.setUser({ id, email, name, ip_address }) | Attach a user to every future event. Pass null to clear. | | Alby.setTag(key, value) | Attach a low-cardinality string tag. | | Alby.setContext(key, obj) | Attach free-form context. Pass null to clear. | | Alby.addBreadcrumb({ type, category, message, data }) | Append a breadcrumb (ring buffer, cap 100). | | Alby.flush(timeoutMs?) | Wait for the in-flight queue to drain. |

Options

| Option | Type | Default | Notes | |---|---|---|---| | dsn | string | — | Required. https://<PUBLIC_KEY>@<host>/ingest/v1/<APP_ID> | | release | string | '' | Your app version, e.g. "1.4.2". | | environment | string | "production" | production / staging / dev / etc. | | sampleRate | number | 1 | 0..1 — fraction of events actually sent. | | autoRegister | boolean | true | Install window.onerror, unhandledrejection, auto-breadcrumbs. | | transport | Transport | FetchTransport | For tests / custom transport. | | debug | boolean | false | Log SDK-internal diagnostics to console.error. |

Wire protocol

See PROTOCOL_V1.md for the full schema. In short, the SDK POSTs JSON events to https://<host>/api/ingest/v1/events with an X-Alby-Dsn: <public_key> header, handles 429 Retry-After, and retries 5xx with backoff. Every event carries a client-generated event_id (UUIDv4) so retries are idempotent.

Links

• Website: alby.sh
• Report issues: GitHub Issues
• Other SDKs: alby-sdk-js · alby-sdk-php · alby-sdk-python

License

MIT © 2026 Alby