Migrate from 5.x to 6.x

Learn how to migrate from version 5 to version 6 of the Sentry React Native SDK

The main goal of version 6 of the Sentry React Native SDK, is to bring compatibility with Sentry JavaScript version 8 and to improve our performance monitoring APIs and integrations. This version is introducing breaking changes because of the JavaScript SDK dependency upgrade to version 8 and because we've removed deprecated APIs and restructured npm package contents.

The Sentry React Native SDK ships with the Sentry JavaScript SDK as a dependency. The Sentry JavaScript SDK has been updated to version 8. This version includes a number of breaking changes. Please follow the JavaScript migration guides to complete the upgrade.

The initial @sentry/react-native@6.0.0 ships with @sentry/core@8.31.0. Always use the exact JavaScript SDK version if adding it manually to your project. Any other version might not be compatible with the React Native SDK.

The main focus of the Sentry JavaScript SDK version 8, is to improve our performance monitoring APIs. That's why the Tracing API changes are described in a standalone guide. Please follow the Tracing API changes guide to complete the upgrade.

Other general JavaScript SDK version 8 changes are described in the JavaScript SDK 7.x to 8.x migration guide.

This section describes API changes in the Sentry React Native SDK, version 6.

To change the following options, you no longer need to create an instance of React Native Tracing. Instead, you can pass them directly to Sentry.init options.

Copied
import * as Sentry from '@sentry/react-native';

Sentry.init({
  tracesSampleRate: 1.0,
+  enableAppStartTracking: true,
+  enableNativeFramesTracking: true,
+  enableStallTracking: true,
+  enableUserInteractionTracing: true,
-  integrations: [new Sentry.ReactNativeTracing({
-    enableAppStartTracking: true,
-    enableNativeFramesTracking: true,
-    enableStallTracking: true,
-    enableUserInteractionTracing: true,
-  })],
});

Navigation Instrumentations are now standalone integrations. You'll need to add it to the integrations array in the Sentry.init options.

Copied
import Sentry from '@sentry/react-native';
import { useNavigationContainerRef } from 'expo-router';

- const reactNavigationIntegration = new Sentry.ReactNavigationInstrumentation();
+ const reactNavigationIntegration =  Sentry.reactNavigationIntegration();

Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
-    new Sentry.ReactNativeTracing({ routingInstrumentation }),
+    reactNavigationIntegration,
  ],
});

ReactNavigationV4Instrumentation was removed in version 6 of the SDK. If you're using React Navigation version 4, you'll need to upgrade to version 5 or newer.

RoutingInstrumentation was removed in version 6 of the SDK. If you're using custom navigation, use the startIdleNavigationSpan function.

Copied
- const routingInstrumentation = new Sentry.RoutingInstrumentation();

Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
-    new Sentry.ReactNativeTracing({
-      routingInstrumentation,
-    }),
  ],
})

const App = () => {
  <SomeNavigationLibrary
    onRouteWillChange={(newRoute) => {
-      routingInstrumentation.onRouteWillChange({
+      Sentry.startIdleNavigationSpan({
        name: newRoute.name,
        op: 'navigation'
      });
    }}
  />
};

The beforeNavigate option was removed in version 6 of the SDK . Use the beforeStartSpan option instead. The beforeStartSpan option is a function that's called before starting a navigation span. This function can't stop the span from being started, but it can modify the span start options before it starts.

Copied
Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
-    new Sentry.ReactNativeTracing({
-      beforeNavigate: (context) => {
+    Sentry.reactNativeTracingIntegration({
+      beforeStartSpan: (options) => {
         return {
           ...options,
            op: 'navigation',
         };
       },
    }),
  ],
});

The enableSpotlight and spotlightSidecarUrl options were removed in version 6 of the SDK. Use the spotlight option instead.

Copied
import * as Sentry from '@sentry/react-native';

Sentry.init({
  tracesSampleRate: 1.0,
-  enableSpotlight: true,
-  spotlightSidecarUrl: 'http://localhost:8969/stream',
+  spotlight: true // or 'http://localhost:8969/stream',
});

The idleTimeout and maxTransactionDuration options were removed in version 6 of the SDK. Use the idleTimeoutMs and finalTimeoutMs options from the JavaScript SDK instead.

Copied
import * as Sentry from '@sentry/react-native';

Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
-    new Sentry.ReactNativeTracing({
-      idleTimeout: 1_000,
-      maxTransactionDuration: 5_000,
+    Sentry.reactNativeTracing({
+      idleTimeoutMs: 1_000,
+      finalTimeoutMs: 5_000,
    }),
  ],
});

We updated the behavior of the SDKs when no tracePropagationTargets option was defined. As a reminder, you can provide a list of strings or RegExes that will be matched against URLs to let the SDK know which outgoing requests tracing HTTP headers should be attached to. These tracing headers are used for distributed tracing.

Previously, on the browser and in React native, when tracePropagationTargets weren't defined, they defaulted to the following: ['localhost', /^\/(?!\/)/]. This meant that all request targets that had "localhost" in the URL, or started with a / were equipped with tracing headers. This default was chosen to prevent CORS errors in your browser applications. However, this default had a few flaws.

Going forward, when the tracePropagationTargets option isn't set:

  • tracing headers will be attached to all outgoing requests in React Native
  • tracing headers will also be attached to all outgoing requests on the same origin as the Browser (including WebViews)

For example, if you're on https://example.com/ and you send a request to https://example.com/api, the request will be traced (in other words, it will have trace headers attached). Requests sent to https://api.example.com/ on the other hand, will not, because they're on a different origin. The same goes for all applications running on localhost.

When you provide a tracePropagationTargets option, all of the entries you define will now be matched against the full URL of the outgoing request. Previously, it was only matched against what you called request APIs with. For example, if you made a request like fetch("/api/posts"), the provided tracePropagationTargets were only compared against "/api/posts".

Previous
Migration Guide
Next
Migrate to 5.x
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").