@multiplayer-app/session-recorder-react 1.2.27 → 1.2.28

package/README.md

@@ -302,8 +302,8 @@ class MyErrorBoundary extends React.Component<{ children: React.ReactNode }, { h
   static getDerivedStateFromError() {
     return { hasError: true }
   }
-  componentDidCatch(error: unknown) {
-    SessionRecorder.captureException(error as any)
+  componentDidCatch(error: unknown, errorInfo?: Record<string, any>) {
+    SessionRecorder.captureException(error as any, errorInfo)
   }
   render() {
     return this.state.hasError ? <h1>Oops.</h1> : this.props.children
@@ -313,7 +313,7 @@ class MyErrorBoundary extends React.Component<{ children: React.ReactNode }, { h
 
 ### 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.
+React 19 adds `onUncaughtError` and `onCaughtError` to `createRoot` options (along with `onRecoverableError` that exists in 18/19). You can wire all three to `SessionRecorder.captureException` similar to Sentry’s handler:
 
 ```tsx
 import React from 'react'
@@ -325,18 +325,31 @@ SessionRecorder.init({
   /* ... your config ... */
 })
 
-ReactDOM.createRoot(document.getElementById('root')!, {
+const container = document.getElementById('root')!
+
+const root = ReactDOM.createRoot(container, {
+  // React 19: thrown and not caught by an Error Boundary
+  onUncaughtError(error, errorInfo) {
+    SessionRecorder.captureException(error, { componentStack: errorInfo?.componentStack })
+  },
+  // React 19: caught by an Error Boundary
+  onCaughtError(error, errorInfo) {
+    SessionRecorder.captureException(error, { componentStack: errorInfo?.componentStack })
+  },
+  // React 18/19: recoverable runtime errors
   onRecoverableError(error) {
-    SessionRecorder.captureException(error as any)
+    SessionRecorder.captureException(error)
   }
-}).render(<App />)
+})
+
+root.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.
+- Uncaught errors and unhandled promise rejections are captured automatically by the SDK.
+- Error Boundary + root callbacks give the richest context (component stack via `errorInfo.componentStack`).
+- In Continuous mode, captured exceptions set span status ERROR and auto‑save the rolling session window.
 
 ## Next.js integration tips
 
@@ -344,11 +357,58 @@ Notes:
 - In the App Router, render the `SessionRecorderProvider` at the top of `app/layout.tsx` and add the `NavigationTracker` component inside your root layout so every route change is captured.
 - If your frontend calls APIs on different origins, set `propagateTraceHeaderCorsUrls` so backend traces correlate correctly.
 
-### Next.js support (coming soon) and temporary solution
+### Next.js 15.3+ (App Router) — instrumentation-client.ts
+
+Next.js 15.3+ adds client-side instrumentation via `src/instrumentation-client.ts`, which runs before hydration. Initialize the recorder at top-level and optionally export `onRouterTransitionStart` for navigation tracking. See the official docs: [instrumentation-client.ts](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation-client).
+
+1. Create `src/instrumentation-client.ts`:
+
+```ts
+import SessionRecorder from '@multiplayer-app/session-recorder-react'
+
+// Initialize as early as possible (before hydration)
+try {
+  SessionRecorder.init({
+    application: 'my-next-app',
+    version: '1.0.0',
+    environment: process.env.NEXT_PUBLIC_ENVIRONMENT ?? 'production',
+    apiKey: process.env.NEXT_PUBLIC_MULTIPLAYER_API_KEY!,
+    showWidget: true,
+    // If your APIs are on different origins, add them so OTLP headers are propagated
+    // format: string | RegExp | Array
+    propagateTraceHeaderCorsUrls: [new RegExp('https://api.example.com', 'i')]
+  })
+} catch (error) {
+  // Keep instrumentation resilient
+  console.warn('[SessionRecorder] init failed in instrumentation-client:', error)
+}
+
+// Optional: Next.js will call this when navigation begins
+export function onRouterTransitionStart(url: string, navigationType: 'push' | 'replace' | 'traverse') {
+  try {
+    SessionRecorder.navigation.record({
+      path: url || '/',
+      navigationType,
+      framework: 'nextjs',
+      source: 'instrumentation-client'
+    })
+  } catch (error) {
+    console.warn('[SessionRecorder] navigation record failed:', error)
+  }
+}
+```
+
+Notes:
+
+- Use `NEXT_PUBLIC_` environment variables for values needed on the client (e.g. `NEXT_PUBLIC_MULTIPLAYER_API_KEY`).
+- `instrumentation-client.ts` ensures initialization happens before your UI mounts; the provider is still required to wire React context and hooks.
+- You can rely on `onRouterTransitionStart` for navigation tracking in Next.js 15.3+, or use the `NavigationTracker` client component as shown below.
+
+### Next.js < 15.3
 
 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 (Recommended)
+1. Initializing in a Client Component
 
 ```tsx
 'use client'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplayer-app/session-recorder-react",
-  "version": "1.2.27",
+  "version": "1.2.28",
   "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.27",
-    "@multiplayer-app/session-recorder-common": "1.2.27"
+    "@multiplayer-app/session-recorder-browser": "1.2.28",
+    "@multiplayer-app/session-recorder-common": "1.2.28"
   },
   "devDependencies": {
     "eslint": "8.48.0",