Upload source maps for React Native

Install posthog-cli:

npm install -g @posthog/cli

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/PostHog/posthog/releases/latest/download/posthog-cli-installer.sh | sh
posthog-cli-update

To authenticate the CLI, call the login command. This opens your browser where you select your organization, project, and API scopes to grant:

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions, you can set environment variables to authenticate:

You can also use the --host option instead of the POSTHOG_CLI_HOST environment variable to target a different PostHog instance or region. For EU users:

posthog-cli --host https://eu.posthog.com [CMD]

Create or update the metro.config.js file in your app's root directory so that it looks like this:

-const { getDefaultConfig } = require("expo/metro-config");
+const { getPostHogExpoConfig } = require('posthog-react-native/metro')

-const config = getDefaultConfig(__dirname);
+const config = getPostHogExpoConfig(__dirname)

module.exports = config

Automatic source map uploading is handled through the Gradle build process on Android and the Xcode build process on iOS.

# After running `eas update` or `npx expo export --dump-sourcemap`, upload source maps from the output directory
posthog-cli hermes upload --directory dist

1. Expo: Update the app.json file in your app's root directory.

Expo Plugins that add modifications can only be used with prebuilding and managed EAS Build.

If you can use the posthog-react-native/expo plugin, skip steps 2 and 3. If not, proceed with steps 2 and 3.

Add the posthog-react-native/expo plugin under the expo.plugins.

{
  "expo": {
    ...
    "plugins": [
      ...
+     "posthog-react-native/expo"
    ]
  }
}

The plugin accepts the following options:

Example opting out of the sandbox change:

{
  "expo": {
    "plugins": [
      ["posthog-react-native/expo", { "disableSandboxing": false }]
    ]
  }
}

2. Android: Update the /android/app/build.gradle file from your app's root directory so that it looks like this:

...

// This must be placed directly above the following `android` block.
+apply from: new File(["node", "--print", "require('path').join(require('path').dirname(require.resolve('posthog-react-native')), '..', 'tooling', 'posthog.gradle')"].execute().text.trim())

android {
  ...
}

3. iOS: Update the /ios/$yourProjectName.xcodeproj/project.pbxproj file (replace $yourProjectName with your project's actual name). You need to locate the Bundle React Native code and images build step.

To do this through Xcode, open your project in Xcode, go to the project settings, navigate to Build Phases, select Bundle React Native code and images, and apply the changes shown below.

...

-`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`
+/bin/sh `"$NODE_BINARY" --print "require('path').join(require('path').dirname(require.resolve('posthog-react-native')), '..', 'tooling', 'posthog-xcode.sh')"` `"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`

If you are not using the Expo plugin (step 1), you will need to also disable User Script Sandboxing for the upload script to work. In Xcode, go to Build Settings, search for User Script Sandboxing (ENABLE_USER_SCRIPT_SANDBOXING) and set it to No. This is required because the script needs to read .git/ for release metadata and execute posthog-cli, which are not allowed under Xcode's script sandbox.