@hyperdx/browser

@hyperdx/browser is the client-side SDK for HyperDX, an open-source observability platform. A single HyperDX.init({apiKey, service}) call wires up OpenTelemetry-based real user monitoring — instrumenting fetch/XHR calls, console logs, and page visibility as spans — while a bundled rrweb-based session recorder captures DOM mutations for full session replay, all shipped to a configurable OpenTelemetry collector endpoint (HyperDX’s managed ingestion by default, or a self-hosted collector via the url option).

Beyond baseline instrumentation, the SDK exposes tracePropagationTargets to stitch frontend spans to backend traces across API domains, attachToReactErrorBoundary to auto-capture React error-boundary exceptions, and addAction/setGlobalAttributes to tag sessions and events with custom business events and user/team metadata. Masking controls (maskAllInputs, maskAllText, blockClass, blockSelector) let teams keep session replay compliant with sensitive-data policies while still reproducing bugs end to end.

What You Get

• Automatic OpenTelemetry instrumentation of fetch, XHR, console, and page-visibility events as spans/logs
• Session replay recording (via a bundled rrweb-based recorder) with field-level and selector-based masking
• Trace propagation headers to link frontend requests to backend traces across specified API domains
• React error boundary integration that auto-records exceptions with component-stack context
• Runtime toggles for advanced network capture and session recorder start/stop
• Configurable ingestion endpoint for self-hosted HyperDX/OpenTelemetry collector deployments

Common Use Cases

• Correlating a frontend error with the exact session replay and backend trace that produced it
• Linking browser-side page performance to backend API latency via shared trace context
• Reproducing user-reported bugs from replayed sessions with sensitive fields masked
• Tagging custom product events (signup, checkout) for cross-referencing with performance/error data

Under The Hood

Architecture The package is a thin facade class (Browser, exported as a singleton) wrapping two sibling packages from the same monorepo — @hyperdx/otel-web (Rum) for tracing/logging and @hyperdx/otel-web-session-recorder (SessionRecorder) for replay. init() destructures a flat BrowserSDKConfig and passes nearly every field straight through to Rum.init and, unless disableReplay is set, SessionRecorder.init, with a private _advancedNetworkCapture flag mutated at runtime via enableAdvancedNetworkCapture/disableAdvancedNetworkCapture and read through a closure by the fetch/XHR instrumentation. Because config is re-passed nearly verbatim rather than transformed, this is an integration/facade layer rather than an independent subsystem — a shape change in the underlying Rum or SessionRecorder config would ripple straight through.

Tech Stack Written in TypeScript and bundled with Rollup (@rollup/plugin-typescript, -commonjs, -node-resolve, -terser, plus rollup-plugin-re/-visualizer) into a build/index.js + .d.ts pair published under the @hyperdx npm scope. It depends only on two first-party OpenTelemetry-based packages from the same monorepo (@hyperdx/otel-web, @hyperdx/otel-web-session-recorder) and @opentelemetry/api for tracer/span primitives — no UI framework dependency. The monorepo is orchestrated with Yarn workspaces and Nx, versioned/published via Changesets, with Husky + lint-staged pre-commit hooks.

Code Quality A real Jest test suite exists (__tests__/main.test.ts, with its own setup.ts) exercising init, addAction, recordException, and the React error-boundary hook. Error handling favors defensive console.warns over throwing (missing/invalid apiKey) and silently swallows Intercom-hook failures in a bare catch. Naming is consistently camelCase with a well-typed BrowserSDKConfig, though ErrorBoundaryComponent is explicitly aliased to any with a // TODO acknowledging the gap. ESLint + Prettier are configured at the repo root, and CI scripts (ci:lint, ci:unit) pair linting, type-checking, and Jest.

API Design A single default-exported singleton with one primary init() call taking a flat config object keeps the getting-started path to two lines (HyperDX.init({apiKey, service})). Method names map to concepts RUM users already know — addAction, recordException, setGlobalAttributes, getSessionId/getSessionUrl — and runtime toggles read as plain verbs (stopSessionRecorder, enableAdvancedNetworkCapture). The one rough edge is a deprecated captureConsole alias kept alongside consoleCapture, a small decision point left for consumers reading the types.