fix(tracing): Support Expo Router 58 in expoRouterIntegration (#6923)

* fix(tracing): Support Expo Router 58 in expoRouterIntegration

Expo Router 58 removed the internal router-store module and no longer emits
React Navigation's __unsafe_action__ event. Because 58 declares package
exports, Metro printed an invalid package.json warning for the router-store
require on every bundle, and the integration could not start navigation spans.

The navigation container ref now comes from the public
useNavigationContainerRef export, which returns a module-level ref in
Expo Router 57 and 58. Route info is computed from the root navigation state
with getRouteInfoFromState, which both versions ship at the same path.

On Expo Router 58 the integration listens to the internal actionDispatched
event and starts the idle navigation span through a new internal
_startIdleNavigationSpan method on reactNavigationIntegration. Expo Router 57
has no exports field, so the missing internalNavigationEvents path is a silent
optional dependency there and spans still start from __unsafe_action__.

Fixes #6901

* docs: Add the PR number to the Expo Router 58 changelog entry

Replace the placeholder in the CHANGELOG entry with the PR number, #6923.

* fix(tracing): Keep expoRouterIntegration working on Expo Router 55 to 57

Review of #6923 found two regressions for Expo Router versions before 58.

Expo Router 55 and older do not ship getRouteInfoFromState, so the require
threw and the integration stopped as if expo-router were not installed. The
route info module is now optional. Without it, the integration still
registers the navigation container and skips the route override, so spans
use the React Navigation route names.

In Expo Router 56 and 57, useNavigationContainerRef reads a store that stays
empty until the Root Layout renders. The ref was read once at Sentry.init, so
polling timed out and brought back #6431. The store now reads the ref on every
access, and a throwing call returns undefined so it cannot escape the poll
timer.

The #6431 regression test is restored with the new mocks, and new tests cover
a missing getRouteInfoFromState and a throwing useNavigationContainerRef. The
CHANGELOG entry moves back to the Unreleased section after the 8.32.0 release.

* fix(tracing): Start Expo Router 58 spans only for navigation actions

Expo Router 58 emits actionDispatched for every reducer action, not only
user navigations. On a cold launch with tabs it sends ROUTE_NAMES_CHANGED
and one PRELOAD per tab, and router.prefetch() and param updates send more
PRELOAD, ROUTE_NAMES_CHANGED, and SET_PARAMS actions.

expoRouterIntegration does not enable useDispatchedActionData, so
startIdleNavigationSpan did not filter these. Each one started an idle span
that shipped as an empty "Route Change" transaction on the idle timeout.

The listener now forwards only the known navigation action types (NAVIGATE,
PUSH, REPLACE, GO_BACK, POP, POP_TO, POP_TO_TOP, JUMP_TO, RESET). An
allowlist is safer than a denylist because the router 58 reducer also has
internal actions such as REMOVE_ROUTES and NAVIGATOR_CHANGED.

Author: alwx

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Apply `screenshot` masking options to Android error and feedback screenshots ([#6930](https://github.com/getsentry/sentry-react-native/pull/6930))
 - Persist fatal JS error envelopes to disk on Android before the process exits ([#6937](https://github.com/getsentry/sentry-react-native/pull/6937))
   - The hard-crash envelope was only queued on the transport thread, so the event was lost when React Native terminated the process right after. It is now written to the offline cache on the calling thread and sent on the next launch, matching iOS.
+- Support Expo Router 58 in `expoRouterIntegration`. Metro no longer warns about the removed `expo-router/build/global-state/router-store` module, and the integration creates navigation spans again ([#6923](https://github.com/getsentry/sentry-react-native/pull/6923))
 
 ### Internal
 

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

@@ -931,6 +931,7 @@ export interface ReactNativeWrapperOptions {
 export const reactNavigationIntegration: (input?: Partial<ReactNavigationIntegrationOptions>) => Integration & {
     registerNavigationContainer: (navigationContainerRef: unknown) => void;
     _setRouteOverrideProvider: (provider: RouteOverrideProvider | undefined) => void;
+    _startIdleNavigationSpan: (event: UnsafeAction) => void;
     options: ReactNavigationIntegrationOptions;
 };
 
@@ -1337,6 +1338,7 @@ export function wrapTurboModule<T extends object>(name: string, module: T | null
 //
 // src/js/tracing/reactnativetracing.ts:93:3 - (ae-forgotten-export) The symbol "ReactNativeTracingState" needs to be exported by the entry point index.d.ts
 // src/js/tracing/reactnavigation.ts:228:3 - (ae-forgotten-export) The symbol "RouteOverrideProvider" needs to be exported by the entry point index.d.ts
+// src/js/tracing/reactnavigation.ts:233:3 - (ae-forgotten-export) The symbol "UnsafeAction" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

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

@@ -5,7 +5,11 @@ import { debug } from '@sentry/core';
 import type { ExpoRouterStore, ExpoRouterUrlObject } from './expoRouterStore';
 import type { RouteOverride } from './reactnavigation';
 
-import { buildExpoRouterTemplatedPath, tryGetExpoRouterStore } from './expoRouterStore';
+import {
+  buildExpoRouterTemplatedPath,
+  tryGetExpoRouterNavigationEvents,
+  tryGetExpoRouterStore,
+} from './expoRouterStore';
 import { getReactNavigationIntegration, reactNavigationIntegration } from './reactnavigation';
 
 export { buildExpoRouterTemplatedPath };
@@ -15,6 +19,21 @@ export const INTEGRATION_NAME = 'ExpoRouter';
 const POLL_INTERVAL_MS = 50;
 const POLL_MAX_DURATION_MS = 5_000;
 
+// Expo Router 58 emits `actionDispatched` for every reducer action, including internal
+// ones such as `ROUTE_NAMES_CHANGED`, `PRELOAD`, and `SET_PARAMS`. Only user navigations
+// start a navigation span; the rest would ship as empty "Route Change" transactions.
+const NAVIGATION_ACTION_TYPES = new Set([
+  'NAVIGATE',
+  'PUSH',
+  'REPLACE',
+  'GO_BACK',
+  'POP',
+  'POP_TO',
+  'POP_TO_TOP',
+  'JUMP_TO',
+  'RESET',
+]);
+
 export type ExpoRouterIntegrationOptions = Parameters<typeof reactNavigationIntegration>[0];
 
 /**
@@ -30,6 +49,7 @@ export type ExpoRouterIntegrationOptions = Parameters<typeof reactNavigationInte
  */
 export const expoRouterIntegration = (options: ExpoRouterIntegrationOptions = {}): Integration => {
   let pollTimer: ReturnType<typeof setTimeout> | undefined;
+  let removeActionListener: (() => void) | undefined;
 
   const afterAllSetup = (client: Client): void => {
     const store = tryGetExpoRouterStore();
@@ -58,14 +78,26 @@ export const expoRouterIntegration = (options: ExpoRouterIntegrationOptions = {}
         }
         reactNavigation._setRouteOverrideProvider?.(() => buildExpoRouterRouteOverride(store));
         reactNavigation.registerNavigationContainer(navigationRef);
+        removeActionListener = tryGetExpoRouterNavigationEvents()?.addListener('actionDispatched', event => {
+          if (!event.actionType || !NAVIGATION_ACTION_TYPES.has(event.actionType)) {
+            return;
+          }
+          reactNavigation._startIdleNavigationSpan?.({
+            data: {
+              action: { type: event.actionType, payload: event.payload as object | undefined },
+              noop: false,
+              stack: undefined,
+            },
+          });
+        });
         pollTimer = undefined;
         return;
       }
 
       if (Date.now() - startedAt >= POLL_MAX_DURATION_MS) {
         if (!navigationRef) {
           debug.warn(
-            `${INTEGRATION_NAME} Found expo-router router-store but it does not expose a \`navigationRef\`. ` +
+            `${INTEGRATION_NAME} Found expo-router but it does not expose a \`navigationRef\`. ` +
               `This likely means the installed expo-router version is incompatible with this integration.`,
           );
         } else {
@@ -85,6 +117,8 @@ export const expoRouterIntegration = (options: ExpoRouterIntegrationOptions = {}
         clearTimeout(pollTimer);
         pollTimer = undefined;
       }
+      removeActionListener?.();
+      removeActionListener = undefined;
     });
   };
 

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

@@ -10,6 +10,7 @@
 
 export interface ExpoRouterNavigationRef {
   current: unknown | null;
+  getRootState?: () => unknown;
 }
 
 export interface ExpoRouterUrlObject {
@@ -22,7 +23,7 @@ export interface ExpoRouterUrlObject {
 
 export interface ExpoRouterStore {
   navigationRef?: ExpoRouterNavigationRef;
-  getRouteInfo?: () => ExpoRouterUrlObject;
+  getRouteInfo?: () => ExpoRouterUrlObject | undefined;
 }
 
 export interface NormalizedExpoRouterRouteInfo {
@@ -42,17 +43,91 @@ export interface NormalizedExpoRouterRouteInfo {
   segments?: string[];
 }
 
+export interface ExpoRouterActionDispatchedEvent {
+  actionType?: string;
+  payload?: unknown;
+}
+
+export interface ExpoRouterInternalNavigationEvents {
+  addListener: (
+    name: 'actionDispatched',
+    callback: (event: ExpoRouterActionDispatchedEvent) => void,
+  ) => (() => void) | undefined;
+}
+
 /**
- * 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.
+ * Returns the navigation container ref and route info of Expo Router, or `null`
+ * if `expo-router` is not installed or does not expose the expected API.
+ *
+ * Expo Router 58 declares `exports`, so Metro warns about any deep path that is
+ * missing from it. Older versions have no `exports`, so a missing deep path
+ * there is a silent optional dependency.
  */
 export function tryGetExpoRouterStore(): ExpoRouterStore | null {
+  let getNavigationContainerRef: (() => ExpoRouterNavigationRef | undefined) | undefined;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const expoRouter = require('expo-router') as {
+      useNavigationContainerRef?: () => ExpoRouterNavigationRef | undefined;
+    };
+    // Not a React hook: it reads a module-level store, so it is safe to call outside render.
+    getNavigationContainerRef = expoRouter?.useNavigationContainerRef;
+  } catch {
+    return null;
+  }
+  if (!getNavigationContainerRef) {
+    return null;
+  }
+  const getRef = getNavigationContainerRef;
+  const readNavigationContainerRef = (): ExpoRouterNavigationRef | undefined => {
+    try {
+      return getRef();
+    } catch {
+      return undefined;
+    }
+  };
+  const getRouteInfoFromState = tryGetRouteInfoFromState();
+
+  return {
+    // Before Expo Router 58 the ref is undefined until the Root Layout renders, so read it on every access.
+    get navigationRef() {
+      return readNavigationContainerRef();
+    },
+    getRouteInfo: getRouteInfoFromState
+      ? () => {
+          const navigationRef = readNavigationContainerRef();
+          const state = navigationRef?.current ? navigationRef.getRootState?.() : undefined;
+          return state ? getRouteInfoFromState(state) : undefined;
+        }
+      : undefined,
+  };
+}
+
+/** `getRouteInfoFromState` exists only in Expo Router 56 and later. */
+function tryGetRouteInfoFromState(): ((state: unknown) => ExpoRouterUrlObject) | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require('expo-router/build/global-state/getRouteInfoFromState') as {
+      getRouteInfoFromState?: (state: unknown) => ExpoRouterUrlObject;
+    };
+    return mod?.getRouteInfoFromState;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Returns the internal navigation event emitter of Expo Router 58 and later, or
+ * `null` for older versions. Expo Router 58 does not emit React Navigation's
+ * `__unsafe_action__` event, so this is the only signal of a dispatched action.
+ */
+export function tryGetExpoRouterNavigationEvents(): ExpoRouterInternalNavigationEvents | null {
   try {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const mod = require('expo-router/build/global-state/router-store') as {
-      store?: ExpoRouterStore;
+    const mod = require('expo-router/build/global-state/internalNavigationEvents') as {
+      internalNavigationEvents?: ExpoRouterInternalNavigationEvents;
     };
-    return mod?.store ?? null;
+    return mod?.internalNavigationEvents ?? null;
   } catch {
     return null;
   }

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

@@ -226,6 +226,11 @@ export const reactNavigationIntegration = ({
    * supply the canonical route info on every state change. Use `undefined` to clear.
    */
   _setRouteOverrideProvider: (provider: RouteOverrideProvider | undefined) => void;
+  /**
+   * @internal API: start a navigation span for a dispatched action, for navigators that do not
+   * emit `__unsafe_action__` (for example, Expo Router 58 and later).
+   */
+  _startIdleNavigationSpan: (event: UnsafeAction) => void;
   options: ReactNavigationIntegrationOptions;
 } => {
   let navigationContainer: NavigationContainer | undefined;
@@ -896,6 +901,7 @@ export const reactNavigationIntegration = ({
     afterAllSetup,
     registerNavigationContainer,
     _setRouteOverrideProvider,
+    _startIdleNavigationSpan: event => startIdleNavigationSpan(event),
     options: {
       routeChangeTimeoutMs,
       enableTimeToInitialDisplay,