From 1a0779e4e851b4df78449f706885e04e1a8716f2 Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 27 Jan 2026 11:00:18 +0100 Subject: [PATCH 1/2] RN: Capture Startup Crashes --- .../manual-setup/app-start-error-capture.mdx | 150 ++++++++++++++++++ .../react-native/manual-setup/native-init.mdx | 7 +- 2 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 docs/platforms/react-native/manual-setup/app-start-error-capture.mdx 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 new file mode 100644 index 00000000000000..cfa7a52a110d78 --- /dev/null +++ b/docs/platforms/react-native/manual-setup/app-start-error-capture.mdx @@ -0,0 +1,150 @@ +--- +title: Capture App Start Errors (v8+) +sidebar_order: 3 +description: "Learn how to capture app start errors and crashes that occur before JavaScript loads using native initialization." +--- + + + +Sentry React Native SDK v8 is currently in alpha testing. This feature is available for early adopters and may undergo changes before the stable release. + + + +By default, the React Native SDK initializes the native SDK underneath the `init` method called on the JS layer. As a result, the SDK has a current limitation of not capturing native crashes that occur prior to the `init` method being called on the JS layer. + +Starting with SDK version 8.0.0, you can initialize Sentry natively before JavaScript loads, enabling capture of app start errors and crashes that occur during: + +- Native module initialization +- JavaScript bundle loading +- Early React Native bridge setup + +This feature uses a `sentry.options.json` configuration file and native initialization APIs that read from this file. + + + +This feature requires Sentry React Native SDK version 8.0.0 or higher. + + + +## Configuration File + +Create a `sentry.options.json` file in your React Native project root with the same options you currently have in `Sentry.init`: + +```json {filename:sentry.options.json} +{ + "dsn": "https://key@example.io/value", + "debug": true, + "environment": "production", + "tracesSampleRate": 1.0, + "enableTracing": true +} +``` + + + +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. + + + +## Android Setup + +Initialize Sentry in your `MainApplication` class: + +```kotlin {filename:android/app/src/main/java/.../MainApplication.kt} +import io.sentry.react.RNSentrySDK + +class MainApplication : Application(), ReactApplication { + override fun onCreate() { + super.onCreate() + RNSentrySDK.init(this) + // ... rest of your initialization code + } +} +``` + +You can also provide additional configuration options: + +```kotlin {filename:android/app/src/main/java/.../MainApplication.kt} +import io.sentry.react.RNSentrySDK +import io.sentry.android.core.SentryAndroidOptions + +class MainApplication : Application(), ReactApplication { + override fun onCreate() { + super.onCreate() + RNSentrySDK.init(this) { options -> + // Additional configuration that can't be serialized in JSON + options.beforeSend = { event, hint -> + // Custom beforeSend logic + event + } + } + // ... rest of your initialization code + } +} +``` + +## iOS Setup + +Initialize Sentry in your `AppDelegate`: + +```objective-c {filename:ios/YourApp/AppDelegate.mm} +#import + +@implementation AppDelegate + +- (BOOL)application:(UIApplication *)application + didFinishLaunchingWithOptions:(NSDictionary *)launchOptions +{ + [RNSentrySDK start]; + return [super application:application didFinishLaunchingWithOptions:launchOptions]; +} + +@end +``` + +You can also provide additional configuration options: + +```objective-c {filename:ios/YourApp/AppDelegate.mm} +#import + +@implementation AppDelegate + +- (BOOL)application:(UIApplication *)application + didFinishLaunchingWithOptions:(NSDictionary *)launchOptions +{ + [RNSentrySDK startWithConfigureOptions:^(SentryOptions *options) { + // Additional configuration that can't be serialized in JSON + options.beforeSend = ^SentryEvent*(SentryEvent *event, SentryHint *hint) { + // Custom beforeSend logic + return event; + }; + }]; + return [super application:application didFinishLaunchingWithOptions:launchOptions]; +} + +@end +``` + +## Expo Setup + +If you're using Expo, you can enable native initialization automatically using the Expo plugin: + +```json {filename:app.json} +{ + "expo": { + "plugins": [ + [ + "@sentry/react-native/expo", + { + "useNativeInit": true + } + ] + ] + } +} +``` + +When `useNativeInit` is set to `true`, the Expo plugin automatically: +- Creates `sentry.options.json` from your Expo config +- Adds `RNSentrySDK.init()` to your Android `MainApplication` +- Adds `RNSentrySDK.start()` to your iOS `AppDelegate` diff --git a/docs/platforms/react-native/manual-setup/native-init.mdx b/docs/platforms/react-native/manual-setup/native-init.mdx index b35d65e786ee86..02c96e83b6792b 100644 --- a/docs/platforms/react-native/manual-setup/native-init.mdx +++ b/docs/platforms/react-native/manual-setup/native-init.mdx @@ -6,8 +6,13 @@ description: "Learn how to manually initialize the native SDKs." By default, the React Native SDK initializes the native SDK underneath the `init` method called on the JS layer. As a result, the SDK has a current limitation of not capturing native crashes that occur prior to the `init` method being called on the JS layer. You can initialize the native SDKs yourself to overcome this limitation or if you want to provide custom options above what the React Native SDK currently provides. -To do this, set [autoInitializeNativeSdk](/platforms/react-native/configuration/options/#autoInitializeNativeSdk) to `false` in the init options: + + +If you're using Sentry React Native SDK version 8.0.0 or higher, see the [Capture App Start Errors](/platforms/react-native/manual-setup/app-start-error-capture/) guide for a simpler approach using `sentry.options.json` and native initialization APIs. + + +To do this, set [autoInitializeNativeSdk](/platforms/react-native/configuration/options/#autoInitializeNativeSdk) to `false` in the init options: ```javascript Sentry.init({ From 77590f39443928720576581a6c41ea112a43152b Mon Sep 17 00:00:00 2001 From: Antonis Lilis Date: Tue, 27 Jan 2026 11:45:10 +0100 Subject: [PATCH 2/2] fix order and simplify --- .../manual-setup/app-start-error-capture.mdx | 48 +------------------ .../react-native/manual-setup/native-init.mdx | 2 +- 2 files changed, 3 insertions(+), 47 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 cfa7a52a110d78..1255d4c19e300a 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 @@ -1,6 +1,6 @@ --- -title: Capture App Start Errors (v8+) -sidebar_order: 3 +title: Capture App Start Errors +sidebar_order: 50 description: "Learn how to capture app start errors and crashes that occur before JavaScript loads using native initialization." --- @@ -62,27 +62,6 @@ class MainApplication : Application(), ReactApplication { } ``` -You can also provide additional configuration options: - -```kotlin {filename:android/app/src/main/java/.../MainApplication.kt} -import io.sentry.react.RNSentrySDK -import io.sentry.android.core.SentryAndroidOptions - -class MainApplication : Application(), ReactApplication { - override fun onCreate() { - super.onCreate() - RNSentrySDK.init(this) { options -> - // Additional configuration that can't be serialized in JSON - options.beforeSend = { event, hint -> - // Custom beforeSend logic - event - } - } - // ... rest of your initialization code - } -} -``` - ## iOS Setup Initialize Sentry in your `AppDelegate`: @@ -102,29 +81,6 @@ Initialize Sentry in your `AppDelegate`: @end ``` -You can also provide additional configuration options: - -```objective-c {filename:ios/YourApp/AppDelegate.mm} -#import - -@implementation AppDelegate - -- (BOOL)application:(UIApplication *)application - didFinishLaunchingWithOptions:(NSDictionary *)launchOptions -{ - [RNSentrySDK startWithConfigureOptions:^(SentryOptions *options) { - // Additional configuration that can't be serialized in JSON - options.beforeSend = ^SentryEvent*(SentryEvent *event, SentryHint *hint) { - // Custom beforeSend logic - return event; - }; - }]; - return [super application:application didFinishLaunchingWithOptions:launchOptions]; -} - -@end -``` - ## Expo Setup If you're using Expo, you can enable native initialization automatically using the Expo plugin: diff --git a/docs/platforms/react-native/manual-setup/native-init.mdx b/docs/platforms/react-native/manual-setup/native-init.mdx index 02c96e83b6792b..28f5693fe7b56b 100644 --- a/docs/platforms/react-native/manual-setup/native-init.mdx +++ b/docs/platforms/react-native/manual-setup/native-init.mdx @@ -6,7 +6,7 @@ description: "Learn how to manually initialize the native SDKs." By default, the React Native SDK initializes the native SDK underneath the `init` method called on the JS layer. As a result, the SDK has a current limitation of not capturing native crashes that occur prior to the `init` method being called on the JS layer. You can initialize the native SDKs yourself to overcome this limitation or if you want to provide custom options above what the React Native SDK currently provides. - + If you're using Sentry React Native SDK version 8.0.0 or higher, see the [Capture App Start Errors](/platforms/react-native/manual-setup/app-start-error-capture/) guide for a simpler approach using `sentry.options.json` and native initialization APIs.