Expo Datadog

The Expo Datadog plugin (expo-datadog) is an Expo Config Plugin that automates the setup of crash reporting and error tracking for your Expo application. It ensures that all required debug artifacts—such as dSYMs, Proguard/R8 mapping files, and JavaScript sourcemaps—are automatically uploaded to Datadog during the build process.

To accomplish this, the plugin applies platform-specific build integrations:

iOS

• Adds an Xcode build phase to upload dSYMs using datadog-ci dsyms upload
• Modifies the "Bundle React Native code and images" build phase to upload sourcemaps using datadog-ci react-native xcode

Android

• Adds the Datadog Gradle plugin (com.datadoghq.dd-sdk-android-gradle-plugin)
• Configures automatic Proguard/R8 mapping file uploads after minification
• Applies the datadog-sourcemaps.gradle script to upload JavaScript sourcemaps

Setup

Note: Make sure you've set up and initialized the Datadog React Native SDK before using this plugin.

Prerequisites

Install the required peer dependencies:

npm install @datadog/mobile-react-native expo-datadog

or with Yarn:

yarn add @datadog/mobile-react-native expo-datadog

You also need @datadog/datadog-ci for uploading symbols:

npm install --save-dev @datadog/datadog-ci

Configure the Plugin

Add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": ["expo-datadog"]
  }
}

Configure Datadog CI

Create a datadog-ci.json file at the root of your project to configure the Datadog CI tool for uploading symbols and sourcemaps:

{
  "apiKey": "<YOUR_DATADOG_API_KEY>",
  "datadogSite": "datadoghq.com"
}

datadog-ci.json Properties

Property	Type	Default	Description
apiKey	string	required	Your Datadog API key
datadogSite	string	"datadoghq.com"	The Datadog site to upload symbols to

Available Datadog Sites

Site	URL
US1	datadoghq.com
US3	us3.datadoghq.com
US5	us5.datadoghq.com
EU1	datadoghq.eu
AP1	ap1.datadoghq.com
AP2	ap2.datadoghq.com
US1-FED	ddog-gov.com

Alternatively, you can set these values as environment variables:

export DATADOG_API_KEY=<your-api-key>
export DATADOG_SITE=datadoghq.com

Configuration Options

All configuration properties are optional. By default, all upload features are enabled.

Property	Type	Default	Description
iosDsyms	boolean	true	Whether iOS dSYMs upload is enabled
iosSourcemaps	boolean	true	Whether iOS sourcemaps upload is enabled
androidProguardMappingFiles	boolean	true	Whether Android Proguard mapping files upload is enabled
androidSourcemaps	boolean	true	Whether Android sourcemaps upload is enabled
serviceName	string	app bundle identifier	Service name used when uploading sourcemaps (both iOS and Android)
datadogGradlePluginVersion	string	"1.14.0"	Version of dd-sdk-android-gradle-plugin for Proguard mapping uploads

Environment Variables

Variable	Description
NODE_BINARY	Path to Node.js binary, used in iOS build phases
DATADOG_CI_EXEC	Path to the datadog-ci executable (auto-detected if not set)
DATADOG_API_KEY	Your Datadog API key (can be set in datadog-ci.json instead)
DATADOG_SITE	Your Datadog site (can be set in datadog-ci.json instead)

Platform-Specific Setup

iOS Setup

The plugin automatically configures Xcode build phases to upload dSYMs and sourcemaps. For the build phases to work correctly, ensure that:

1. Your .xcode.env or .xcode.env.local file contains the NODE_BINARY path:

# .xcode.env.local
export NODE_BINARY=$(command -v node)

2. Create a datadog-ci.json file at the root of your project (see Configure Datadog CI), or set your Datadog API key as an environment variable before building:

export DATADOG_API_KEY=<your-api-key>

Android Setup

Enabling Proguard Mapping File Uploads

To upload native Android debug symbols (Proguard/R8 mapping files), you must enable minification in your release builds. Add the following to your android/gradle.properties:

android.enableMinifyInReleaseBuilds=true

Without this setting, no mapping files are generated and the androidProguardMappingFiles option has no effect.

Datadog API Key

Create a datadog-ci.json file at the root of your project (see Configure Datadog CI), or set your Datadog API key in your android/gradle.properties or as an environment variable:

DATADOG_API_KEY=<your-api-key>

Configuration Examples

Full Configuration with All Options

{
  "expo": {
    "plugins": [
      [
        "expo-datadog",
        {
          "errorTracking": {
            "iosDsyms": true,
            "iosSourcemaps": true,
            "androidProguardMappingFiles": true,
            "androidSourcemaps": true,
            "serviceName": "com.mycompany.myapp",
            "datadogGradlePluginVersion": "1.22.0"
          }
        }
      ]
    ]
  }
}

Build Workflow

After configuring the plugin, run expo prebuild to generate the native projects with Datadog configuration:

Important

These commands create proper release builds and trigger Datadog uploads, but they do not automatically upload your app to App Store Connect or Google Play.

# Generate native projects
npx expo prebuild

# Build for iOS
npx expo run:ios --configuration Release

# Build for iOS (alternative using xcodebuild)
cd ios && xcodebuild -workspace <YourApp>.xcworkspace -scheme <YourApp> -configuration Release -sdk iphoneos

# Build for Android
npx expo run:android --variant release

# Build for Android (alternative using Gradle directly)
cd android && DATADOG_API_KEY=<your-api-key> ./gradlew assembleRelease

Note for EAS Build: When using EAS Build, set your DATADOG_API_KEY as a secret in your EAS project settings:

eas secret:create --name DATADOG_API_KEY --value <your-api-key>

Troubleshooting

Node binary not found when using NVM

When using NVM (Node Version Manager), the Xcode build phase may not find your Node installation. To fix this, create an ios/.xcode.env.local file (this file is gitignored by default):

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
export NODE_BINARY=$(command -v node)

Android: "No such remote 'origin'" error

If you encounter the following error during Android builds:

> Task :app:uploadMappingRelease FAILED
error: No such remote 'origin'

This occurs because the Datadog Gradle plugin expects a git repository with a remote configured. To fix this, initialize a git repository and add a remote:

git init
git remote add origin <your-repository-url>

iOS: dSYMs upload failing

If dSYM uploads fail, ensure that:

1. Your datadog-ci.json file exists at the project root with valid credentials
2. The DATADOG_API_KEY environment variable is set if not using datadog-ci.json
3. Your build is generating dSYMs (check Build Settings → Debug Information Format is set to "DWARF with dSYM File")

Android: Sourcemaps not uploading

Ensure that:

1. You have @datadog/datadog-ci installed as a dev dependency
2. Your datadog-ci.json file or environment variables are correctly configured
3. You're building a release variant (sourcemaps are not uploaded for debug builds)

Contributing

If you find an issue with this package and have a fix, please consult the Contributing Guidelines.

Further Reading

• Expo and Expo Go documentation
• Expo Crash Reporting and Error Tracking documentation
• Datadog CI Configuration