From c1c033b529e23afaff40727ea80731aa5e6a5001 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich Date: Thu, 12 Sep 2024 17:02:17 +0200 Subject: [PATCH 1/7] feat: Add RN SDK v6 migration guide --- .../react-native/migration/before-v5.mdx | 302 ++++++++++++++++++ .../react-native/migration/index.mdx | 299 +---------------- .../react-native/migration/sentry-expo.mdx | 2 +- .../react-native/migration/v5-to-v6.mdx | 238 ++++++++++++++ 4 files changed, 542 insertions(+), 299 deletions(-) create mode 100644 docs/platforms/react-native/migration/before-v5.mdx create mode 100644 docs/platforms/react-native/migration/v5-to-v6.mdx diff --git a/docs/platforms/react-native/migration/before-v5.mdx b/docs/platforms/react-native/migration/before-v5.mdx new file mode 100644 index 0000000000000..995e295dadb4f --- /dev/null +++ b/docs/platforms/react-native/migration/before-v5.mdx @@ -0,0 +1,302 @@ +--- +title: Migrate to 5.x +sidebar_order: 200 +description: "Learn about migrating to the SDK version 5." +--- + +## From 4.x to 5.x + +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 + +Rename the following `Sentry.init` options: + +- `enableAutoPerformanceTracking` to `enableAutoPerformanceTracing` +- `enableOutOfMemoryTracking` to `enableWatchdogTerminationTracking` +- `ReactNativeTracingOptions.idleTimeout` to `ReactNativeTracingOptions.idleTimeoutMs` +- `ReactNativeTracingOptions.maxTransactionDuration` to `ReactNativeTracingOptions.finalTimeoutMs` + +If you are using `TouchEventBoundary` and `accessibilityLabel` set the following: + +```javascript +Sentry.wrap(App, { + touchEventBoundaryProps: { labelName: "accessibilityLabel" }, +}); +``` + +Current stack trace for `Sentry.captureMessage` has been moved from `event.exception` to `event.threads`. + +Default `breadcrumb.level` is `info`, value `critical` has been removed and `log` is 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 + +The following metadata are synchronized from `sentry-cocoa` to `react-native`: + +- `tags` +- `extra` +- `fingerprint` +- `level` +- `environment` +- `breadcrumbs` + +The synchronized `fingerprint` might affect grouping of issues 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](/platforms/apple/migration/#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](/platforms/react-native/manual-setup/manual-setup/#bundle-react-native-code-and-images). + +### Changes to Minimum Supported Versions + +The minimum supported iOS version has been bumped 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 + +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 + +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 + +By bumping Sentry JavaScript to v7, new breaking changes were introduced, to know more what was changed, check 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 know more what was changed, check the [migration guide](/platforms/android/migration/#migrating-from-iosentrysentry-android-5x-to-iosentrysentry-android-600). + +## From 3.0.x to 3.1.x + +`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 + +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 to rebuild your app on both platforms. + +### 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](/platforms/react-native/usage/event-information/#event-origin-and-environment-tags). + +## From 2.4.x to 2.5.x + +The breaking changes are relevant only to Android. There are no breaking changes for other platforms. + +### 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](/platforms/android/migration/#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 the Issues page and Alerts. If you always set a custom user using `Sentry.setUser(customUser)`, the behavior has not changed. While you don't have to make any update, 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 + +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 + +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 are using self-hosted Sentry, the SDK requires Sentry version 20.6.0 and above. If you are using our SaaS product ([sentry.io](https://sentry.io)), no changes or actions needed. + +### iOS/MacOS + +While the migration does not introduce breaking changes for iOS/MacOS on the React Native side, we recommend running `pod install` after the upgrade. + + + +If you are using our Cocoa SDK directly, follow that [migration guide for 5.x to 6.x](/platforms/apple/migration/#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 effort involved, the migration from 5.x to 6.x does not move these few cached events into envelopes. + +### Android + +If you are on React Native <0.60, you will need to update this line in your `MainApplication.java`: + +From (earlier version): + +```java +import io.sentry.RNSentryPackage; +``` + +```kotlin +import io.sentry.RNSentryPackage +``` + +New: + +```java +import io.sentry.react.RNSentryPackage; +``` + +```kotlin +import io.sentry.react.RNSentryPackage +``` + +Other than the one line change noted above, the migration should not 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](/platforms/android/migration/#migrating-from-iosentrysentry-android-2x-to-iosentrysentry-android-3x). + + + + +## From 0.x to 1.x + +If you are 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`. diff --git a/docs/platforms/react-native/migration/index.mdx b/docs/platforms/react-native/migration/index.mdx index 88fb0767a0b2e..6a96809cf0fcc 100644 --- a/docs/platforms/react-native/migration/index.mdx +++ b/docs/platforms/react-native/migration/index.mdx @@ -1,304 +1,7 @@ --- title: Migration Guide sidebar_order: 8000 -description: "Learn about migrating from 1.x to 2.x to enable release health tracking and native stack traces by default." +description: "Learn about migrating to new Sentry React Native SDK versions." --- - -## From 4.x to 5.x - -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 - -Rename the following `Sentry.init` options: - -- `enableAutoPerformanceTracking` to `enableAutoPerformanceTracing` -- `enableOutOfMemoryTracking` to `enableWatchdogTerminationTracking` -- `ReactNativeTracingOptions.idleTimeout` to `ReactNativeTracingOptions.idleTimeoutMs` -- `ReactNativeTracingOptions.maxTransactionDuration` to `ReactNativeTracingOptions.finalTimeoutMs` - -If you are using `TouchEventBoundary` and `accessibilityLabel` set the following: - -```javascript -Sentry.wrap(App, { - touchEventBoundaryProps: { labelName: "accessibilityLabel" }, -}); -``` - -Current stack trace for `Sentry.captureMessage` has been moved from `event.exception` to `event.threads`. - -Default `breadcrumb.level` is `info`, value `critical` has been removed and `log` is 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 - -The following metadata are synchronized from `sentry-cocoa` to `react-native`: - -- `tags` -- `extra` -- `fingerprint` -- `level` -- `environment` -- `breadcrumbs` - -The synchronized `fingerprint` might affect grouping of issues 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](/platforms/apple/migration/#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](/platforms/react-native/manual-setup/manual-setup/#bundle-react-native-code-and-images). - -### Changes to Minimum Supported Versions - -The minimum supported iOS version has been bumped 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 - -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 - -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 - -By bumping Sentry JavaScript to v7, new breaking changes were introduced, to know more what was changed, check 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 know more what was changed, check the [migration guide](/platforms/android/migration/#migrating-from-iosentrysentry-android-5x-to-iosentrysentry-android-600). - -## From 3.0.x to 3.1.x - -`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 - -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 to rebuild your app on both platforms. - -### 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](/platforms/react-native/usage/event-information/#event-origin-and-environment-tags). - -## From 2.4.x to 2.5.x - -The breaking changes are relevant only to Android. There are no breaking changes for other platforms. - -### 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](/platforms/android/migration/#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 the Issues page and Alerts. If you always set a custom user using `Sentry.setUser(customUser)`, the behavior has not changed. While you don't have to make any update, 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 - -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 - -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 are using self-hosted Sentry, the SDK requires Sentry version 20.6.0 and above. If you are using our SaaS product ([sentry.io](https://sentry.io)), no changes or actions needed. - -### iOS/MacOS - -While the migration does not introduce breaking changes for iOS/MacOS on the React Native side, we recommend running `pod install` after the upgrade. - - - -If you are using our Cocoa SDK directly, follow that [migration guide for 5.x to 6.x](/platforms/apple/migration/#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 effort involved, the migration from 5.x to 6.x does not move these few cached events into envelopes. - -### Android - -If you are on React Native <0.60, you will need to update this line in your `MainApplication.java`: - -From (earlier version): - -```java -import io.sentry.RNSentryPackage; -``` - -```kotlin -import io.sentry.RNSentryPackage -``` - -New: - -```java -import io.sentry.react.RNSentryPackage; -``` - -```kotlin -import io.sentry.react.RNSentryPackage -``` - -Other than the one line change noted above, the migration should not 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](/platforms/android/migration/#migrating-from-iosentrysentry-android-2x-to-iosentrysentry-android-3x). - - - - -## From 0.x to 1.x - -If you are 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`. diff --git a/docs/platforms/react-native/migration/sentry-expo.mdx b/docs/platforms/react-native/migration/sentry-expo.mdx index b02aa9c77206f..df6ec179017e8 100644 --- a/docs/platforms/react-native/migration/sentry-expo.mdx +++ b/docs/platforms/react-native/migration/sentry-expo.mdx @@ -1,6 +1,6 @@ --- title: Migrate from sentry-expo -sidebar_order: 3 +sidebar_order: 300 description: "Learn about migrating from sentry-expo to @sentry/react-native" --- diff --git a/docs/platforms/react-native/migration/v5-to-v6.mdx b/docs/platforms/react-native/migration/v5-to-v6.mdx new file mode 100644 index 0000000000000..05ee4f1702bd2 --- /dev/null +++ b/docs/platforms/react-native/migration/v5-to-v6.mdx @@ -0,0 +1,238 @@ +--- +title: Migrate from 5.x to 6.x +sidebar_order: 100 +description: "Learn about migrating from the SDK version 5 to 6" +--- + +The main goal of Sentry React Native SDK version 6 is bring compatibility with Sentry JavaScript version 8 and to improve our performance monitoring APIs and integrations. This version is breaking because of the JavaScript SDK dependency upgrade to version 8 and becuase we removed deprecated APIs, restructured npm package contents. + +## Important changes in dependencies + +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. + +### Performance Monitoring API changes + +The main focus of the Sentry JavaScript SDK version 8 is to improve our performance monitoring APIs and that's why the Tracing APIs changes are desccribed in a standalone guide. Please follow the [Tracing API changes](/platforms/javascript/migration/v7-to-v8/v8-new-performance-api/) guide to complete the upgrade. + +### General API changes + +Other general JavaScript SDK version 8 changes are described in the [JavaScript SDK 7.x to 8.x migration guide](/platforms/javascript/migration/v7-to-v8/). + +## Important React Native SDK `6.x` changes + +This section describes the APIs changes in the Sentry React Native SDK version 6. + +### React Native Tracing options moved to `Sentry.init` options + +To change the follwoing options, you no longer need to create instance of React Native Tracing. Instead, you can pass them directly to `Sentry.init` options. + +```javascript diff +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 + +The Navigation Instrumentations are now a standalone integrations and you need to add it to the `integrations` array in the `Sentry.init` options. + +```javascript {tabTitle:Expo Router} diff +import Sentry from '@sentry/react-native'; +import { useNavigationContainerRef } from 'expo-router'; + +- const reactNavigationIntegration = new Sentry.ReactNavigationInstrumentation(); ++ const reactNavigationIntegration = new Sentry.reactNavigationIntegration(); + +Sentry.init({ + tracesSampleRate: 1.0, + integrations: [ +- new Sentry.ReactNativeTracing({ routingInstrumentation }), ++ reactNavigationIntegration, + ], +}); +``` + +```javascript {tabTitle:React Navigation} diff +import Sentry from '@sentry/react-native'; +import { NavigationContainer } from '@react-navigation/native'; + +- const reactNavigationIntegration = new Sentry.ReactNavigationInstrumentation(); ++ const reactNavigationIntegration = new Sentry.reactNavigationIntegration(); + +Sentry.init({ + tracesSampleRate: 1.0, + integrations: [ +- new Sentry.ReactNativeTracing({ routingInstrumentation }), ++ reactNavigationIntegration, + ], +}); +``` + +```javascript {tabTitle:React Native Navigation} diff +import Sentry from '@sentry/react-native'; +import { Navigation } from 'react-native-navigation'; + +Sentry.init({ + tracesSampleRate: 1.0, + integrations: [ +- new Sentry.ReactNativeTracing({ +- routingInstrumentation: new Sentry.ReactNativeNavigationInstrumentation( +- Navigation, +- ), +- }), ++ new Sentry.reactNativeNavigationIntegration({ ++ navigation: Navigation, ++ }), + ], +}); +``` + +### React Navigation version 4 is not supported + +`ReactNavigationV4Instrumentation` was removed in the SDK version 6. If you are using React Navigation version 4, you need to upgrade to version 5 or never. + +### RoutingInstrumentation for Custom Navigation was removed + +`RoutingInstrumentation` was removed in the SDK version 6. If you are using custom navigation, use `startIdleNavigationSpan` fucntion. + +```javascript {tabTitle:Direct} diff +- const routingInstrumentation = new Sentry.RoutingInstrumentation(); + +Sentry.init({ + tracesSampleRate: 1.0, + integrations: [ +- new Sentry.ReactNativeTracing({ +- routingInstrumentation, +- }), + ], +}) + +const App = () => { + { +- routingInstrumentation.onRouteWillChange({ ++ Sentry.startIdleNavigationSpan({ + name: newRoute.name, + op: 'navigation' + }); + }} + /> +}; +``` + +```javascript {tabTitle:Integration} diff +// Before +import Sentry from '@sentry/react-native'; + +-class CustomInstrumentation extends Sentry.RoutingInstrumentation { +- constructor(navigator) { +- super(); +- +- this.navigator.registerRouteChangeListener( +- this.routeListener.bind(this), +- ); +- } +- +- routeListener(newRoute) { +- this.onRouteWillChange({ ++const customNavigationIntegration = ({navigator}) => { ++ navigator.registerRouteChangeListener((newRoute) => { ++ Sentry.startIdleNavigationSpan({ + name: newRoute.name, + op: "navigation", +- }); +- } +-} ++ }) ++ }); ++ ++ return { ++ name: "CustomNavigation", ++ }; ++}; + +Sentry.init({ + tracesSampleRate: 1.0, + integrations: [ +- new Sentry.ReactNativeTracing({ +- routingInstrumentation: new CustomInstrumentation(navigator), +- }), ++ customNavigationIntegration({navigator}), + ], +}); +``` + +### `enableSpotlight` and `spotlightSidecarUrl` replaced by `spotlight` + +The `enableSpotlight` and `spotlightSidecarUrl` options were removed in the SDK version 6. Use the `spotlight` option instead. + +```javascript diff +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', +}); +``` + +### React Native Tracing `idleTimeout` and `maxTransactionDuration` options were removed + +The `idleTimeout` and `maxTransactionDuration` options were removed in the SDK version 6. Use the `idleTimeoutMs` and `finalTimeoutMs` options from the JavaScript SDK instead. + +```javascript diff +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, + }), + ], +}); +``` + +### Updated behaviour of `tracePropagationTargets` in React Native + +We updated the behaviour 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 tell the SDK, to 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` were not defined, they defaulted to the following: +`['localhost', /^\/(?!\/)/]`. This meant that all request targets to 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 is not set, +- tracing headers will be attached to all outgoing requests in React Native +- and to all outgoing on the same origin on 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 (ie. will have trace headers attached). Requests to +`https://api.example.com/` will not, because it is on a different origin. The same goes for all applications running on +`localhost`. + +When you provide a `tracePropagationTargets` option, all of the entries you defined 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"`. From e847bc0cbedfb2c75fbd9d8f66ca2f2c7f3db8c3 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich Date: Thu, 12 Sep 2024 21:54:56 +0200 Subject: [PATCH 2/7] more changes --- .../react-native/migration/v5-to-v6.mdx | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/platforms/react-native/migration/v5-to-v6.mdx b/docs/platforms/react-native/migration/v5-to-v6.mdx index 05ee4f1702bd2..576be4a597a35 100644 --- a/docs/platforms/react-native/migration/v5-to-v6.mdx +++ b/docs/platforms/react-native/migration/v5-to-v6.mdx @@ -176,6 +176,28 @@ Sentry.init({ }); ``` +### `beforeNavigate` replaced by `beforeStartSpan` + +The `beforeNavigate` option was removed in the SDK version 6. Use the `beforeStartSpan` option instead. The `beforeStartSpan` option is a function that is 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. + +```javascript diff +Sentry.init({ + tracesSampleRate: 1.0, + integrations: [ +- new Sentry.ReactNativeTracing({ +- beforeNavigate: (context) => { ++ Sentry.reactNativeTracingIntegration({ ++ beforeStartSpan: (options) => { + return { + ...options, + op: 'navigation', + }; + }, + }), + ], +}); +``` + ### `enableSpotlight` and `spotlightSidecarUrl` replaced by `spotlight` The `enableSpotlight` and `spotlightSidecarUrl` options were removed in the SDK version 6. Use the `spotlight` option instead. From c5f42a7c7659f45becf9f9d91a694834a22b1300 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Tue, 8 Oct 2024 11:38:22 +0200 Subject: [PATCH 3/7] Apply suggestions from code review before v5 Co-authored-by: Liza Mock --- .../react-native/migration/before-v5.mdx | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/platforms/react-native/migration/before-v5.mdx b/docs/platforms/react-native/migration/before-v5.mdx index 995e295dadb4f..86a3d81f29a59 100644 --- a/docs/platforms/react-native/migration/before-v5.mdx +++ b/docs/platforms/react-native/migration/before-v5.mdx @@ -1,7 +1,7 @@ --- title: Migrate to 5.x sidebar_order: 200 -description: "Learn about migrating to the SDK version 5." +description: "Learn how to migrate to version 5 of the SDK ." --- ## From 4.x to 5.x @@ -17,7 +17,7 @@ Rename the following `Sentry.init` options: - `ReactNativeTracingOptions.idleTimeout` to `ReactNativeTracingOptions.idleTimeoutMs` - `ReactNativeTracingOptions.maxTransactionDuration` to `ReactNativeTracingOptions.finalTimeoutMs` -If you are using `TouchEventBoundary` and `accessibilityLabel` set the following: +If you're using `TouchEventBoundary` and `accessibilityLabel` set the following: ```javascript Sentry.wrap(App, { @@ -25,9 +25,9 @@ Sentry.wrap(App, { }); ``` -Current stack trace for `Sentry.captureMessage` has been moved from `event.exception` to `event.threads`. +The current stack trace for `Sentry.captureMessage` has been moved from `event.exception` to `event.threads`. -Default `breadcrumb.level` is `info`, value `critical` has been removed and `log` is transformed to `debug` on iOS and Android. +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: @@ -50,7 +50,7 @@ The following metadata are synchronized from `sentry-cocoa` to `react-native`: - `environment` - `breadcrumbs` -The synchronized `fingerprint` might affect grouping of issues in Sentry. React Native `event.fingerprint` is merged with iOS `fingerprint` without duplicates with RN items being first in the order. +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](/platforms/apple/migration/#migrating-from-7x-to-8x). @@ -58,7 +58,7 @@ The synchronized `fingerprint` might affect grouping of issues in Sentry. React ### Changes to Minimum Supported Versions -The minimum supported iOS version has been bumped iOS 11. The minimum Android API has been bumped to 21. The minimum supported React Native version is 0.65.0. +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 @@ -100,9 +100,9 @@ See the JS SDK migration guide [here](https://github.com/getsentry/sentry-javasc ## From 3.x to 4.x -By bumping Sentry JavaScript to v7, new breaking changes were introduced, to know more what was changed, check the [breaking changes changelog](https://github.com/getsentry/sentry-javascript/blob/7.0.0/CHANGELOG.md#breaking-changes) from Sentry Javascript. +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 know more what was changed, check the [migration guide](/platforms/android/migration/#migrating-from-iosentrysentry-android-5x-to-iosentrysentry-android-600). +By bumping Sentry Android to v6, new breaking changes were introduced, to learn more about what was changed, check out the [migration guide](/platforms/android/migration/#migrating-from-iosentrysentry-android-5x-to-iosentrysentry-android-600). ## From 3.0.x to 3.1.x @@ -117,9 +117,9 @@ const routingInstrumentation = new Sentry.ReactNavigationInstrumentation(); ## From 2.x to 3.x -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 to rebuild your app on both platforms. +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 +### 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](/platforms/react-native/usage/event-information/#event-origin-and-environment-tags). @@ -131,7 +131,7 @@ The breaking changes are relevant only to Android. There are no breaking 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](/platforms/android/migration/#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 the Issues page and Alerts. If you always set a custom user using `Sentry.setUser(customUser)`, the behavior has not changed. While you don't have to make any update, 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. +`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 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"; @@ -161,7 +161,7 @@ if (Platform.OS === "android") { ## React Navigation Instrumentation from <2.3.0 -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`. +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: @@ -235,23 +235,23 @@ class App extends React.Component { 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 are using self-hosted Sentry, the SDK requires Sentry version 20.6.0 and above. If you are using our SaaS product ([sentry.io](https://sentry.io)), no changes or actions needed. +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 -While the migration does not introduce breaking changes for iOS/MacOS on the React Native side, we recommend running `pod install` after the upgrade. +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 are using our Cocoa SDK directly, follow that [migration guide for 5.x to 6.x](/platforms/apple/migration/#migrating-from-5x-to-6x). +If you're using our Cocoa SDK directly, follow the [migration guide for 5.x to 6.x](/platforms/apple/migration/#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 effort involved, the migration from 5.x to 6.x does not move these few cached events into envelopes. +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 -If you are on React Native <0.60, you will need to update this line in your `MainApplication.java`: +If you're on React Native <0.60, you'll need to update this line in your `MainApplication.java`: From (earlier version): @@ -273,7 +273,7 @@ import io.sentry.react.RNSentryPackage; import io.sentry.react.RNSentryPackage ``` -Other than the one line change noted above, the migration should not cause breaking changes on the React Native side. +Other than the one line change noted above, the migration shouldn't cause breaking changes on the React Native side. @@ -285,7 +285,7 @@ If you use our Android SDK directly, you should follow its [migration guide for ## From 0.x to 1.x -If you are 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: +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 @@ -299,4 +299,4 @@ npm uninstall react-native-sentry --save yarn remove react-native-sentry ``` -From there you can follow the standard installation instructions for `@sentry/react-native`. +From there, you can follow the standard installation instructions for `@sentry/react-native`. From 1f273daba224b321a73c3681c11fc390a8f97272 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Tue, 8 Oct 2024 17:47:19 +0200 Subject: [PATCH 4/7] Apply suggestions from code review version 6 Co-authored-by: Liza Mock --- .../react-native/migration/index.mdx | 2 +- .../react-native/migration/v5-to-v6.mdx | 46 +++++++++---------- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/platforms/react-native/migration/index.mdx b/docs/platforms/react-native/migration/index.mdx index 6a96809cf0fcc..a566495c6b371 100644 --- a/docs/platforms/react-native/migration/index.mdx +++ b/docs/platforms/react-native/migration/index.mdx @@ -1,7 +1,7 @@ --- title: Migration Guide sidebar_order: 8000 -description: "Learn about migrating to new Sentry React Native SDK versions." +description: "Learn how to migrate to the new versions of Sentry's React Native SDK." --- diff --git a/docs/platforms/react-native/migration/v5-to-v6.mdx b/docs/platforms/react-native/migration/v5-to-v6.mdx index 576be4a597a35..01e7d519bf7d9 100644 --- a/docs/platforms/react-native/migration/v5-to-v6.mdx +++ b/docs/platforms/react-native/migration/v5-to-v6.mdx @@ -1,32 +1,32 @@ --- title: Migrate from 5.x to 6.x sidebar_order: 100 -description: "Learn about migrating from the SDK version 5 to 6" +description: "Learn how to migrate from version 5 to version 6 of the Sentry React Native SDK" --- -The main goal of Sentry React Native SDK version 6 is bring compatibility with Sentry JavaScript version 8 and to improve our performance monitoring APIs and integrations. This version is breaking because of the JavaScript SDK dependency upgrade to version 8 and becuase we removed deprecated APIs, restructured npm package contents. +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 breaking because of the JavaScript SDK dependency upgrade to version 8 and because we've removed deprecated APIs and restructured npm package contents. -## Important changes in dependencies +## Important Changes In Dependencies 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 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. -### Performance Monitoring API changes +### Performance-Monitoring API Changes -The main focus of the Sentry JavaScript SDK version 8 is to improve our performance monitoring APIs and that's why the Tracing APIs changes are desccribed in a standalone guide. Please follow the [Tracing API changes](/platforms/javascript/migration/v7-to-v8/v8-new-performance-api/) guide to complete the upgrade. +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](/platforms/javascript/migration/v7-to-v8/v8-new-performance-api/) guide to complete the upgrade. -### General API changes +### General API Changes Other general JavaScript SDK version 8 changes are described in the [JavaScript SDK 7.x to 8.x migration guide](/platforms/javascript/migration/v7-to-v8/). -## Important React Native SDK `6.x` changes +## Important React Native SDK `6.x` Changes -This section describes the APIs changes in the Sentry React Native SDK version 6. +This section describes API changes in the Sentry React Native SDK, version 6. -### React Native Tracing options moved to `Sentry.init` options +### React Native Tracing Options Moved to `Sentry.init` Options -To change the follwoing options, you no longer need to create instance of React Native Tracing. Instead, you can pass them directly to `Sentry.init` options. +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. ```javascript diff import * as Sentry from '@sentry/react-native'; @@ -46,9 +46,9 @@ Sentry.init({ }); ``` -### Navigation Instrumentations are now standalone integrations +### Navigation Instrumentations Are Now Standalone Integrations -The Navigation Instrumentations are now a standalone integrations and you need to add it to the `integrations` array in the `Sentry.init` options. +Navigation Instrumentations are now standalone integrations. You'll need to add it to the `integrations` array in the `Sentry.init` options. ```javascript {tabTitle:Expo Router} diff import Sentry from '@sentry/react-native'; @@ -101,13 +101,13 @@ Sentry.init({ }); ``` -### React Navigation version 4 is not supported +### React Navigation Version 4 Is Not Supported -`ReactNavigationV4Instrumentation` was removed in the SDK version 6. If you are using React Navigation version 4, you need to upgrade to version 5 or never. +`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 for Custom Navigation was removed +### RoutingInstrumentation for Custom Navigation Was Removed -`RoutingInstrumentation` was removed in the SDK version 6. If you are using custom navigation, use `startIdleNavigationSpan` fucntion. +`RoutingInstrumentation` was removed in version 6 of the SDK. If you're using custom navigation, use the `startIdleNavigationSpan` function. ```javascript {tabTitle:Direct} diff - const routingInstrumentation = new Sentry.RoutingInstrumentation(); @@ -176,9 +176,9 @@ Sentry.init({ }); ``` -### `beforeNavigate` replaced by `beforeStartSpan` +### `beforeNavigate` Replaced by `beforeStartSpan` -The `beforeNavigate` option was removed in the SDK version 6. Use the `beforeStartSpan` option instead. The `beforeStartSpan` option is a function that is 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. +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. ```javascript diff Sentry.init({ @@ -198,9 +198,9 @@ Sentry.init({ }); ``` -### `enableSpotlight` and `spotlightSidecarUrl` replaced by `spotlight` +### `enableSpotlight` and `spotlightSidecarUrl` Replaced by `spotlight` -The `enableSpotlight` and `spotlightSidecarUrl` options were removed in the SDK version 6. Use the `spotlight` option instead. +The `enableSpotlight` and `spotlightSidecarUrl` options were removed in version 6 of the SDK. Use the `spotlight` option instead. ```javascript diff import * as Sentry from '@sentry/react-native'; @@ -213,9 +213,9 @@ Sentry.init({ }); ``` -### React Native Tracing `idleTimeout` and `maxTransactionDuration` options were removed +### React Native Tracing `idleTimeout` and `maxTransactionDuration` Options Were Removed -The `idleTimeout` and `maxTransactionDuration` options were removed in the SDK version 6. Use the `idleTimeoutMs` and `finalTimeoutMs` options from the JavaScript SDK instead. +The `idleTimeout` and `maxTransactionDuration` options were removed in version 6 of the SDK. Use the `idleTimeoutMs` and `finalTimeoutMs` options from the JavaScript SDK instead. ```javascript diff import * as Sentry from '@sentry/react-native'; From 6f4bd7e8a075ce6c5466926c09e854b3cd905f5b Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Tue, 8 Oct 2024 17:48:01 +0200 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Liza Mock --- .../react-native/migration/v5-to-v6.mdx | 29 +++++++------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/docs/platforms/react-native/migration/v5-to-v6.mdx b/docs/platforms/react-native/migration/v5-to-v6.mdx index 01e7d519bf7d9..ad1a482710d1c 100644 --- a/docs/platforms/react-native/migration/v5-to-v6.mdx +++ b/docs/platforms/react-native/migration/v5-to-v6.mdx @@ -234,27 +234,20 @@ Sentry.init({ }); ``` -### Updated behaviour of `tracePropagationTargets` in React Native +### Updated Behavior of `tracePropagationTargets` in React Native -We updated the behaviour 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 tell the SDK, to which outgoing requests -tracing HTTP headers should be attached to. These tracing headers are used for distributed tracing. +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` were not defined, they defaulted to the following: -`['localhost', /^\/(?!\/)/]`. This meant that all request targets to 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. +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 is not set, +Going forward, when the `tracePropagationTargets` option isn't set: - tracing headers will be attached to all outgoing requests in React Native -- and to all outgoing on the same origin on the Browser (including WebViews). +- 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 (ie. will have trace headers attached). Requests to -`https://api.example.com/` will not, because it is on a different origin. The same goes for all applications running on -`localhost`. - -When you provide a `tracePropagationTargets` option, all of the entries you defined 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"`. +`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"`. From 72d250794b2c5b4997efbcc39b100f94732631c0 Mon Sep 17 00:00:00 2001 From: Krystof Woldrich <31292499+krystofwoldrich@users.noreply.github.com> Date: Tue, 15 Oct 2024 16:42:32 +0200 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Antonis Lilis Co-authored-by: LucasZF --- docs/platforms/react-native/migration/v5-to-v6.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/platforms/react-native/migration/v5-to-v6.mdx b/docs/platforms/react-native/migration/v5-to-v6.mdx index ad1a482710d1c..688c878db8e7e 100644 --- a/docs/platforms/react-native/migration/v5-to-v6.mdx +++ b/docs/platforms/react-native/migration/v5-to-v6.mdx @@ -4,11 +4,11 @@ sidebar_order: 100 description: "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 breaking because of the JavaScript SDK dependency upgrade to version 8 and because we've removed deprecated APIs and restructured npm package contents. +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. ## Important Changes In Dependencies -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 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](/platforms/javascript/migration/) 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. @@ -55,7 +55,7 @@ import Sentry from '@sentry/react-native'; import { useNavigationContainerRef } from 'expo-router'; - const reactNavigationIntegration = new Sentry.ReactNavigationInstrumentation(); -+ const reactNavigationIntegration = new Sentry.reactNavigationIntegration(); ++ const reactNavigationIntegration = Sentry.reactNavigationIntegration(); Sentry.init({ tracesSampleRate: 1.0, @@ -71,7 +71,7 @@ import Sentry from '@sentry/react-native'; import { NavigationContainer } from '@react-navigation/native'; - const reactNavigationIntegration = new Sentry.ReactNavigationInstrumentation(); -+ const reactNavigationIntegration = new Sentry.reactNavigationIntegration(); ++ const reactNavigationIntegration = Sentry.reactNavigationIntegration(); Sentry.init({ tracesSampleRate: 1.0, From ee89e99c070165bb86cdcdce978ead718375ce0f Mon Sep 17 00:00:00 2001 From: Krystof Woldrich Date: Tue, 15 Oct 2024 16:46:58 +0200 Subject: [PATCH 7/7] fix diffs --- docs/platforms/react-native/migration/sentry-expo.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/platforms/react-native/migration/sentry-expo.mdx b/docs/platforms/react-native/migration/sentry-expo.mdx index df6ec179017e8..579e6ece2fc06 100644 --- a/docs/platforms/react-native/migration/sentry-expo.mdx +++ b/docs/platforms/react-native/migration/sentry-expo.mdx @@ -46,14 +46,14 @@ pnpm add @sentry/react-native Replace all imports of `sentry-expo` with `@sentry/react-native`: -```diff {tabTitle:JavaScript} +```javascript {tabTitle:JavaScript} diff - import * as Sentry from 'sentry-expo'; + import * as Sentry from '@sentry/react-native'; ``` Replace `sentry-expo` exports `Browser` and `React` with `@sentry/react`: -```diff {tabTitle:JavaScript} +```javascript {tabTitle:JavaScript} diff - import { Browser, React } from 'sentry-expo'; + import * as Browser from '@sentry/react'; + import * as React from '@sentry/react'; @@ -61,7 +61,7 @@ Replace `sentry-expo` exports `Browser` and `React` with `@sentry/react`: Replace `sentry-expo` export `Native` with `@sentry/react-native`: -```diff {tabTitle:JavaScript} +```javascript {tabTitle:JavaScript} diff - import { Native } from 'sentry-expo'; + import * as Sentry from '@sentry/react-native'; ``` @@ -70,7 +70,7 @@ Replace `sentry-expo` export `Native` with `@sentry/react-native`: The `enableInExpoDevelopment` option is no longer supported. If you were using it, remove it and replace it with a `__DEV__` check, or leave the SDK enabled in development. -```diff {tabTitle:JavaScript} +```javascript {tabTitle:JavaScript} diff Sentry.init({ - enableInExpoDevelopment: true, + enabled: __DEV__,