Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 95 additions & 71 deletions docs/platforms/react-native/common/index.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: React Native
description: Learn how to set up Sentry's React Native SDK.
description: Learn how to set up Sentry's React Native SDK and capture your first events.
sdk: sentry.javascript.react-native
fallbackPlatform: javascript
caseStyle: camelCase
Expand All @@ -9,125 +9,140 @@ categories:
- mobile
---

<AgentSetupCallout skill="sentry-react-native-sdk" platformName="React Native" />
<AgentSetupCallout
skill="sentry-react-native-sdk"
platformName="React Native"
/>

Read on to find out how to set up Sentry's React Native SDK which will automatically report errors and exceptions in your application. If you prefer to follow video instructions, see [How to Install the Sentry React Native SDK in 60 Seconds](https://vimeo.com/899369012).
Read on to find out how to set up Sentry's React Native SDK, which automatically reports errors and exceptions in your application. If you prefer video instructions, see [How to Install the Sentry React Native SDK in 60 Seconds](https://vimeo.com/899369012).

<Alert>

If you don't already have an account and Sentry project established, head over to [sentry.io](https://sentry.io/signup/), then return to this page.
If you don't already have an account and Sentry project, head over to [sentry.io](https://sentry.io/signup/), then return to this page.

</Alert>

## Features

In addition to [error monitoring](/product/issues/), here are some of the features you can configure when installing Sentry:

- **[Logs](/platforms/react-native/logs/)**: Send, view, and query logs from your app alongside your errors to get richer context when debugging.
- **[Tracing](/platforms/react-native/tracing/)**: Monitor the timing and flow of requests and operations as they happen across different systems in your application to improve performance.
- **[Session Replay](/platforms/react-native/session-replay/)**: Get reproductions of user sessions to improve your app experience.
- **[Profiling](/platforms/react-native/profiling/)**: Collect and analyze function-level information about your code to fine-tune performance.
- **[Application Metrics](/platforms/react-native/metrics/)**: Send, view, and query counters, gauges, and measurements from your app to track health and drill down into related traces, logs, and errors.
- **[User Feedback](/platforms/react-native/user-feedback/)**: Collect user feedback from anywhere inside your application at any time, without needing an error event to occur first.
- **[Size Analysis](/platforms/react-native/size-analysis/)**: Monitor your mobile app's size in pre-production to prevent unexpected size increases (regressions) from reaching users.

Tracing, profiling, session replay, and logs can be added via the [Configure](#configure) section below. For the other features, refer to each product page for instructions on getting started.

## Install

Sentry captures data by using an SDK within your application's runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works.
Sentry captures data by using an SDK within your application's runtime. These platform-specific SDKs give Sentry a deeper understanding of how your application works.

To install, run `@sentry/wizard`:
Run `@sentry/wizard` to install and configure the SDK:

```bash {tabTitle:npm}
npx @sentry/wizard@latest -i reactNative
```

[Sentry Wizard](https://github.com/getsentry/sentry-wizard) will patch your project accordingly, though you can [set up manually](/platforms/react-native/manual-setup/manual-setup/) if you prefer. You only need to patch the project once. Then you can add the patched files to your version control system.
[Sentry Wizard](https://github.com/getsentry/sentry-wizard) patches your project. You only need to do this once; then add the patched files to version control. If you prefer, follow the [manual setup guide](/platforms/react-native/manual-setup/manual-setup/).

<Expandable title="The following tasks will be performed by the Sentry Wizard">

- Install the `@sentry/react-native` package.
- Add the `@sentry/react-native/metro` to the _*metro.config.js*_ Metro configuration.
- Add the `@sentry/react-native/expo` to the _*app.json*_ Expo configuration.
- Add `@sentry/react-native/metro` to the _*metro.config.js*_ Metro configuration.
- Add `@sentry/react-native/expo` to the _*app.json*_ Expo configuration.
- Enable the Sentry React Native Gradle build step for Android to auto-upload generated source maps and debug symbols.
- Wrap the _Bundle React Native code and images_ Xcode project build phase script to upload generated source maps and collect bundled node modules.
- Add _Upload Debug Symbols to Sentry_ Xcode project build phase.
- Add the _Upload Debug Symbols to Sentry_ Xcode project build phase.
- Run `pod install`.
- Store build credentials in _*ios/sentry.properties*_, _*android/sentry.properties*_ and _*.env.local*_.
- Configure Sentry for the supplied DSN in your _*layout.tsx*_/_*App.tsx*_file.
- Store build credentials in _*ios/sentry.properties*_, _*android/sentry.properties*_, and _*.env.local*_.
- Configure Sentry with the supplied DSN in your _*layout.tsx*_ or _*App.tsx*_ file.

</Expandable>

If you're using Expo, [read our Expo guide](/platforms/react-native/guides/expo/) to learn how to add Sentry to your Expo project. This SDK will work for both managed and bare projects.

If you're using Expo, follow the [Expo guide](/platforms/react-native/guides/expo/) for Expo-specific setup. The SDK works with both managed and bare projects.

## Configure

<OnboardingOptionButtons
options={[
'error-monitoring',
'performance',
'profiling',
'session-replay',
"logs",
]}
/>
**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** need `enableLogs: true` in the initialization snippet below, and you'll learn how to send them in [Send Logs](#send-logs). **Application Metrics** need no extra configuration, and you'll learn how to send them in [Send Application Metrics](#send-application-metrics-).

This guide also enables **Tracing**, **Profiling**, **Session Replay**, and **User Feedback**. **Size Analysis** uses a separate build-time setup; see <PlatformLink to="/size-analysis/">Size Analysis</PlatformLink>.

<Include name="quick-start-features-expandable" />
Comment thread
sentry-junior[bot] marked this conversation as resolved.

To capture all errors, initialize the Sentry React Native SDK as soon as possible.
To capture errors, initialize the Sentry React Native SDK as early as possible in your application's lifecycle.

The snippet also turns on:

- Tracing: via <PlatformLink to="/configuration/options/#tracesSampleRate">`tracesSampleRate`</PlatformLink>
- Profiling: via `profilesSampleRate` (see <PlatformLink to="/profiling/">Profiling</PlatformLink>)
- Session Replay: via `mobileReplayIntegration()` and the replay sample rates (see <PlatformLink to="/session-replay/">Session Replay</PlatformLink>)
- User Feedback: via `feedbackIntegration()` (see <PlatformLink to="/user-feedback/">User Feedback</PlatformLink>)
- Logs: via <PlatformLink to="/configuration/options/#enableLogs">`enableLogs`</PlatformLink>

Don't need a feature? Remove its integration and options from the snippet.

```javascript {filename:App.js}
import * as Sentry from "@sentry/react-native";

Sentry.init({
dsn: "___PUBLIC_DSN___",
// Adds more context data to events (IP address, cookies, user, etc.)
// For more information, visit: https://docs.sentry.io/platforms/react-native/data-management/data-collected/
// Adds context data to events, such as IP address, cookies, and user.
sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ performance
// Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
// We recommend adjusting this value in production.
// Learn more at
// https://docs.sentry.io/platforms/react-native/configuration/options/#traces-sample-rate

integrations: [
// Enables Session Replay
Sentry.mobileReplayIntegration(),
// Enables User Feedback. Open the form with Sentry.showFeedbackWidget().
Sentry.feedbackIntegration(),
],

// Enables Tracing.
// Set to 1.0 to capture 100% of spans for tracing.
// We recommend reducing this value in production.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs
// Enable logs to be sent to Sentry
// Learn more at https://docs.sentry.io/platforms/react-native/logs/
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
// ___PRODUCT_OPTION_START___ profiling
// profilesSampleRate is relative to tracesSampleRate.
// Here, we'll capture profiles for 100% of transactions.

// Enables Profiling for 100% of sampled transactions.
profilesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ profiling
// ___PRODUCT_OPTION_START___ session-replay
// Record session replays for 100% of errors and 10% of sessions
replaysOnErrorSampleRate: 1.0,

// Enables Logs to be sent to Sentry.
enableLogs: true,

// Capture replays for 10% of sessions and 100% of sessions with an error.
replaysSessionSampleRate: 0.1,
integrations: [Sentry.mobileReplayIntegration()],
// ___PRODUCT_OPTION_END___ session-replay
replaysOnErrorSampleRate: 1.0,
});
```

<OnboardingOption optionId="performance">
### Wrap Your App

#### Wrap Your App

To automatically instrument your app with [touch event tracking](/platforms/react-native/configuration/touchevents/) and [automatic tracing](/platforms/react-native/tracing/instrumentation/automatic-instrumentation/), wrap it with `Sentry.wrap`:
To automatically instrument your app with [touch event tracking](/platforms/react-native/configuration/touchevents/) and [automatic tracing](/platforms/react-native/tracing/instrumentation/automatic-instrumentation/), wrap its root component with `Sentry.wrap`:

```javascript {filename:App.js}
export default Sentry.wrap(App);
```

This is not required if your app does not have a single parent "App" component.
You don't need this if your app doesn't have a single parent `App` component.

## Send Logs

</OnboardingOption>
Use `Sentry.logger` to send logs at different levels. You can include attributes to search or filter by later.

The SDK can capture `console.*` calls when Logs are enabled. See the [Console logging integration](/platforms/react-native/integrations/console-logging/) for details.

```javascript
Sentry.logger.info("Order processed", { order_id: "order-123" });
Sentry.logger.warn("Slow operation detected", {
operation: "data_fetch",
duration_ms: 3500,
});
```

See <PlatformLink to="/logs/">Set Up Logs</PlatformLink> for all available logging methods and message formatting options.

## Verify
## Send Application Metrics <FeatureBadge type="new" />

Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes.
Application Metrics are supported in React Native SDK 7.8.0 and newer. No extra option is needed after SDK initialization. Use `Sentry.metrics` to send counters, gauges, and distributions:

```javascript
Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("active_connections", 42);
Sentry.metrics.distribution("api_latency", 187, { unit: "millisecond" });
```

See <PlatformLink to="/metrics/">Set Up Metrics</PlatformLink> for all available metric types and configuration options.

## Verify Your Setup

Trigger a test error to confirm that Sentry is receiving events. You should see the error in Sentry within a few minutes.

```javascript {tabTitle:Throw Error} {mdExpandTabs}
throw new Error("My first Sentry error!");
Expand All @@ -137,12 +152,21 @@ throw new Error("My first Sentry error!");
Sentry.nativeCrash();
```

Alternatively, you can use the <PlatformLink to="/manual-setup/playground/">Sentry Playground</PlatformLink> to interactively test your SDK setup with multiple error scenarios.
Alternatively, use the <PlatformLink to="/manual-setup/playground/">Sentry Playground</PlatformLink> to test your setup interactively with multiple error scenarios.

### View Captured Data in Sentry

Head over to your project on [Sentry.io](https://sentry.io) to view the captured error.

<Include name="quick-start-locate-data-expandable" />

## Next Steps

At this point, you should have integrated Sentry into your React Native application. Here's what to explore next:

{/* prettier-ignore */}
- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup
- <PlatformLink to="/features/">Learn about the features of Sentry's React Native SDK</PlatformLink>
- <PlatformLink to="/features/">Explore React Native features</PlatformLink>
- <PlatformLink to="/sourcemaps/">Add readable stack traces to errors</PlatformLink>
- <PlatformLink to="/data-management/apple-privacy-manifest/">Add Apple Privacy manifest</PlatformLink>
- <PlatformLink to="/data-management/apple-privacy-manifest/">Add the Apple Privacy Manifest</PlatformLink>
- <PlatformLink to="/troubleshooting/">Troubleshoot your setup</PlatformLink>
Comment thread
sentry-junior[bot] marked this conversation as resolved.
Loading
Loading