Browser SDK
Capture frontend errors, user activity, and session replay.
Watch the Browser SDK video
A 2:43 walkthrough of this guide’s documented setup, examples, and SDK options. Includes the documented test error and a moving, privacy-masked session replay. British male narration and captions are included.
Jump to a chapter
Read the video transcript
Install and initialize
Install the Browser SDK with the command shown in the guide. Import Reelay in main dot T S, then call init once before your app renders. For Cloud, use the HTTPS API endpoint shown here; for Enterprise, use your Agent’s HTTPS URL. Pass your node ID and ingest key from the dashboard. These are the same configuration fields and placeholders as the documentation.
Capture and verify errors
Uncaught errors and unhandled promise rejections are captured automatically, along with click, navigation, console, and fetch breadcrumbs. For a caught error, use the guide’s save Order example: call capture Exception in the catch block. Capture Message reports a message as a synthetic error event. To verify setup, throw the documented Reelay test error in staging, then check Errors in the dashboard.
Session replay and privacy
Replay keeps the last thirty to sixty seconds of activity in memory and uploads a clip only when an error occurs. Here is the recorded activity for the documented test error. The replay moves through the Browser guide, with page text masked. Input values and page text are masked by default. Replay is enabled by default; set replay to false to disable it.
Built-in scrubbing redacts common secrets. Review what your application puts in URLs, logs, breadcrumbs, and the DOM, and add scrub Patterns for your own secret formats. Before Send can inspect or drop an event; return null to drop it. Error sample rate defaults to one. Performance sampling defaults to zero, so set traces Sample Rate above zero for Web Vitals and page-load transactions.
Backend links and source maps
Allowed fetch requests receive a Reelay session ID header. A positive trace sample rate also adds traceparent. Same-origin requests are allowed by default. For a separate API origin, use the documented trace Propagation Targets list and allow both headers in your API’s CORS configuration. This list replaces the default: include window location origin explicitly, and never add third-party origins.
For production source maps, generate maps during the build and inject debug IDs before deploying the bundles. The guide shows this inject command. Uploads need authentication supported by your deployment, and private maps should stay off a public CDN. Check the documented Enterprise uploader compatibility note. The API reference also covers custom breadcrumbs, reading the session ID, flushing pending events, and uninstalling listeners.
Install
Install the package, then call init once before your app renders. Use https://api.usereelay.com as the endpoint for Cloud, or your Enterprise Agent's HTTPS URL.
npm install @usereelay/browserimport * as Reelay from "@usereelay/browser";
Reelay.init({ endpoint: "https://api.usereelay.com", nodeId: "<your-node-id>", ingestKey: "<your-ingest-key>",});Verify it works
Throw a test error in staging, then check Errors in the dashboard.
setTimeout(() => { throw new Error("Reelay test"); }, 0);What gets captured
- Uncaught errors and unhandled promise rejections.
- Click, navigation, console, and fetch breadcrumbs.
- Session replay (masked by default, shipped only when an error occurs).
- Web Vitals and page-load transactions, only when tracesSampleRate is set above 0.
Report a caught error
try { await saveOrder();} catch (error) { Reelay.captureException(error);}
Reelay.captureMessage("Checkout used the fallback path");Link to your backend
The SDK adds a reelay-session-id header to allowed fetch requests so backend errors link to the browser session. When tracesSampleRate is above 0, a W3C traceparent header is added too. Same-origin requests are allowed by default. For a separate API origin, list it in tracePropagationTargets and allow both headers in the API's CORS config.
Reelay.init({ endpoint: "https://api.usereelay.com", nodeId: "<your-node-id>", ingestKey: "<your-ingest-key>", tracePropagationTargets: [ window.location.origin, "https://api.example.com", ],});Options
| Option | Use |
|---|---|
| endpoint | HTTPS ingest URL. Required. |
| nodeId, ingestKey | Node credentials from the dashboard. Required by the backend. |
| release, commitSha | Deployed version and full Git SHA. Embed at build time. |
| sampleRate | Fraction of errors to send (0–1). Default: 1. |
| beforeSend | Inspect or drop an event before sending. Return null to drop. |
| scrubPatterns, redactedFields | Extra regexes and field names to redact. |
| replay | Error-buffered session replay. Default: true. |
| maskAllText | Mask page text in replay. Default: true. |
| tracePropagationTargets | Origins allowed to receive trace headers. |
| tracesSampleRate | Performance sampling (0–1). Default: 0 (off). |
| profiling | JS self-profiling. Chromium only. Default: false. |
| debug | Diagnostic callback. |
Replay and privacy
Replay keeps the last 30–60 seconds of activity in memory and uploads a clip only when an error occurs. Input values and page text are masked by default. Set replay: false to disable.
Built-in scrubbing redacts common secrets, but review what your app puts in URLs, logs, breadcrumbs, and the DOM. Add scrubPatterns for your own secret formats.
Example project
A complete Browser integration is available in the example workbench.
Production source maps
Minified browser stacks point at generated bundles. Source maps let a compatible ingestion and symbolication workflow recover original filenames and line numbers. Generate maps during your build and inject debug IDs into the bundles before deploying them.
The SDK includes the reelay-sourcemaps tool. Its inject command updates the local artifacts; an upload step must use the endpoint and authentication supported by your deployment. Keep private source maps off a public CDN when they contain source you do not want to publish.
npx reelay-sourcemaps inject ./distSDK API reference
| Function or method | Purpose |
|---|---|
| init(options) | Initialize the client and listeners. Later calls reuse the client. |
| getClient() | Return the active BrowserClient, or undefined before initialization. |
| captureException(error) | Report a handled exception; returns its event ID or an empty string if dropped. |
| captureMessage(message) | Report a message as a synthetic error event. |
| client.sessionId | Read the current browser session identifier. |
| client.addBreadcrumb(crumb) | Add a custom, scrubbed breadcrumb to the recent-activity buffer. |
| client.flush() | Drain the pending event queue. Returns a promise. |
| client.uninstall() | Remove listeners and restore wrapped browser functions. |