Sentry React Sdk

# Error Monitoring — Sentry React SDK

> Minimum SDK: `@sentry/react` ≥8.0.0+  
> `captureReactException()` requires `@sentry/react` ≥9.8.0  
> `reactErrorHandler()` requires `@sentry/react` ≥8.6.0

---

## How Automatic Capture Works

The React SDK hooks into the browser environment and captures errors automatically from multiple layers:

| Layer | Mechanism | Integration |
|-------|-----------|-------------|
| Uncaught JS exceptions | `window.onerror` | `GlobalHandlers` (default on) |
| Unhandled promise rejections | `window.onunhandledrejection` | `GlobalHandlers` (default on) |
| Errors in `setTimeout` / `setInterval` / `requestAnimationFrame` | Patched browser APIs | `BrowserApiErrors` (default on) |
| React render errors (React <19) | `componentDidCatch` via `<ErrorBoundary>` | `Sentry.ErrorBoundary` |
| React render errors (React 19+) | `createRoot` hooks | `Sentry.reactErrorHandler()` |
| Console errors (optional) | Patched `console.error` | `CaptureConsole` (opt-in) |

### What Requires Manual Instrumentation

The global handlers only catch errors that **escape** your code. These are silently swallowed without manual calls:

- Errors caught by your own `try/catch` blocks
- Errors swallowed by React Router's default error boundary
- Business-logic failures (validation errors, unexpected states)
- Async errors inside `Promise.then()` chains where `.catch()` is attached
- User-visible conditions that aren't exceptions (use `captureMessage`)

### Disabling or Customizing Automatic Capture

```javascript
Sentry.init({
  integrations: [
    Sentry.globalHandlersIntegration({
      onerror: true,
      onunhandledrejection: false,  // handle rejections manually
    }),
  ],
});

// Manual rejection handler:
window.addEventListener("unhandledrejection", (event) => {
  Sentry.captureException(event.reason);
});
```

---

## React Error Boundaries

### Strategy: React 19+ vs. React ≤18

| | React ≤18 | React 19+ |
|---|---|---|
| **Global error reporting** | `window.onerror` + `Sentry.ErrorBoundary` | `Sentry.reactErrorHandler()` on `createRoot` |
| **Scoped fallback UI** | `<Sentry.ErrorBoundary>` | `<Sentry.ErrorBoundary>` (still required) |
| **Complementary?** | N/A | ✅ Use both together |

---

### React 19+ — `Sentry.reactErrorHandler()` with `createRoot`

React 19 exposes three hooks on `createRoot` and `hydrateRoot`. Pass `Sentry.reactErrorHandler()` to each one. Requires `@sentry/react` ≥8.6.0.

```jsx
// src/main.tsx
import { createRoot } from "react-dom/client";
import * as Sentry from "@sentry/react";

Sentry.init({ dsn: "___PUBLIC_DSN___" });

const container = document.getElementById("app")!;

createRoot(container, {
  // Fires for errors that bubble up WITHOUT any ErrorBoundary catching them.
  // These are fatal — the entire React tree unmounts.
  onUncaughtError: Sentry.reactErrorHandler((error, errorInfo) => {
    // Optional: runs AFTER Sentry has already captured the error
    console.warn("Uncaught React error:", error.message);
    console.warn("Component stack:", errorInfo.componentStack);
  }),

  // Fires for errors caught BY an ErrorBoundary (React 19 re-routes caught errors here).
  // The boundary still renders its fallback UI — this is just the reporting hook.
  onCaughtError: Sentry.reactErrorHandler(),

  // Fires when React recovers from an error automatically (e.g. hydration mismatch).
  onRecoverableError: Sentry.reactErrorHandler(),
}).render(<App />);
```

**SSR / `hydrateRoot`:**

```jsx
import { hydrateRoot } from "react-dom/client";
import * as Sentry from "@sentry/react";

hydrateRoot(document.getElementById("app")!, <App />, {
  onUncaughtError: Sentry.reactErrorHandler(),
  onCaughtError: Sentry.reactErrorHandler(),
  onRecoverableError: Sentry.reactErrorHandler(),
});
```

**Key behavior differences between the three hooks:**

| Hook | Fires when... | Tree state after |
|------|--------------|-----------------|
| `onUncaughtError` | Error escapes all boundaries | Tree unmounts (fatal)