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

package/README.md

@@ -51,18 +51,18 @@ To get full‑stack session recording working, set up one of our backend SDKs/CL
 
 ## Quick start
 
-1. Wrap your application with the `SessionRecorderProvider`.
-2. Pass the same configuration you would supply to the browser SDK.
+1. Recommended: Call `SessionRecorder.init(options)` before you mount your React app to avoid losing any data.
+2. Wrap your application with the `SessionRecorderProvider`.
 3. Start or stop sessions using the widget or the provided hooks.
 
-### Minimal setup with manual initialization
+### Minimal setup with manual initialization (Recommended)
 
 ```tsx
 // src/main.tsx or src/index.tsx app root
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import App from './App'
-import { SessionRecorderProvider } from '@multiplayer-app/session-recorder-react'
+import SessionRecorder, { SessionRecorderProvider } from '@multiplayer-app/session-recorder-react'
 
 const sessionRecorderConfig = {
   version: '1.0.0',
@@ -77,8 +77,8 @@ const sessionRecorderConfig = {
   propagateTraceHeaderCorsUrls: [new RegExp('https://api.example.com', 'i')]
 }
 
-// Initialize the session recorder manually
-SessionRecorderProvider.init(sessionRecorderConfig)
+// Initialize the session recorder before mounting (Recommended)
+SessionRecorder.init(sessionRecorderConfig)
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <SessionRecorderProvider>
@@ -87,30 +87,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 )
 ```
 
-### Minimal setup with provider initialization
-
-```tsx
-// src/main.tsx or src/index.tsx app root
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import App from './App'
-import { SessionRecorderProvider } from '@multiplayer-app/session-recorder-react'
-
-const sessionRecorderConfig = {
-  version: '1.0.0',
-  environment: 'production',
-  application: 'my-react-app',
-  apiKey: 'YOUR_MULTIPLAYER_API_KEY'
-}
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <SessionRecorderProvider options={sessionRecorderConfig}>
-    <App />
-  </SessionRecorderProvider>
-)
-```
-
-Behind the scenes, the provider initializes the shared Browser SDK (if you pass the configuration as options to the provider) — or you can initialize it manually as shown in the example above. It then sets up listeners and exposes helper APIs through React context and selectors.
+Behind the scenes, the provider sets up listeners and exposes helper APIs through React context and selectors.
 
 ### Set session attributes to provide context for the session
 
@@ -140,16 +117,19 @@ const MyComponent = () => {
 If you prefer not to render our floating widget, disable it and rely purely on the imperative hooks. Use the context hook when you need imperative control (for example, to bind to buttons or QA tooling) as shown in the example below:
 
 ```tsx
-// Provider configuration
-<SessionRecorderProvider
-  options={{
-    application: 'my-react-app',
-    version: '1.0.0',
-    environment: 'production',
-    apiKey: 'YOUR_MULTIPLAYER_API_KEY',
-    showWidget: false // hide the built-in widget
-  }}
->
+import SessionRecorder, { SessionRecorderProvider } from '@multiplayer-app/session-recorder-react'
+
+// Initialize without the built‑in widget
+SessionRecorder.init({
+  application: 'my-react-app',
+  version: '1.0.0',
+  environment: 'production',
+  apiKey: 'YOUR_MULTIPLAYER_API_KEY',
+  showWidget: false // hide the built-in widget
+})
+
+// Wrap your app with the provider to enable hooks/context
+<SessionRecorderProvider>
   <App />
 </SessionRecorderProvider>
 ```
@@ -279,7 +259,7 @@ export function NavigationTrackerLegacy() {
 
 ## Configuration reference
 
-The `options` prop passed to `SessionRecorderProvider` is forwarded to the underlying browser SDK. Refer to the [browser README](../session-recorder-browser/README.md#initialize) for the full option list, including:
+The options passed to `SessionRecorder.init(...)` are forwarded to the underlying browser SDK. Refer to the [browser README](../session-recorder-browser/README.md#initialize) for the full option list, including:
 
 - `application`, `version`, `environment`, `apiKey`
 - `showWidget`, `showContinuousRecording`
@@ -290,6 +270,74 @@ The `options` prop passed to `SessionRecorderProvider` is forwarded to the under
 
 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`.
@@ -300,27 +348,24 @@ Any time `recordNavigation` is enabled, the browser SDK will emit OpenTelemetry
 
 An official Next.js-specific wrapper is coming soon. Until then, you can use this package safely in Next.js by:
 
-1. Initializing in a Client Component
+1. Initializing in a Client Component (Recommended)
 
 ```tsx
 'use client'
 import React from 'react'
-import { SessionRecorderProvider } from '@multiplayer-app/session-recorder-react'
+import SessionRecorder, { SessionRecorderProvider } from '@multiplayer-app/session-recorder-react'
+
+// Initialize before mount to avoid losing any data
+SessionRecorder.init({
+  application: 'my-next-app',
+  version: '1.0.0',
+  environment: 'production',
+  apiKey: 'YOUR_MULTIPLAYER_API_KEY',
+  showWidget: true
+})
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <SessionRecorderProvider
-      options={{
-        application: 'my-next-app',
-        version: '1.0.0',
-        environment: 'production',
-        apiKey: 'YOUR_MULTIPLAYER_API_KEY',
-        showWidget: true
-      }}
-    >
-      {children}
-    </SessionRecorderProvider>
-  )
+  return <SessionRecorderProvider>{children}</SessionRecorderProvider>
 }
 ```
 
@@ -377,7 +422,7 @@ All hooks and helpers ship with TypeScript types. To extend the navigation metad
 ## Troubleshooting
 
 - Ensure the provider wraps your entire component tree so context hooks resolve.
-- Confirm `SessionRecorder.init` runs only once. The provider handles this automatically if you pass the configuration as options to the provider; do not call it manually elsewhere.
+- Confirm `SessionRecorder.init` runs only once and before your app mounts.
 - Ensure the session recorder required options are passed and the API key is valid.
 - For SSR environments, guard any direct `document` or `window` usage behind `typeof window !== 'undefined'` checks (the helper hooks already do this).
 

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.24",
+  "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.24",
-    "@multiplayer-app/session-recorder-common": "1.2.24"
+    "@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'