feat(core): Capture Expo Router ErrorBoundary errors

CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Features
 
+- Capture errors that hit Expo Router's per-route `ErrorBoundary`. Wrap the boundary with `Sentry.wrapRouterErrorBoundary(ErrorBoundary)` in your route file to capture render-phase errors with route context (`route.name`, `route.path`, `route.params`), tag the in-flight navigation transaction as errored, and emit a breadcrumb. Concrete paths and params are gated behind `sendDefaultPii` ([#6160](https://github.com/getsentry/sentry-react-native/issues/6160))
 - Add `nativeStackAndroid` support to `NativeLinkedErrors`, capturing the JVM stack trace of rejected native module promises as a linked exception ([#6278](https://github.com/getsentry/sentry-react-native/pull/6278))
 - Record XHR request/response headers and (optionally) bodies in Mobile Session Replay. Opt in via `mobileReplayIntegration` with `networkDetailAllowUrls` to capture headers; set `networkCaptureBodies: true` to also capture bodies. Other options: `networkDetailDenyUrls`, `networkRequestHeaders`, `networkResponseHeaders`. Authorization-like headers are always stripped, bodies are capped at ~150 KB. Covers XHR-based clients like `axios`; fetch will follow. See [Network Details](https://docs.sentry.io/platforms/react-native/session-replay/#network-details) for details. ([#6288](https://github.com/getsentry/sentry-react-native/pull/6288))
 - Warn during dev builds when multiple versions of Sentry JS SDK are detected ([#6269](https://github.com/getsentry/sentry-react-native/pull/6269))

packages/core/etc/sentry-react-native.api.md

@@ -285,6 +285,14 @@ export interface ExpoRouter {
     replace?: (...args: unknown[]) => void;
 }
 
+// @public
+export interface ExpoRouterErrorBoundaryProps {
+    // (undocumented)
+    error: Error;
+    // (undocumented)
+    retry: () => Promise<void>;
+}
+
 // Warning: (ae-forgotten-export) The symbol "ExpoRouterIntegrationOptions" needs to be exported by the entry point index.d.ts
 //
 // @public
@@ -890,6 +898,9 @@ export function wrapExpoImage<T extends ExpoImage>(imageClass: T): T;
 // @public
 export function wrapExpoRouter<T extends ExpoRouter>(router: T): T;
 
+// @public
+export function wrapRouterErrorBoundary<P extends ExpoRouterErrorBoundaryProps>(OriginalErrorBoundary: React_2.ComponentType<P>): React_2.ComponentType<P>;
+
 // @public
 export function wrapTurboModule<T extends object>(name: string, module: T | null | undefined, options?: {
     skip?: ReadonlyArray<string>;

packages/core/src/js/index.ts

@@ -133,12 +133,13 @@
   createTimeToFullDisplay,
   createTimeToInitialDisplay,
   wrapExpoRouter,
   expoRouterIntegration,
+  wrapRouterErrorBoundary,
   wrapExpoImage,
   wrapExpoAsset,
 } from './tracing';
 
-export type { TimeToDisplayProps, ExpoRouter, ExpoImage, ExpoAsset } from './tracing';
+export type { TimeToDisplayProps, ExpoRouter, ExpoRouterErrorBoundaryProps, ExpoImage, ExpoAsset } from './tracing';
 
 export { Mask, Unmask } from './replay/CustomMask';
 

packages/core/src/js/tracing/expoRouterErrorBoundary.tsx

@@ -0,0 +1,127 @@
+import type { Scope } from '@sentry/core';
+
+import {
+  addBreadcrumb,
+  addExceptionMechanism,
+  captureException,
+  getActiveSpan,
+  getClient,
+  getRootSpan,
+  SPAN_STATUS_ERROR,
+} from '@sentry/core';
+import * as React from 'react';
+
+import { getCurrentExpoRouterRouteInfo } from './expoRouterStore';
+
+/**
+ * The minimal shape of Expo Router's per-route `ErrorBoundary` props.
+ *
+ * We re-declare it here to avoid a hard dependency on `expo-router`.
+ */
+export interface ExpoRouterErrorBoundaryProps {
+  error: Error;
+  retry: () => Promise<void>;
+}
+
+/**
+ * Wraps Expo Router's per-route `ErrorBoundary` so that the SDK captures
+ * errors that hit the boundary instead of relying on the user's global error
+ * handler.
+ *
+ * Expo Router renders the boundary exported from a route file
+ * (`export { ErrorBoundary } from 'expo-router'`) when a component throws
+ * during render. Without this wrapper, Sentry only sees the error if it also
+ * reaches `ErrorUtils` — which it often does not, because React swallows the
+ * error once a boundary handles it.
+ *
+ * For each new `error` instance the wrapper:
+ *  - Captures the error to Sentry with `route.name`, `route.path`, and
+ *    `route.params` attached, gated by `sendDefaultPii` for concrete fields.
+ *  - Tags the active idle navigation span (and its root) with
+ *    `SPAN_STATUS_ERROR` so the navigation transaction reflects the failure.
+ *  - Adds a breadcrumb describing the boundary render.
+ *
+ * @example
+ * ```ts
+ * // app/_layout.tsx\n * import { ErrorBoundary as ExpoErrorBoundary } from 'expo-router';\n * import * as Sentry from '@sentry/react-native';\n *\n * export const ErrorBoundary = Sentry.wrapRouterErrorBoundary(ExpoErrorBoundary);\n * ```\n */
+export function wrapRouterErrorBoundary<P extends ExpoRouterErrorBoundaryProps>(
+  OriginalErrorBoundary: React.ComponentType<P>,
+): React.ComponentType<P> {
+  const Wrapped: React.FC<P> = props => {
+    // Track the last error instance we reported so a re-render with the same
+    // error does not produce a duplicate event. Resets when `retry()` clears
+    // the error and React unmounts the boundary.
+    const reportedErrorRef = React.useRef<unknown>(null);
+
+    if (reportedErrorRef.current !== props.error && props.error) {
+      reportedErrorRef.current = props.error;
+      reportRouterBoundaryError(props.error);
+    }
+
+    return <OriginalErrorBoundary {...props} />;
+  };
+
+  Wrapped.displayName = `wrapRouterErrorBoundary(${
+    OriginalErrorBoundary.displayName || OriginalErrorBoundary.name || 'ErrorBoundary'
+  })`;
+
+  return Wrapped as React.ComponentType<P>;
+}
+
+function reportRouterBoundaryError(error: Error): void {
+  const sendPii = getClient()?.getOptions()?.sendDefaultPii ?? false;
+  const route = getCurrentExpoRouterRouteInfo();
+
+  const templatedPath = route?.templatedPath;
+  // `templatedPath` (e.g. `/users/[id]`) is structural and safe; concrete path
+  // (e.g. `/users/42`) and `params` may contain identifiers and are PII-gated.
+  const routeName = templatedPath ?? 'unknown';
+  const concretePath = sendPii ? (route?.pathnameWithParams ?? route?.pathname) : undefined;
+
+  addBreadcrumb({
+    category: 'expo-router.error_boundary',
+    type: 'error',
+    level: 'error',
+    message: `Expo Router ErrorBoundary rendered for ${routeName}`,
+    data: {
+      'route.name': routeName,
+      ...(concretePath ? { 'route.path': concretePath } : undefined),
+    },
+  });
+
+  markActiveNavigationSpanErrored();
+
+  captureException(error, (scope: Scope) => {
+    scope.setTag('expo_router.error_boundary', 'true');
+    scope.setContext('route', {
+      name: routeName,
+      ...(concretePath ? { path: concretePath } : undefined),
+      ...(sendPii && route?.params ? { params: route.params } : undefined),
+      ...(route?.segments ? { segments: route.segments } : undefined),
+    });
+    scope.addEventProcessor(event => {
+      addExceptionMechanism(event, { type: 'expo_router_error_boundary', handled: true });
+      return event;
+    });
+    return scope;
+  });
+}
+
+/**
+ * If an idle navigation span (or any child) is still open when the boundary
+ * renders, mark its root as errored so the resulting transaction reflects the
+ * navigation failure. Scoped to navigation roots so that a user-started
+ * custom span is not retroactively flipped to errored. No-op otherwise.
+ */
+function markActiveNavigationSpanErrored(): void {
+  const active = getActiveSpan();
+  if (!active) {
+    return;
+  }
+  const root = getRootSpan(active);
+  const origin = (root as { attributes?: Record<string, unknown> })?.attributes?.['sentry.origin'];
+  if (typeof origin !== 'string' || !origin.startsWith('auto.navigation.')) {
+    return;
+  }
+  root.setStatus({ code: SPAN_STATUS_ERROR, message: 'expo_router_error_boundary' });
+}

packages/core/src/js/tracing/expoRouterIntegration.ts

@@ -2,32 +2,19 @@ import type { Client, Integration } from '@sentry/core';
 
 import { debug } from '@sentry/core';
 
+import type { ExpoRouterStore, ExpoRouterUrlObject } from './expoRouterStore';
 import type { RouteOverride } from './reactnavigation';
 
+import { buildExpoRouterTemplatedPath, tryGetExpoRouterStore } from './expoRouterStore';
 import { getReactNavigationIntegration, reactNavigationIntegration } from './reactnavigation';
 
+export { buildExpoRouterTemplatedPath };
+
 export const INTEGRATION_NAME = 'ExpoRouter';
 
 const POLL_INTERVAL_MS = 50;
 const POLL_MAX_DURATION_MS = 5_000;
 
-interface ExpoRouterNavigationRef {
-  current: unknown | null;
-}
-
-interface ExpoRouterUrlObject {
-  unstable_globalHref?: string;
-  pathname?: string;
-  pathnameWithParams?: string;
-  params?: Record<string, unknown>;
-  segments?: string[];
-}
-
-interface ExpoRouterStore {
-  navigationRef?: ExpoRouterNavigationRef;
-  getRouteInfo?: () => ExpoRouterUrlObject;
-}
-
 type ExpoRouterIntegrationOptions = Parameters<typeof reactNavigationIntegration>[0];
 
 /**
@@ -108,34 +95,6 @@ export const expoRouterIntegration = (options: ExpoRouterIntegrationOptions = {}
   };
 };
 
-function tryGetExpoRouterStore(): ExpoRouterStore | null {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const mod = require('expo-router/build/global-state/router-store') as {
-      store?: ExpoRouterStore;
-    };
-    return mod?.store ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Builds a templated pathname from Expo Router's `segments`
- *
- * Examples:
- *   ['(tabs)', 'profile', '[id]']  -> '/profile/[id]'
- *   ['posts', '[...slug]']         -> '/posts/[...slug]'
- *   []                              -> '/'
- */
-export function buildExpoRouterTemplatedPath(segments: string[] | undefined): string {
-  if (!segments || segments.length === 0) {
-    return '/';
-  }
-  const filtered = segments.filter(s => !(s.startsWith('(') && s.endsWith(')')));
-  return filtered.length === 0 ? '/' : `/${filtered.join('/')}`;
-}
-
 function buildExpoRouterRouteOverride(store: ExpoRouterStore): RouteOverride | undefined {
   let info: ExpoRouterUrlObject | undefined;
   try {

packages/core/src/js/tracing/expoRouterStore.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared helpers for reading Expo Router's internal router store.
+ *
+ * Used by:
+ *  - {@link expoRouterIntegration} to attach the current route to the idle
+ *    navigation span via {@link RouteOverride}.
+ *  - {@link wrapRouterErrorBoundary} to attach the current route to errors
+ *    surfaced through Expo Router's per-route `ErrorBoundary`.
+ */
+
+export interface ExpoRouterNavigationRef {
+  current: unknown | null;
+}
+
+export interface ExpoRouterUrlObject {
+  unstable_globalHref?: string;
+  pathname?: string;
+  pathnameWithParams?: string;
+  params?: Record<string, unknown>;
+  segments?: string[];
+}
+
+export interface ExpoRouterStore {
+  navigationRef?: ExpoRouterNavigationRef;
+  getRouteInfo?: () => ExpoRouterUrlObject;
+}
+
+export interface NormalizedExpoRouterRouteInfo {
+  /**
+   * Templated pathname with grouping segments (`(tabs)`) removed. Safe to send
+   * regardless of `sendDefaultPii`. Examples:
+   *   ['(tabs)', 'profile', '[id]'] -> '/profile/[id]'
+   *   ['posts', '[...slug]']        -> '/posts/[...slug]'
+   *   []                            -> '/'
+   */
+  templatedPath: string;
+  /** Concrete pathname (may contain user identifiers). Caller decides PII handling. */
+  pathname?: string;
+  /** Concrete pathname including query/params (may contain PII). */
+  pathnameWithParams?: string;
+  params?: Record<string, unknown>;
+  segments?: string[];
+}
+
+/**
+ * Returns Expo Router's internal router store, or `null` if `expo-router` is
+ * not installed or the build does not expose the expected module path.
+ */
+export function tryGetExpoRouterStore(): ExpoRouterStore | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require('expo-router/build/global-state/router-store') as {
+      store?: ExpoRouterStore;
+    };
+    return mod?.store ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Builds a templated pathname from Expo Router's `segments`. Grouping segments
+ * (e.g. `(tabs)`, `(auth)`) are stripped because they do not appear in the URL.
+ */
+export function buildExpoRouterTemplatedPath(segments: string[] | undefined): string {
+  if (!segments || segments.length === 0) {
+    return '/';
+  }
+  const filtered = segments.filter(s => !(s.startsWith('(') && s.endsWith(')')));
+  return filtered.length === 0 ? '/' : `/${filtered.join('/')}`;
+}
+
+/**
+ * Reads the current route from Expo Router's store and normalizes it. Returns
+ * `undefined` if the store is not reachable or `getRouteInfo` throws.
+ */
+export function getCurrentExpoRouterRouteInfo(): NormalizedExpoRouterRouteInfo | undefined {
+  const store = tryGetExpoRouterStore();
+  if (!store) {
+    return undefined;
+  }
+  let info: ExpoRouterUrlObject | undefined;
+  try {
+    info = store.getRouteInfo?.();
+  } catch {
+    return undefined;
+  }
+  if (!info) {
+    return undefined;
+  }
+  return {
+    templatedPath: buildExpoRouterTemplatedPath(info.segments),
+    pathname: info.pathname,
+    pathnameWithParams: info.pathnameWithParams,
+    params: info.params,
+    segments: info.segments,
+  };
+}

packages/core/src/js/tracing/index.ts

@@ -13,7 +13,10 @@
 export type { ExpoRouter } from './expoRouter';
 
 export { expoRouterIntegration } from './expoRouterIntegration';
 
+export { wrapRouterErrorBoundary } from './expoRouterErrorBoundary';
+export type { ExpoRouterErrorBoundaryProps } from './expoRouterErrorBoundary';
+
 export { wrapExpoImage } from './expoImage';
 export type { ExpoImage } from './expoImage';