@multiplayer-app/session-recorder-react 1.2.25 → 1.2.26

package/README.md

@@ -270,6 +270,74 @@ The options passed to `SessionRecorder.init(...)` are forwarded to the underlyin
 
 Any time `recordNavigation` is enabled, the browser SDK will emit OpenTelemetry navigation spans and keep an in-memory stack of visited routes. You can access the navigation helpers through `SessionRecorder.navigation` if you need to introspect from React components.
 
+## Capturing exceptions in React apps
+
+The browser SDK auto‑captures uncaught errors and unhandled promise rejections. In React apps you’ll typically also want an Error Boundary to catch render errors and report them. This package ships a ready‑to‑use boundary and also shows how to wire React 18/19 root error callbacks.
+
+### Using the built‑in error boundary
+
+```tsx
+import React from 'react'
+import { ErrorBoundary } from '@multiplayer-app/session-recorder-react'
+
+export function AppWithBoundary() {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong</div>}>
+      <App />
+    </ErrorBoundary>
+  )
+}
+```
+
+The boundary calls `SessionRecorder.captureException(error)` internally and renders the provided `fallback` on error.
+
+### Custom boundary (if you need full control)
+
+```tsx
+import React from 'react'
+import SessionRecorder from '@multiplayer-app/session-recorder-react'
+
+class MyErrorBoundary extends React.Component<{ children: React.ReactNode }, { hasError: boolean }> {
+  state = { hasError: false }
+  static getDerivedStateFromError() {
+    return { hasError: true }
+  }
+  componentDidCatch(error: unknown) {
+    SessionRecorder.captureException(error as any)
+  }
+  render() {
+    return this.state.hasError ? <h1>Oops.</h1> : this.props.children
+  }
+}
+```
+
+### React 18/19 root error hooks
+
+React surfaces recoverable runtime errors via the root option `onRecoverableError`. You can forward these to the session recorder as well. This works in React 18 and React 19.
+
+```tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import SessionRecorder from '@multiplayer-app/session-recorder-react'
+import App from './App'
+
+SessionRecorder.init({
+  /* ... your config ... */
+})
+
+ReactDOM.createRoot(document.getElementById('root')!, {
+  onRecoverableError(error) {
+    SessionRecorder.captureException(error as any)
+  }
+}).render(<App />)
+```
+
+Notes:
+
+- Uncaught errors and unhandled rejections are captured automatically by the browser SDK.
+- Error Boundary + `onRecoverableError` covers both render and runtime recoverable errors.
+- In Continuous mode, any captured exception marks the trace as ERROR and auto‑saves the rolling session window.
+
 ## Next.js integration tips
 
 - Initialize the provider in a Client Component (for example `app/providers.tsx`) because the browser SDK requires `window`.

package/dist/ErrorBoundary.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export type ErrorBoundaryProps = {
+    children: React.ReactNode;
+    /** Optional fallback UI to render when an error is caught */
+    fallback?: React.ReactNode;
+};
+type State = {
+    hasError: boolean;
+};
+export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, State> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: unknown): void;
+    render(): React.ReactNode;
+}
+export default ErrorBoundary;
+//# sourceMappingURL=ErrorBoundary.d.ts.map

package/dist/ErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../src/ErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B,CAAA;AAED,KAAK,KAAK,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAA;AAElC,qBAAa,aAAc,SAAQ,KAAK,CAAC,SAAS,CAAC,kBAAkB,EAAE,KAAK,CAAC;gBAC/D,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB,IAAI,KAAK;IAIxC,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAQvC,MAAM,IAAI,KAAK,CAAC,SAAS;CAM1B;AAED,eAAe,aAAa,CAAA"}

package/dist/ErrorBoundary.js

@@ -0,0 +1,27 @@
+import React from 'react';
+import SessionRecorder from '@multiplayer-app/session-recorder-browser';
+export class ErrorBoundary extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false };
+    }
+    static getDerivedStateFromError() {
+        return { hasError: true };
+    }
+    componentDidCatch(error) {
+        try {
+            SessionRecorder.captureException(error);
+        }
+        catch (_e) {
+            // no-op
+        }
+    }
+    render() {
+        if (this.state.hasError) {
+            return this.props.fallback ?? null;
+        }
+        return this.props.children;
+    }
+}
+export default ErrorBoundary;
+//# sourceMappingURL=ErrorBoundary.js.map

package/dist/ErrorBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.js","sourceRoot":"","sources":["../src/ErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AACzB,OAAO,eAAe,MAAM,2CAA2C,CAAA;AAUvE,MAAM,OAAO,aAAc,SAAQ,KAAK,CAAC,SAAoC;IAC3E,YAAY,KAAyB;QACnC,KAAK,CAAC,KAAK,CAAC,CAAA;QACZ,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;IAClC,CAAC;IAED,MAAM,CAAC,wBAAwB;QAC7B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;IAC3B,CAAC;IAED,iBAAiB,CAAC,KAAc;QAC9B,IAAI,CAAC;YACH,eAAe,CAAC,gBAAgB,CAAC,KAAY,CAAC,CAAA;QAChD,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC;YACZ,QAAQ;QACV,CAAC;IACH,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAA;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC5B,CAAC;CACF;AAED,eAAe,aAAa,CAAA"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from '@multiplayer-app/session-recorder-browser';
 export { default } from '@multiplayer-app/session-recorder-browser';
 export * from './context/SessionRecorderContext';
 export * from './context/useSessionRecorderStore';
+export { ErrorBoundary } from './ErrorBoundary';
 export { useNavigationRecorder } from './navigation';
 export type { UseNavigationRecorderOptions } from './navigation';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,2CAA2C,CAAC;AAEpE,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,YAAY,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,2CAA2C,CAAC;AAEpE,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,YAAY,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -2,5 +2,6 @@ export * from '@multiplayer-app/session-recorder-browser';
 export { default } from '@multiplayer-app/session-recorder-browser';
 export * from './context/SessionRecorderContext';
 export * from './context/useSessionRecorderStore';
+export { ErrorBoundary } from './ErrorBoundary';
 export { useNavigationRecorder } from './navigation';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,2CAA2C,CAAC;AAEpE,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,2CAA2C,CAAC;AAEpE,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplayer-app/session-recorder-react",
-  "version": "1.2.25",
+  "version": "1.2.26",
   "description": "Multiplayer Fullstack Session Recorder for React (browser wrapper)",
   "author": {
     "name": "Multiplayer Software, Inc.",
@@ -35,8 +35,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "dependencies": {
-    "@multiplayer-app/session-recorder-browser": "1.2.25",
-    "@multiplayer-app/session-recorder-common": "1.2.25"
+    "@multiplayer-app/session-recorder-browser": "1.2.26",
+    "@multiplayer-app/session-recorder-common": "1.2.26"
   },
   "devDependencies": {
     "eslint": "8.48.0",

package/src/ErrorBoundary.tsx

@@ -0,0 +1,38 @@
+import React from 'react'
+import SessionRecorder from '@multiplayer-app/session-recorder-browser'
+
+export type ErrorBoundaryProps = {
+  children: React.ReactNode
+  /** Optional fallback UI to render when an error is caught */
+  fallback?: React.ReactNode
+}
+
+type State = { hasError: boolean }
+
+export class ErrorBoundary extends React.Component<ErrorBoundaryProps, State> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true }
+  }
+
+  componentDidCatch(error: unknown): void {
+    try {
+      SessionRecorder.captureException(error as any)
+    } catch (_e) {
+      // no-op
+    }
+  }
+
+  render(): React.ReactNode {
+    if (this.state.hasError) {
+      return this.props.fallback ?? null
+    }
+    return this.props.children
+  }
+}
+
+export default ErrorBoundary

package/src/index.ts

@@ -3,6 +3,6 @@ export { default } from '@multiplayer-app/session-recorder-browser';
 
 export * from './context/SessionRecorderContext';
 export * from './context/useSessionRecorderStore';
-
+export { ErrorBoundary } from './ErrorBoundary'
 export { useNavigationRecorder } from './navigation'
 export type { UseNavigationRecorderOptions } from './navigation'