From c865a3e7bda19dac73d611279114959bfbeb82dc Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Wed, 29 Apr 2026 14:29:58 +0200 Subject: [PATCH 1/3] docs(react-native): Clarify release alignment for native auto-init Rewrite the Options Merging alert to explain that pre-JS crashes use only sentry.options.json values, not JS overrides. Add a Setting Release and Distribution section with guidance on keeping native and JS release values aligned via SENTRY_RELEASE/SENTRY_DIST env vars. Co-Authored-By: Claude --- .../manual-setup/app-start-error-capture.mdx | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx index 06b94749e20a65..96edeb8fd19899 100644 --- a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx +++ b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx @@ -36,7 +36,9 @@ Create a `sentry.options.json` file in your React Native project root with the s -Options from `sentry.options.json` are merged with options from `Sentry.init()` in JavaScript. Options specified in JavaScript take precedence over the configuration file, allowing you to override settings at runtime. +When `Sentry.init()` runs in JavaScript, the native SDK is re-initialized with the JS options merged on top of the file options. This means JavaScript options take precedence for events captured **after** JS loads. + +However, crashes and errors that occur **before** JavaScript loads (which is the purpose of this feature) are captured using only the values from `sentry.options.json` and native auto-detection. If you set a custom `release` or `dist` in `Sentry.init()`, make sure the same values are also in `sentry.options.json`. Otherwise, pre-JS crashes will be attributed to a different release than post-JS events. See [Setting Release and Distribution](#setting-release-and-distribution) for details. @@ -50,6 +52,30 @@ SENTRY_ENVIRONMENT=staging npx react-native run-android This works in any CI/CD system by setting the environment variable in your build configuration. +### Setting Release and Distribution + +If you use a custom `release` or `dist` in `Sentry.init()`, you should set matching values in `sentry.options.json` so that pre-JavaScript crashes are attributed to the correct release: + +```json {filename:sentry.options.json} +{ + "dsn": "https://key@example.io/value", + "release": "my-app@1.0.0+42", + "dist": "42" +} +``` + +For dynamic values that change per build, you can generate `sentry.options.json` as a build step or use the `SENTRY_RELEASE` and `SENTRY_DIST` environment variables at build time. The SDK build scripts will use these to override the values in your `sentry.options.json`, similar to how `SENTRY_ENVIRONMENT` works. + +```bash +SENTRY_RELEASE="my-app@1.0.0+42" SENTRY_DIST="42" npx react-native run-ios +``` + + + +If the `release` or `dist` in `sentry.options.json` doesn't match what you pass to `Sentry.init()`, you'll see two separate releases in Sentry — one for native crashes captured before JS loads and another for events captured after. Make sure both sources use the same values. + + + ## Android Setup Initialize Sentry in your `MainApplication` class: From 7f38ed61e92140b9f6a1d97a9ad68b10b5a2ecf8 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Wed, 29 Apr 2026 14:32:06 +0200 Subject: [PATCH 2/3] docs(react-native): Remove SENTRY_RELEASE/SENTRY_DIST env var docs Remove env var override content that depends on unreleased SDK changes. This will be added in a follow-up PR. Co-Authored-By: Claude --- .../react-native/manual-setup/app-start-error-capture.mdx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx index 96edeb8fd19899..305f59960ad17e 100644 --- a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx +++ b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx @@ -38,7 +38,7 @@ Create a `sentry.options.json` file in your React Native project root with the s When `Sentry.init()` runs in JavaScript, the native SDK is re-initialized with the JS options merged on top of the file options. This means JavaScript options take precedence for events captured **after** JS loads. -However, crashes and errors that occur **before** JavaScript loads (which is the purpose of this feature) are captured using only the values from `sentry.options.json` and native auto-detection. If you set a custom `release` or `dist` in `Sentry.init()`, make sure the same values are also in `sentry.options.json`. Otherwise, pre-JS crashes will be attributed to a different release than post-JS events. See [Setting Release and Distribution](#setting-release-and-distribution) for details. +However, crashes and errors that occur **before** JavaScript loads (which is the purpose of this feature) are captured using only the values from `sentry.options.json` and native auto-detection. If you set a custom `release` or `dist` in `Sentry.init()`, make sure the same values are also in `sentry.options.json`. Otherwise, pre-JS crashes will be attributed to a different release than post-JS events. @@ -64,12 +64,6 @@ If you use a custom `release` or `dist` in `Sentry.init()`, you should set match } ``` -For dynamic values that change per build, you can generate `sentry.options.json` as a build step or use the `SENTRY_RELEASE` and `SENTRY_DIST` environment variables at build time. The SDK build scripts will use these to override the values in your `sentry.options.json`, similar to how `SENTRY_ENVIRONMENT` works. - -```bash -SENTRY_RELEASE="my-app@1.0.0+42" SENTRY_DIST="42" npx react-native run-ios -``` - If the `release` or `dist` in `sentry.options.json` doesn't match what you pass to `Sentry.init()`, you'll see two separate releases in Sentry — one for native crashes captured before JS loads and another for events captured after. Make sure both sources use the same values. From 6244a1af49a0ddf796f5a64387ef8dae33cd0d68 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Wed, 29 Apr 2026 17:07:59 +0200 Subject: [PATCH 3/3] docs(react-native): Document SENTRY_RELEASE and SENTRY_DIST env var support for sentry.options.json Documents the build-time env var override for release and dist in the app-start-error-capture guide, including the EAS Build example. Depends on getsentry/sentry-react-native#6069 Co-Authored-By: Claude Opus 4.6 --- .../manual-setup/app-start-error-capture.mdx | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx index 305f59960ad17e..4737d37812f1f8 100644 --- a/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx +++ b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx @@ -64,6 +64,12 @@ If you use a custom `release` or `dist` in `Sentry.init()`, you should set match } ``` +For dynamic values that change per build, set the `SENTRY_RELEASE` and `SENTRY_DIST` environment variables at build time. The SDK build scripts will use these to override the values in your `sentry.options.json`, similar to how `SENTRY_ENVIRONMENT` works. + +```bash +SENTRY_RELEASE="my-app@1.0.0+42" SENTRY_DIST="42" npx react-native run-ios +``` + If the `release` or `dist` in `sentry.options.json` doesn't match what you pass to `Sentry.init()`, you'll see two separate releases in Sentry — one for native crashes captured before JS loads and another for events captured after. Make sure both sources use the same values. @@ -184,16 +190,22 @@ When `useNativeInit` is set to `true`, the Expo plugin automatically: You can set the `environment` using the plugin `options` property as shown above, or using the `SENTRY_ENVIRONMENT` environment variable. The environment variable takes precedence over the plugin option. -For per-environment builds with EAS Build, set `SENTRY_ENVIRONMENT` in your build profiles: +For per-environment builds with EAS Build, set `SENTRY_ENVIRONMENT` in your build profiles. You can also set `SENTRY_RELEASE` and `SENTRY_DIST` if you use custom release names: ```json {filename:eas.json} { "build": { "production": { - "env": { "SENTRY_ENVIRONMENT": "production" } + "env": { + "SENTRY_ENVIRONMENT": "production", + "SENTRY_RELEASE": "my-app@1.0.0+42", + "SENTRY_DIST": "42" + } }, "staging": { - "env": { "SENTRY_ENVIRONMENT": "staging" } + "env": { + "SENTRY_ENVIRONMENT": "staging" + } } } }