Manual Configuration

If you can’t (or prefer not to) run the automatic setup, use the instructions below to configure your application.

Install the @sentry/react-native package:

Copied
npm install --save @sentry/react-native

For iOS, the Sentry SDK wraps the React Native bundle process to upload source maps automatically. The SDK also adds a new Xcode Build Phase to upload debug symbols to ensure you get readable stack traces for your native crashes.

Add a sentry.properties file to your ios directory.

ios/sentry.properties
Copied
defaults.url=https://sentry.io/
defaults.org=example-org
defaults.project=example-project
auth.token=sntrys_YOUR_TOKEN_HERE

We modify the React Native build phase (“Bundle React Native code and images”) slightly from this:

Bundle React Native code and images
Copied
set -e

WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"

To this:

Bundle React Native code and images
Copied
set -e

WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"
SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh"
BUNDLE_REACT_NATIVE="/bin/sh $SENTRY_XCODE $REACT_NATIVE_XCODE"

# RN 0.69+
/bin/sh -c "$WITH_ENVIRONMENT \"$BUNDLE_REACT_NATIVE\""

# RN 0.46 – 0.68
# /bin/sh -c "$BUNDLE_REACT_NATIVE"

To change the default behavior, pass the following environment variables in .xcode.env or in the Build Phase script:

.xcode.env
Copied
export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable source map upload

export AUTO_RELEASE=true # Automatically detect release from Xcode project
export SENTRY_CLI_EXECUTABLE="path/to/@sentry/cli/bin/sentry-cli"
export SENTRY_CLI_EXTRA_ARGS="--extra --flags" # Extra arguments for sentry-cli in all build phases
export SENTRY_CLI_RN_XCODE_EXTRA_ARGS="--extra --flags"

export SOURCE_MAP_PATH="path/to/source-maps" # From where collect-modules should read modules
export SENTRY_COLLECT_MODULES="path/to/collect-modules.sh"
export MODULES_PATHS="../node_modules,../my-custom-module"

By default, uploading of source maps for debug simulator builds is disabled for speed reasons. If you want to generate source maps for debug builds, you can pass --allow-fetch as a parameter to SENTRY_CLI_RN_XCODE_EXTRA_ARGS in the above mentioned script.

To upload debug symbols to Sentry, create a new Run Script build phase using the following script:

Upload Debug Symbols to Sentry
Copied
export SENTRY_PROPERTIES=sentry.properties

[[ $SENTRY_INCLUDE_NATIVE_SOURCES == "true" ]] && INCLUDE_SOURCES_FLAG="--include-sources" || INCLUDE_SOURCES_FLAG=""
SENTRY_CLI="../node_modules/@sentry/cli/bin/sentry-cli"
$SENTRY_CLI debug-files upload "$INCLUDE_SOURCES_FLAG" "$DWARF_DSYM_FOLDER_PATH"

To change the default behavior, you can pass the following environment variables in .xcode.env or in the Build Phase script:

.xcode.env
Copied
export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable debug symbols upload

export SENTRY_INCLUDE_NATIVE_SOURCES=true # Upload native iOS sources
export SENTRY_CLI_EXECUTABLE="paht/to/@sentry/cli/bin/sentry-cli"
export SENTRY_CLI_EXTRA_ARGS="--extra --flags" # Extra arguments for sentry-cli in all build phases
export SENTRY_CLI_DEBUG_FILES_UPLOAD_EXTRA_ARGS="--extra --flags"

For more information about what options to use in SENTRY_CLI_DEBUG_FILES_UPLOAD_EXTRA_ARGS visit the Sentry CLI Apple Debug Symbols documentation.

To link the native library via CocoaPods, link to the native module in your Podfile. In React Native versions 0.60 and above, the podspec should be automatically linked. If isn't, you can link to the native module manually by adding the RNSentry.podspec to your Podfile as follows:

Copied
pod 'RNSentry', :path => '../node_modules/@sentry/react-native/RNSentry.podspec'

If you are using nvm or Volta, Xcode has trouble locating the default node binary, which can look similar to the troubleshooting example.

For Android, we hook into Gradle for the source map build process. When you run npx @sentry/wizard@latest -i reactNative, the Gradle files are automatically updated. If you can't or don't want to do that, you can follow the steps below to update the files.

Add a sentry.properties file to your android directory.

android/sentry.properties
Copied
defaults.url=https://sentry.io/
defaults.org=example-org
defaults.project=example-project
auth.token=sntrys_YOUR_TOKEN_HERE

We enable the Gradle integration in your android/app/build.gradle file by adding the following line before the android options:

android/app/build.gradle
Copied
apply from: "../../node_modules/@sentry/react-native/sentry.gradle"

You can enable native symbol upload and other features by adding the Sentry Android Gradle Plugin (AGP) dependency to android/build.gradle.

android/build.gradle
Copied
buildscript {
    dependencies {
        // Other dependencies ...
        classpath("io.sentry:sentry-android-gradle-plugin:4.3.1")
    }
}

You can configure the plugin options in android/app/build.gradle, as shown below:

android/app/build.gradle
Copied
apply plugin: "io.sentry.android.gradle"

sentry {
    // Enables or disables the automatic configuration of Native Symbols
    // for Sentry. This executes sentry-cli automatically so
    // you don't need to do it manually.
    // Default is disabled.
    uploadNativeSymbols = true

    // Enables or disables the automatic upload of the app's native source code to Sentry.
    // This executes sentry-cli with the --include-sources param automatically so
    // you don't need to do it manually.
    // This option has an effect only when [uploadNativeSymbols] is enabled.
    // Default is disabled.
    includeNativeSources = true

    // `@sentry/react-native` ships with compatible `sentry-android`
    // This option would install the latest version that ships with the SDK or SAGP (Sentry Android Gradle Plugin)
    // which might be incompatible with the React Native SDK
    // Enable auto-installation of Sentry components (sentry-android SDK and okhttp, timber and fragment integrations).
    // Default is enabled.
    autoInstallation {
      enabled = false
    }
}

You can also enable logging for sentry-cli by adding this config before the above apply from: line:

android/app/build.gradle
Copied
project.ext.sentryCli = [
    logLevel: "debug"
]

apply from: "../../node_modules/@sentry/react-native/sentry.gradle"

We also support fetching different sentry.properties files for different flavors. For that, you need to add:

android/app/build.gradle
Copied
project.ext.sentryCli = [
    logLevel: "debug",
    flavorAware: true
]

apply from: "../../node_modules/@sentry/react-native/sentry.gradle"

The corresponding flavor files should also be placed within the specific build type folder where you intend to use them. For example, the "Android demo release" flavor would be react-native/android/sentry-demo-release.properties.

We recommend leaving logLevel: "debug" since we look for specific sentry.properties files depending on your flavor's name.

Include the project by adding it to your dependency list in android/app/build.gradle:

android/app/build.gradle
Copied
dependencies {
    // ... other dependencies listed here //
    implementation project(':@sentry_react-native')
}

If you're linking manually, make sure your MainApplication.java is similar to:

Copied
import io.sentry.react.RNSentryPackage;

public class MainApplication extends Application implements ReactApplication {

    @Override
    protected List<ReactPackage> getPackages() {
      List<ReactPackage> packages = new PackageList(this).getPackages();
      packages.add(new RNSentryPackage());
      return packages;
    }
}

Add the following to your settings.gradle file:

android/settings.gradle
Copied
include ':@sentry_react-native'
project(':@sentry_react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@sentry/react-native/android')
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").