@bugwalk/browser

Browser SDK for Bugwalk. Records page views, clicks, network requests, and uncaught errors, and ties them to a person so you can replay what they actually did before something broke.

If you use React, Vue, Svelte, Angular, Next.js, or Nuxt, install the adapter for your framework instead — it wraps this package and hooks the framework's own error handling.

Install

npm install @bugwalk/browser

Use

import { init, identify, capture } from '@bugwalk/browser';

init({ dsn: import.meta.env.VITE_BUGWALK_DSN });

// once you know who is signed in
identify({ id: user.id, email: user.email });

// anything the automatic capture cannot infer
capture('checkout_failed', { orderId });

Call init as early as possible, before your app mounts. On the server it returns undefined and does nothing, so no typeof window guard is needed.

Without a build step

<script src="https://cdn.bugwalk.app/v1/browser.min.js"></script>
<script>
  Bugwalk.init({ dsn: 'hs_pub_...' });
</script>

Same code as the npm package, 6.8 kB gzipped.

What is captured automatically

| | | | --- | --- | | Page views and navigation | Including pushState routing, so single-page apps work | | Clicks | On buttons, links, and anything with a click role, with the element's visible label | | fetch and XMLHttpRequest | Method, URL, status, and duration | | Uncaught errors | window.onerror and unhandledrejection, with parsed stack frames |

Each of these can be turned off: init({ dsn, captureClicks: false }).

Joining the frontend to the backend

Same-origin requests get a W3C traceparent header and an x-bugwalk-session header. Your backend SDK reads both, which is what puts a failed API call and the click that caused it on one timeline.

To instrument a separate API origin, list it and allow the two headers in that server's CORS configuration:

init({ dsn, tracePropagationTargets: ['https://api.example.com'] });

Passing tracePropagationTargets replaces the same-origin default, so include your own origin if you want both.

Redaction

Authorization headers, cookies, password-like keys, card numbers, and tokens are stripped inside the browser, before anything is sent. See the redaction rules.

For anything specific to your app:

init({
  dsn,
  beforeSend(event) {
    if (event.payload?.url?.includes('/internal/')) return null; // drop it
    return event;
  },
});

Session handling

A session lasts until 30 minutes of inactivity. Call resetSession() on logout so the next person to use the browser gets their own journey.

API

| Function | Purpose | | --- | --- | | init(options) | Start recording. Safe to call more than once. | | identify(person) | Attach an id or email to everything from here on. | | capture(name, payload?) | Record a custom event. | | captureError(error) | Record an error you already caught. | | flush() | Send what is buffered and wait for it. | | resetSession() | End the visit and start a new one. | | shutdown() | Stop recording and remove every listener. |

Apache-2.0