CONTRIBUTING.md

Contributing

Thanks for your interest in contributing to sentry-react-native! This guide explains how we work with external contributions and how to get your environment set up. If you have questions, reach out on Discord.

This repository contains mono repository structure with multiple React Native and Expo project for development and testing.

Submitting Changes

TL;DR: Discuss your change in a GitHub issue before opening a pull request. We may close PRs that weren't discussed with a maintainer first.

Every line we merge is code we maintain long-term for hundreds of thousands of apps, so we want to agree on the problem and the approach before anyone writes code. This saves time for you and for us.

Before You Start

1. Find or create an issue. Search the issue tracker first. If nothing fits, open a new issue describing the problem or feature.
2. Discuss your approach with a maintainer. Comment on the issue with what you plan to change and wait for a maintainer to respond before you start working.
3. Check the assignee. If the issue is already assigned to someone else, coordinate with them in the issue before starting work.

Making Your Contribution

• Fork the repo and make your changes on a branch.
• Add tests. Non-trivial PRs won't be accepted without them.
• Don't bump version numbers. We do that when we release.
• Open a PR that links the issue (e.g. Fixes #123)
• Name your PR according to our commit message format.
• Keep PRs focused: one change per PR, no unrelated refactors.

AI Use

You are welcome to use whatever tools you prefer for making a contribution. However, any changes you propose have to be understood, reviewed and tested by you, a human, first, before you submit a pull request with them for the Sentry team to review. If we feel like that didn't happen, we will close the PR outright. For example, we won't review visibly AI-generated PRs from an agent instructed to look for and "fix" open issues in the repo. This aligns with our SDK principle: every line has an owner.

Overview

• / -> monorepo root private package
• /samples -> sample application, expo, rn...
• /packages -> RN SDK packages
• /dev-packages -> dev packages, ts-3.8 test runner, e2e tests components and runner

Setting up an Environment

We use Volta to ensure we use consistent versions of node and yarn.

sentry-react-native is a monorepo containing several packages, and we use lerna to manage them. To get started, install all dependencies, and then perform an initial build, so TypeScript can read all of the linked type definitions.

$ yarn
$ yarn build

With that, the repo is fully set up and you are ready to run all commands.

Watch mode, for development of the SDK core

cd packages/core yarn build:sdk:watch

## Testing

```sh
yarn test

# Or the watcher when writing tests:
cd packages/core
yarn test:watch

Public API Changes

We track the public API surface using @microsoft/api-extractor. A baseline report is committed at packages/core/etc/sentry-react-native.api.md. CI will fail if the public API changes without updating this file.

If your change modifies the public API (new exports, changed signatures, removed APIs):

yarn build:sdk
yarn api-report

Review the diff in packages/core/etc/sentry-react-native.api.md and commit the updated report alongside your code changes.

Running the sample

First, set up the Sentry CLI token. A recommended approach is to create a file named .env.sentry-build-plugin in the root folder of each sample and add:

SENTRY_AUTH_TOKEN=...

To obtain the correct token, log in to Sentry.io, then visit: https://docs.sentry.io/cli/configuration/#to-authenticate-manually From there, generate a token following the documentation.

Now we can go into the sample project, install and build it:

cd samples/react-native/

yarn start # Metro development server

npx pod-install
yarn ios # iOS Development build
yarn android # Android Development build

Recommended is to open the native project in samples/react-native/android and samples/react-native/ios on Android Studio and Xcode respectively.

Run the emulators (legacy-architecture):

For android switch newArchEnabled to false in android/gradle.properties. For iOS explicitly disable fabric in samples/react-native/ios/Podfile by setting :fabric_enabled => false before pod install.

yarn pod-install-debug-static-legacy
yarn react-native run-ios

yarn react-native run-android

# Release builds
yarn pod-install-release-static-legacy
yarn react-native run-ios --mode=Release

yarn react-native run-android --mode=release

Run the emulators (new-architecture):

yarn pod-install-debug-static
yarn react-native run-ios

yarn react-native run-android

# Release builds
yarn pod-install-release-static
yarn react-native run-ios --mode=Release

yarn react-native run-android --mode=Release

The pod-install-* scripts follow the pattern pod-install-{debug,release}-{static,dynamic}[-legacy] (dynamic variants build with frameworks as dynamic libraries). Since #6413, pod install downloads a prebuilt Sentry.xcframework from sentry-cocoa's GitHub release and vendors it, instead of building Sentry from source. Set SENTRY_USE_XCFRAMEWORK=0 before pod install to restore the previous source-build behavior (e.g. for offline builds).

Running the macOS sample

Head to the macOS sample root directory:

cd samples/react-native-macos/
yarn
bundle install
yarn pod-install-legacy
yarn start

You can now build and run the project from command line:

yarn react-native run-macos

or by openning the samples/react-native-macos/macos/sentry-react-native-sample.xcworkspace.

Note that the new architecture is not supported for the macOS sample at this point.

Develop with sentry-cocoa

Here are step on how to test your changes in sentry-cocoa with sentry-react-native. We assume you have both repositories cloned in siblings folders.

1. Build sentry-cocoa.

cd sentry-cocoa
make init

2. Link local sentry-cocoa build in sentry-react-native

cd sentry-react-native

Comment out sentry dependency in RNSentry.podspec.

-   s.dependency 'Sentry', '7.31.0'
+   s.dependency 'Sentry'

Add local pods to samples/react-native/ios/Podfile.

target 'sample' do

  # ... react native config

 pod 'Sentry', :path => '../../../../sentry-cocoa'
  # ... rest of the configuration

end

Develop with sentry-java

Here are step on how to test your changes in sentry-java with sentry-react-native. We assume that you have sentry-java setup, Android SDK installed, correct JAVA version etc.

1. Build and publish sentry-java locally.

cd sentry-java
make dryRelease
ls ~/.m2/repository/io/sentry/sentry-android # check that `sentry-java` was published

2. Add local maven to the sample project.

cd sentry-react-native/sample

Add local maven to samples/react-native/android/build.gradle.

allprojects {
    repositories {
        mavenLocal()
    }
}

Update sentry-android version, to the one locally published, in packages/core/android/build.gradle.

dependencies {
    implementation 'com.facebook.react:react-native:+'
-    api 'io.sentry:sentry-android:5.4.0'
+    api 'io.sentry:sentry-android:6.7.7-my-local-version'
}

Develop with sentry-android-gradle-plugin

Here are steps on how to debug the gradle builds process with sentry-android-gradle-plugin. We assume that you have sentry-android-gradle-plugin setup, Android SDK installed, correct JAVA version etc.

1. Add the following code to samples/react-native/android/settings.gradle, this ensure the plugin builds at the beginning of the application build:

includeBuild('../../../../sentry-android-gradle-plugin/plugin-build') {
  dependencySubstitution {
    substitute(module 'io.sentry:sentry-android-gradle-plugin') using project(':')
  }
}

../../../../sentry-android-gradle-plugin/plugin-build this example works if sentry-react-native and sentry-android-gradle-plugin are sibling directories.

2. Open samples/react-native/android in Android Studio.
3. Add Remote JVM Debug configuration (keep all defaults).
4. Run build command with -Dorg.gradle.debug=true and --no-daemon, example:

./gradlew assembleRelease -Dorg.gradle.debug=true --no-daemon

5. The build command will wait for the debugger connection, go to the Android Studio and select the newly created Remote JVM Debug configuration and click Debug.
6. The build process will stop on active breakpoint.