--- title: "Migrate to 5.x" description: "Learn how to migrate to version 5 of the SDK ." url: https://docs.sentry.io/platforms/react-native/migration/before-v5/ --- # Migrate to 5.x | Sentry for React Native ## [From 4.x to 5.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-4x-to-5x) The React Native SDK version 5 supports both Legacy (from RN 0.65 and above) and New Architecture (from RN 0.69 and above) as well as the new React Native Gradle Plugin (introduced in RN 0.71). ### [Naming and behavior changes](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#naming-and-behavior-changes) Rename the following `Sentry.init` options: * `enableAutoPerformanceTracking` to `enableAutoPerformanceTracing` * `enableOutOfMemoryTracking` to `enableWatchdogTerminationTracking` * `ReactNativeTracingOptions.idleTimeout` to `ReactNativeTracingOptions.idleTimeoutMs` * `ReactNativeTracingOptions.maxTransactionDuration` to `ReactNativeTracingOptions.finalTimeoutMs` If you're using `TouchEventBoundary` and `accessibilityLabel` set the following: ```javascript Sentry.wrap(App, { touchEventBoundaryProps: { labelName: "accessibilityLabel" }, }); ``` The current stack trace for `Sentry.captureMessage` has been moved from `event.exception` to `event.threads`. The default `breadcrumb.level` is `info`, value `critical` has been removed and `log` has been transformed to `debug` on iOS and Android. The bundled `sentry-cli` version has been bumped to [v2.10.0](https://github.com/getsentry/sentry-cli/releases/tag/2.10.0). Check your usage of `sentry-cli` to reflect [breaking changes](https://github.com/getsentry/sentry-cli/releases/tag/2.0.0). Note, that `upload-dsym` has been replaced by `debug-files upload` and requires a path. Make sure to check your `Upload Debug Symbols` build step in your Xcode project. The command should look like the example below: ```bash # Before ../node_modules/@sentry/cli/bin/sentry-cli upload-dsym # After ../node_modules/@sentry/cli/bin/sentry-cli debug-files upload "$DWARF_DSYM_FOLDER_PATH" ``` ### [iOS specific changes](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#ios-specific-changes) The following metadata are synchronized from `sentry-cocoa` to `react-native`: * `tags` * `extra` * `fingerprint` * `level` * `environment` * `breadcrumbs` The synchronized `fingerprint` might affect issue grouping in Sentry. React Native `event.fingerprint` is merged with iOS `fingerprint` without duplicates with RN items being first in the order. `sentry-cocoa` has been bumped to v8.0.0, please follow the related migration [here](https://docs.sentry.io/platforms/apple/migration.md#migrating-from-7x-to-8x). `sentry-wizard` doesn't patch iOS projects for React Native 0.65 to 0.68. These versions have to be [patched manually](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#bundle-react-native-code-and-images). ### [Changes to Minimum Supported Versions](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#changes-to-minimum-supported-versions) The minimum supported iOS version has been bumped to iOS 11. The minimum Android API has been bumped to 21. The minimum supported React Native version is 0.65.0. ## [From 4.8.x to 4.9.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-48x-to-49x) A new feature that enables sending runtime JavaScript dependencies in events for React Native apps was added in release `4.9.0`. No manual steps are required to enable this on Android builds. For iOS, you need to patch the `shellScript` in the `ios/$projectName.xcodeproj/project.pbxproj` file, where `$projectName` is likely your project's name. To do this, search for the `Bundle React Native code and images` phase and patch the `shellScript`. React Native 0.69.0 and above: *Old*: ```bash shellScript = "export SENTRY_PROPERTIES=sentry.properties\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nset -e\n\nWITH_ENVIRONMENT=\"../node_modules/react-native/scripts/xcode/with-environment.sh\"\nREACT_NATIVE_XCODE=\"../node_modules/react-native/scripts/react-native-xcode.sh\"\n\n/bin/sh -c \"$WITH_ENVIRONMENT \\\"../node_modules/@sentry/cli/bin/sentry-cli react-native xcode $REACT_NATIVE_XCODE\\\"\"\n"; ``` *New*: ```bash shellScript = "export SENTRY_PROPERTIES=sentry.properties\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nset -e\n\nWITH_ENVIRONMENT=\"../node_modules/react-native/scripts/xcode/with-environment.sh\"\nREACT_NATIVE_XCODE=\"../node_modules/react-native/scripts/react-native-xcode.sh\"\n\n/bin/sh -c \"$WITH_ENVIRONMENT \\\"../node_modules/@sentry/cli/bin/sentry-cli react-native xcode $REACT_NATIVE_XCODE\\\"\"\n\n/bin/sh ../node_modules/@sentry/react-native/scripts/collect-modules.sh\n"; ``` React Native 0.56.0 to 0.68.0: *Old*: ```bash shellScript = "export NODE_BINARY=node\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nexport SENTRY_PROPERTIES=../sentry.properties\n\n../node_modules/@sentry/cli/bin/sentry-cli react-native xcode \\\n ../node_modules/react-native/scripts/react-native-xcode.sh\n"; ``` *New*: ```bash shellScript = "export NODE_BINARY=node\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nexport SENTRY_PROPERTIES=../sentry.properties\n\n../node_modules/@sentry/cli/bin/sentry-cli react-native xcode \\\n ../node_modules/react-native/scripts/react-native-xcode.sh\n\n/bin/sh ../node_modules/@sentry/react-native/scripts/collect-modules.sh\n"; ``` See the [JS SDK migration guide](https://github.com/getsentry/sentry-javascript/blob/f4861f8c3eab1181ab8e7544402b23770a992d6e/MIGRATION.md?plain=1#L81) for changes related to the upgrade to version `7.19.0`. ## [From 4.6.x to 4.7.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-46x-to-47x) See the JS SDK migration guide [here](https://github.com/getsentry/sentry-javascript/blob/f4861f8c3eab1181ab8e7544402b23770a992d6e/MIGRATION.md?plain=1#L89) and [here](https://github.com/getsentry/sentry-javascript/blob/f4861f8c3eab1181ab8e7544402b23770a992d6e/MIGRATION.md?plain=1#L93) for changes related to the upgrade to version `7.16.0`. ## [From 3.x to 4.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-3x-to-4x) By bumping Sentry JavaScript to v7, new breaking changes were introduced, to learn more about what was changed, check out the [breaking changes changelog](https://github.com/getsentry/sentry-javascript/blob/7.0.0/CHANGELOG.md#breaking-changes) from Sentry JavaScript. By bumping Sentry Android to v6, new breaking changes were introduced, to learn more about what was changed, check out the [migration guide](https://docs.sentry.io/platforms/android/migration.md#migrating-from-iosentrysentry-android-5x-to-iosentrysentry-android-600). ## [From 3.0.x to 3.1.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-30x-to-31x) `ReactNavigationV5Instrumentation` was renamed to `ReactNavigationInstrumentation` and supports every version of React Navigation from v5 onwards, including v6. You only need to change the name wherever you call the constructor for the instrumentation: ```javascript // Old const routingInstrumentation = new Sentry.ReactNavigationV5Instrumentation(); // New const routingInstrumentation = new Sentry.ReactNavigationInstrumentation(); ``` ## [From 2.x to 3.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-2x-to-3x) There are no changes needed when migrating from versions `2.x` to `3.x`, although you will need to make sure that you run `pod install` on iOS and that you rebuild your app on both platforms. ### [Event Origin and Environment Tags](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#event-origin-and-environment-tags) When upgrading from prior versions to `3.x`, you may see a mismatch in the values of the `event.environment` tag compared to events sent from the SDK prior to this version. Events that originate from native iOS code will now have the `event.environment` tag set to `native`. Read more about these tags on the [event information guide](https://docs.sentry.io/platforms/react-native/usage/event-information.md#event-origin-and-environment-tags). ## [From 2.4.x to 2.5.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-24x-to-25x) The breaking changes are relevant only to Android. There are no breaking changes for other platforms. ### [Android Specific Changes](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#android-specific-changes) Sentry React Native version `2.5.0` depends on Sentry Android `5.0.0`. Please [refer to the Android migration guide for Android-specific changes](https://docs.sentry.io/platforms/android/migration.md#migrating-from-iosentrysentry-android-430-to-iosentrysentry-android-500). `Settings.Secure.ANDROID_ID` has been removed and replaced with a randomly-generated `installationId`. This may affect the number of unique users displayed on the Issues page and Alerts. If you've always set a custom user using `Sentry.setUser(customUser)`, the behavior hasn't changed. While you don't have to make any updates, if you want to maintain the old behavior, use the following code snippet which makes use of the [react-native-device-info](https://github.com/react-native-device-info/react-native-device-info) library. ```javascript import { Platform } from "react-native"; import DeviceInfo from "react-native-device-info"; import * as Sentry from "@sentry/react-native"; Sentry.init({ // ... }); // Only add the event processor on Android if (Platform.OS === "android") { Sentry.addGlobalEventProcessor((event) => { // Get the ANDROID_ID const id = DeviceInfo.getUniqueId(); // If the user does not exist, set the id to be the unique id. if (!event.user) { event.user = { id }; } return event; }); } ``` ## [React Navigation Instrumentation from <2.3.0](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#react-navigation-instrumentation-from-230) We changed the initialization method for the React Navigation v5 and above, routing instrumentation to avoid a potential issue when using linking. You now register the navigation container inside the `onReady` prop passed to the `NavigationContainer`. From: ```javascript // Old Functional Component Example const App = () => { const navigation = React.useRef(); React.useEffect(() => { routingInstrumentation.registerNavigationContainer(navigation); }, []); return ...; }; // Old Class Component Example class App extends React.Component { navigation = React.createRef(); componentDidMount() { routingInstrumentation.registerNavigationContainer(navigation); } render() { return ( ... ); } } ``` To: ```javascript // Functional Component Example const App = () => { const navigation = React.useRef(); return ( { // Register the navigation container with the instrumentation inside onReady routingInstrumentation.registerNavigationContainer(navigation); }} > ... ); }; // Class Component Example class App extends React.Component { navigation = React.createRef(); render() { return ( { // Register the navigation container with the instrumentation inside onReady routingInstrumentation.registerNavigationContainer(navigation); }} > ... ); } } ``` ## [From 1.x to 2.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-1x-to-2x) Sentry's most recent version of our React Native SDK enables release health tracking and native stack traces by default. This version of the SDK uses the [envelope endpoint](https://develop.sentry.dev/sdk/envelopes/). If you're using self-hosted Sentry, the SDK requires Sentry version 20.6.0 and above. If you're using our SaaS product ([sentry.io](https://sentry.io)), no changes or actions are needed. ### [iOS/MacOS](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#iosmacos) While the migration doesn't introduce breaking changes for iOS/MacOS on the React Native side, we recommend running `pod install` after the upgrade. If you're using our Cocoa SDK directly, follow the [migration guide for 5.x to 6.x](https://docs.sentry.io/platforms/apple/migration.md#migrating-from-5x-to-6x). On iOS/MacOS, we now cache events in envelopes on the disk. As a result, you might lose a few cached events during the migration. Due to the high level of effort involved, the migration from 5.x to 6.x won't move these few cached events into envelopes. ### [Android](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#android) If you're on React Native <0.60, you'll need to update this line in your `MainApplication.java`: From (earlier version): ```java import io.sentry.RNSentryPackage; ``` New: ```java import io.sentry.react.RNSentryPackage; ``` Other than the one line change noted above, the migration shouldn't cause breaking changes on the React Native side. If you use our Android SDK directly, you should follow its [migration guide for 2.x to 3.x](https://docs.sentry.io/platforms/android/migration.md#migrating-from-iosentrysentry-android-2x-to-iosentrysentry-android-3x). ## [From 0.x to 1.x](https://docs.sentry.io/platforms/react-native/migration/before-v5.md#from-0x-to-1x) If you're upgrading from an earlier version of Sentry's React Native SDK, you should unlink the package to ensure the generated code is updated to the latest version: ```bash react-native unlink react-native-sentry ``` After that remove `react-native-sentry` from your `package.json`: ```bash npm uninstall react-native-sentry --save # or yarn remove react-native-sentry ``` From there, you can follow the standard installation instructions for `@sentry/react-native`.