Skip to content

manual-setup.mdx

Latest commit

 

History

History
224 lines (159 loc) · 8.73 KB

manual-setup.mdx

File metadata and controls

224 lines (159 loc) · 8.73 KB
title Manual Configuration
description Learn about manual configuration for iOS and Android.
sidebar_order 3

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

Install SDK Package

Install the @sentry/react-native package:

npm install @sentry/react-native --save
yarn add @sentry/react-native
pnpm add @sentry/react-native

iOS

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 Privacy Manifest

The SDK needs access to certain information about the device and the application for its essential functionality. Some of the APIs required for this are considered privacy-relevant. Add the privacy manifest to your Xcode project to ensure your app is compliant with Apple's guidelines. Read the Apple Privacy Manifest guide for more info on how to add records required for the Sentry SDKs.

Add sentry.properties

Add a sentry.properties file to your ios directory.

defaults.url=https://sentry.io/
defaults.org=___ORG_SLUG___
defaults.project=___PROJECT_SLUG___
auth.token=___ORG_AUTH_TOKEN___

Configure Automatic Source Maps Upload

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

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:

set -e

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

# RN 0.81.1+
/bin/sh -c "$WITH_ENVIRONMENT $SENTRY_XCODE"

# RN 0.69 - 0.80.0
# BUNDLE_REACT_NATIVE="/bin/sh $SENTRY_XCODE"
# /bin/sh -c "$WITH_ENVIRONMENT \"$BUNDLE_REACT_NATIVE\""

# RN 0.46 – 0.68
# BUNDLE_REACT_NATIVE="/bin/sh $SENTRY_XCODE"
# /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:

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"

export SENTRY_PROJECT_ROOT="/path/to/packages/mobile" # Override project root for monorepo setups

If you're using a monorepo (for example, NX or Turborepo), the script may resolve the project root incorrectly due to symlinked node_modules. Set SENTRY_PROJECT_ROOT to the absolute path of your React Native package to fix build failures caused by incorrect path resolution.

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.

Configure Automatic Debug Symbols Upload

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

/bin/sh ../node_modules/@sentry/react-native/scripts/sentry-xcode-debug-files.sh

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

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="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_DEBUG_FILES_UPLOAD_EXTRA_ARGS="--extra --flags"

export SENTRY_PROJECT_ROOT="/path/to/packages/mobile" # Override project root for monorepo setups

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

Using Node With nvm or Volta

If you're using nvm or Volta, Xcode may have trouble locating the default node binary. The suggested workaround in this troubleshooting example can help.

Android

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 sentry.properties

Add a sentry.properties file to your android directory.

defaults.url=https://sentry.io/
defaults.org=___ORG_SLUG___
defaults.project=___PROJECT_SLUG___
auth.token=___ORG_AUTH_TOKEN___

Enable Gradle Integration

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

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

To change the default behavior, you can pass the following Sentry Gradle Integration options and environmental variables:

export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable source maps upload

export SENTRY_DIST=1234
export SENTRY_RELEASE=app@1.0.0
project.ext.sentryCli = [
    logLevel: "debug" // Enable verbose debug output
    sentryProperties: "path/to/sentry.properties",
    flavorAware: false, // When enabled looks for sentry-{flavor}-{build_type}.properties
    modulesPaths: [
      "node_modules",
      "../node_modules",
    ],
    skipCollectModules: false,

    collectModulesScript: "path/to/node_modules/@sentry/react-native/dist/js/tools/collectModules.js",
    copyDebugIdScript: "path/to/node_modules/@sentry/react-native/scripts/copy-debugid.js",
    hasSourceMapDebugIdScript: "path/to/node_modules/@sentry/react-native/scripts/has-sourcemap-debugid.js",
]

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

Enable Sentry AGP

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

buildscript {
    dependencies {
        // Other dependencies ...
        classpath("io.sentry:sentry-android-gradle-plugin:{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}")
    }
}

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

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
    }
}