---
title: "Manual Configuration"
description: "Learn about manual configuration for iOS and Android."
url: https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup/
---

# Manual Configuration | Sentry for React Native

If you can't (or prefer not to) run the [automatic setup](https://docs.sentry.io/platforms/react-native.md), use the instructions below to configure your application.

## [Install SDK Package](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#install-sdk-package)

Install the `@sentry/react-native` package:

```bash
npm install @sentry/react-native --save
```

## [iOS](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#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](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#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](https://docs.sentry.io/platforms/react-native/data-management/apple-privacy-manifest.md) guide for more info on how to add records required for the Sentry SDKs.

### [Add `sentry.properties`](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#add-sentryproperties)

Add a `sentry.properties` file to your `ios` directory.

`ios/sentry.properties`

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

### [Configure Automatic Source Maps Upload](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#configure-automatic-source-maps-upload)

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

`Bundle React Native code and images`

```bash
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`

```bash
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:

`.xcode.env`

```bash
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](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#configure-automatic-debug-symbols-upload)

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

`Upload Debug Symbols to Sentry`

```bash
/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:

`.xcode.env`

```bash
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](https://docs.sentry.io/platforms/apple/dsym.md#sentry-cli) documentation.

### [Using Node With nvm or Volta](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#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](https://docs.sentry.io/platforms/react-native/troubleshooting.md#using-node-with-nvm-or-volta) can help.

## [Android](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#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`](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#add-sentryproperties-1)

Add a `sentry.properties` file to your `android` directory.

`android/sentry.properties`

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

### [Enable Gradle Integration](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#enable-gradle-integration)

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`

```groovy
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:

```bash
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
```

### [Enable Sentry AGP](https://docs.sentry.io/platforms/react-native/manual-setup/manual-setup.md#enable-sentry-agp)

You can enable native symbol upload and other features by adding the [Sentry Android Gradle Plugin (AGP)](https://docs.sentry.io/platforms/android/configuration/gradle.md) dependency to `android/build.gradle`.

`android/build.gradle`

```groovy
buildscript {
    dependencies {
        // Other dependencies ...
        classpath("io.sentry:sentry-android-gradle-plugin:6.4.0")
    }
}
```

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

##### Auto-Installation Must Be Disabled

The `autoInstallation` option **must** be set to `false` when using the Sentry Android Gradle Plugin with React Native. The `@sentry/react-native` SDK manages its own `sentry-android` dependency. If auto-installation is enabled, the plugin may pull in a different `sentry-android` version, causing an `IllegalStateException: Sentry SDK has detected a mix of versions` crash at app startup.

`android/app/build.gradle`

```groovy
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.
    // IMPORTANT: Must be false for React Native.
    autoInstallation {
      enabled = false
    }
}
```