@drilonhametaj/observer-browser
v0.1.0-alpha.1
Published
Browser SDK for the Observer SDK. Auto-tracks errors, network, clicks, navigation, and behavioural anomalies. Embed in any Next.js host app.
Maintainers
drilonhametajReadme
@drilonhametaj/observer-browser
Browser SDK for the Observer SDK.
Auto-tracks errors, network failures, behavioural anomalies, and console
output in any web app — and ships them to your host's
/api/observer/ingest endpoint with traceId correlation.
Status: alpha. Only safe to use in dev environments.
Install
pnpm add @drilonhametaj/observer-browserRequires react@>=18 if you use the React adapter.
Quickstart (Next.js App Router)
// app/layout.tsx
import { ObserverProvider } from '@drilonhametaj/observer-browser/react'
export default function RootLayout({ children }) {
return (
<html>
<body>
<ObserverProvider
config={{
endpoint: '/api/observer/ingest',
apiKey: process.env.NEXT_PUBLIC_OBSERVER_KEY!,
environment: 'development',
}}
>
{children}
</ObserverProvider>
</body>
</html>
)
}That's it. The SDK now captures:
js_error— uncaught exceptionspromise_rejection— unhandled rejectionshttp— every fetch (withtraceparentheader injected for backend correlation)click— every click, with rage/dead-click detectionconsole—console.warnandconsole.errornavigation— SPA route changes
Manual capture
import { Observer } from '@drilonhametaj/observer-browser'
Observer.captureException(error, { context: 'user-payload-handler' })
Observer.captureMessage('user clicked retry', 'info')
Observer.addBreadcrumb({ category: 'auth', action: 'login.success' })
Observer.setUser({ id: 'u_42', email: '[email protected]', role: 'admin' })Expectations
Track flows that should complete within a window:
Observer.expect('save-cantiere', { within: 5_000 })
try {
await api.saveCantiere(data)
Observer.fulfilled('save-cantiere')
} catch (err) {
Observer.failed('save-cantiere', String(err))
throw err
}If fulfilled doesn't fire within 5s, an expectation_unmet incident
is created server-side.
Error boundary
import { ObserverErrorBoundary } from '@drilonhametaj/observer-browser/react'
<ObserverErrorBoundary boundary="UserDashboard" fallback={<MyErrorUI />}>
<Dashboard />
</ObserverErrorBoundary>Bundle size
Core entry target: <30KB gzipped. rrweb (session replay) is lazy-loaded
only when captureReplay: true is set — so you don't pay for it unless
you use it.
Configuration
| Option | Default | Description |
|---|---|---|
| endpoint | required | Where to POST event batches. Always relative, same origin. |
| apiKey | required | Shared secret with the server. Sent as X-Observer-Key. |
| environment | 'development' | Locked to 'development'; enterprise modes are out of scope. |
| ignoreErrors | [] | Patterns (string or RegExp) — drop matching events before send. |
| beforeSend | null | Mutate or drop events. Return null to drop. |
| captureReplay | false | Enable rrweb session replay (M5). |
License
MIT © Drilon Hametaj