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

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

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:

`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.
    autoInstallation {
      enabled = false
    }
}
```