Skip to content

Commit b326945

Browse files
alwxconstantinius
alwx
authored and
constantinius
committed
Expo integration docs (#16923)
We've recently added a bunch of changes to Expo integrations in the React Native SDK, this PR adds the missing information about those changes to the docs. Here is the list of PRs it covers: - Expo Updates - getsentry/sentry-react-native#5794 - getsentry/sentry-react-native#5788 - getsentry/sentry-react-native#5748 - Expo Config Plugin - getsentry/sentry-react-native#5796 — 06d4e245 — Add environment option to Expo config plugin - EAS Build Integration - getsentry/sentry-react-native#5666 - getsentry/sentry-react-native#5773 - getsentry/sentry-react-native#5617 - Expo Router / Tracing - getsentry/sentry-react-native#5606 - getsentry/sentry-react-native#5718 - Tooling / Fixes - getsentry/sentry-react-native#5636 - getsentry/sentry-react-native#5733
1 parent aa9a22b commit b326945

File tree

5 files changed

+239
-3
lines changed

5 files changed

+239
-3
lines changed

‎docs/platforms/react-native/manual-setup/expo.mdx‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,20 @@ To verify that everything is working as expected, build the `Release` version of
148148

149149
## Next Steps
150150

151-
- [Learn how to upload source maps for native builds and Expo Updates](/platforms/react-native/sourcemaps/uploading/expo/)
152-
- [Add automatic tracing with Expo Router](/platforms/react-native/tracing/instrumentation/expo-router/)
153-
- [Configure the Sentry Android Gradle Plugin](/platforms/react-native/manual-setup/expo/gradle/)
151+
### Expo-Specific Features
152+
153+
- [Expo Updates](/platforms/react-native/manual-setup/expo/expo-updates/) — Automatic OTA update context, searchable tags, and emergency launch alerts
154+
- [EAS Build Hooks](/platforms/react-native/manual-setup/expo/eas-build-hooks/) — Capture build failures and lifecycle events from EAS Build
155+
- [Sentry Android Gradle Plugin](/platforms/react-native/manual-setup/expo/gradle/) — Advanced Android build configuration
156+
157+
### Source Maps and Releases
158+
159+
- [Upload source maps for native builds and Expo Updates](/platforms/react-native/sourcemaps/uploading/expo/)
160+
161+
### Performance
162+
163+
- [Expo Router tracing](/platforms/react-native/tracing/instrumentation/expo-router/) — Navigation transitions, performance spans, and prefetch instrumentation
164+
- [Expo Image and Asset tracing](/platforms/react-native/tracing/instrumentation/expo-resources/) — Automatic spans for `expo-image` and `expo-asset`
154165

155166
## Notes
156167

‎docs/platforms/react-native/manual-setup/expo/eas-build-hooks.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: EAS Build Hooks
3+
description: "Capture EAS build failures and lifecycle events in Sentry."
4+
sidebar_order: 10
5+
---
6+
7+
EAS Build runs your app builds on Expo's infrastructure. When a build fails, the error can be hard to diagnose — it happens outside your local environment and outside your app. EAS Build Hooks let you send build lifecycle events directly to Sentry so you can track failures, correlate them with releases, and get notified when production builds break.
8+
9+
## Setup
10+
11+
Add the Sentry EAS build hook scripts to your `package.json`:
12+
13+
```json {filename:package.json}
14+
{
15+
"scripts": {
16+
"eas-build-on-error": "sentry-eas-build-on-error",
17+
"eas-build-on-success": "sentry-eas-build-on-success",
18+
"eas-build-on-complete": "sentry-eas-build-on-complete"
19+
}
20+
}
21+
```
22+
23+
EAS Build automatically runs `package.json` scripts with these names at the corresponding lifecycle events. See the [Expo npm hooks documentation](https://docs.expo.dev/build-reference/npm-hooks/) for more details.
24+
25+
Set your DSN as an EAS secret or environment variable so it's available during builds:
26+
27+
```bash
28+
eas secret:create --scope project --name SENTRY_DSN --value <your-dsn>
29+
```
30+
31+
## What Gets Captured
32+
33+
**`eas-build-on-error`** — Sends an `EASBuildError` event to Sentry when a build fails. The event includes:
34+
35+
- Build platform (`ios` / `android`)
36+
- Build profile (for example, `production`, `preview`)
37+
- Build ID, project ID, git commit hash
38+
- Whether the build ran on CI
39+
40+
**`eas-build-on-success`** — Optionally sends an info event when a build succeeds. Disabled by default; enable it with `SENTRY_EAS_BUILD_CAPTURE_SUCCESS=true`.
41+
42+
**`eas-build-on-complete`** — A single hook that captures either a failure or success event depending on the build outcome. Use this instead of `on-error` + `on-success` if you prefer a single hook entry point.
43+
44+
All events are tagged with `eas.*` tags so you can filter and group them in Sentry.
45+
46+
## Environment Variables
47+
48+
| Variable | Required | Description |
49+
|---|---|---|
50+
| `SENTRY_DSN` | Yes | Your project's DSN |
51+
| `SENTRY_EAS_BUILD_CAPTURE_SUCCESS` | No | Set to `true` to capture successful builds |
52+
| `SENTRY_EAS_BUILD_TAGS` | No | JSON object of additional tags, for example `{"team":"mobile"}` |
53+
| `SENTRY_EAS_BUILD_ERROR_MESSAGE` | No | Custom error message for failed builds |
54+
| `SENTRY_EAS_BUILD_SUCCESS_MESSAGE` | No | Custom message for successful builds |
55+
| `SENTRY_RELEASE` | No | Override the release name (defaults to `{appVersion}+{buildNumber}`) |
56+
57+
## Environment Files
58+
59+
The hook automatically loads environment variables from the following sources (without overwriting values already set by EAS):
60+
61+
1. `@expo/env` (if available)
62+
2. `.env` file in the project root (via `dotenv`, if available)
63+
3. `.env.sentry-build-plugin` file in the project root
64+
65+
This means you can store the DSN in `.env.sentry-build-plugin` locally, and use an EAS secret in CI — the hook will use whichever value is already set.
66+
67+
## Using `on-complete` Instead of Separate Hooks
68+
69+
If you only need to track failures but want the option to add success tracking later, `eas-build-on-complete` is the most flexible option. It reads `EAS_BUILD_STATUS` (set by EAS) to determine the outcome and captures the appropriate event:
70+
71+
```json {filename:package.json}
72+
{
73+
"scripts": {
74+
"eas-build-on-complete": "sentry-eas-build-on-complete"
75+
}
76+
}
77+
```
78+
79+
To also capture successful builds, set `SENTRY_EAS_BUILD_CAPTURE_SUCCESS=true` in your build environment.

‎docs/platforms/react-native/manual-setup/expo/expo-updates.mdx‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Expo Updates
3+
description: "Automatic context and alerts for Expo OTA updates."
4+
sidebar_order: 20
5+
---
6+
7+
When you ship OTA updates with Expo Updates, events captured by Sentry are automatically enriched with information about which update is running. This lets you filter issues by update channel, runtime version, or update ID — and get alerted when an emergency launch occurs.
8+
9+
These integrations are enabled by default in Expo projects. No additional setup is required.
10+
11+
## Expo Updates Context
12+
13+
Every Sentry event includes an `ota_updates` context with the current update state:
14+
15+
| Field | Description |
16+
|---|---|
17+
| `update_id` | UUID of the currently running OTA update |
18+
| `channel` | Expo Updates channel (for example, `production`, `staging`) |
19+
| `runtime_version` | Runtime version of the update |
20+
| `is_enabled` | Whether Expo Updates is enabled |
21+
| `is_embedded_launch` | Whether the app launched from the embedded bundle |
22+
| `is_using_embedded_assets` | Whether the app is using embedded assets |
23+
| `is_emergency_launch` | Whether this was an emergency launch (fallback to embedded) |
24+
| `emergency_launch_reason` | Reason for the emergency launch (if applicable) |
25+
| `check_automatically` | Automatic update check policy |
26+
| `launch_duration` | How long the update launch took (ms) |
27+
| `created_at` | When the update was created |
28+
29+
## Searchable Tags
30+
31+
The SDK also sets the following tags on every event so you can filter and group issues in Sentry:
32+
33+
| Tag | Value |
34+
|---|---|
35+
| `expo.updates.update_id` | UUID of the running update |
36+
| `expo.updates.channel` | Update channel name |
37+
| `expo.updates.runtime_version` | Runtime version string |
38+
39+
To find all issues from a specific update channel, use `expo.updates.channel:production` in the Sentry issue search.
40+
41+
## Emergency Launch Warnings
42+
43+
Expo Updates performs an _emergency launch_ when it fails to load the latest OTA update and falls back to the embedded bundle. This can silently degrade user experience.
44+
45+
When the SDK detects an emergency launch at startup, it automatically sends a `warning`-level event to Sentry with:
46+
47+
- Message: `Expo Updates emergency launch: <reason>` (or `Expo Updates emergency launch` if no reason is available)
48+
- Tag: `expo.updates.emergency_launch: true`
49+
50+
You can set up a Sentry alert on this tag to get notified whenever an emergency launch happens in production.
51+
52+
<Alert>
53+
54+
Emergency launch detection only runs in native builds, not in Expo Go.
55+
56+
</Alert>
57+
58+
## Expo Constants Context
59+
60+
The SDK automatically captures Expo Constants as an `expo_constants` context on every event. This provides metadata about the execution environment and app configuration:
61+
62+
| Field | Description |
63+
|---|---|
64+
| `execution_environment` | Where the app is running (`storeClient`, `standalone`, `bare`) |
65+
| `app_ownership` | Whether the app runs in Expo Go or standalone |
66+
| `debug_mode` | Whether debug mode is enabled |
67+
| `expo_version` | Expo client version |
68+
| `expo_runtime_version` | Runtime version from app config |
69+
| `session_id` | Current session ID |
70+
| `app_name` | App name from `app.json` |
71+
| `app_slug` | App slug from `app.json` |
72+
| `app_version` | App version from `app.json` |
73+
| `expo_sdk_version` | Expo SDK version |
74+
| `eas_project_id` | EAS project ID |

‎docs/platforms/react-native/tracing/instrumentation/expo-resources.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Expo Image and Asset Instrumentation
3+
description: "Automatic performance spans for expo-image and expo-asset."
4+
sidebar_order: 70
5+
---
6+
7+
Image and asset loading times directly affect how quickly your app feels responsive. The SDK can automatically create performance spans for `expo-image` and `expo-asset` operations so you can see exactly how long prefetching and loading takes within your existing traces.
8+
9+
## Expo Image
10+
11+
Wrap the `Image` class from `expo-image` once at app startup to instrument `Image.prefetch()` and `Image.loadAsync()`:
12+
13+
```javascript {filename:App.js}
14+
import { Image } from 'expo-image';
15+
import * as Sentry from '@sentry/react-native';
16+
17+
Sentry.wrapExpoImage(Image);
18+
```
19+
20+
After wrapping, every call to `Image.prefetch()` creates a `resource.image.prefetch` span, and every call to `Image.loadAsync()` creates a `resource.image.load` span. The spans are automatically linked to the active trace.
21+
22+
Span attributes include:
23+
24+
- `image.url` — the image URL (for single-image operations)
25+
- `image.url_count` — number of URLs (for batch prefetch)
26+
27+
## Expo Asset
28+
29+
Wrap the `Asset` class from `expo-asset` once at app startup to instrument `Asset.loadAsync()`:
30+
31+
```javascript {filename:App.js}
32+
import { Asset } from 'expo-asset';
33+
import * as Sentry from '@sentry/react-native';
34+
35+
Sentry.wrapExpoAsset(Asset);
36+
```
37+
38+
After wrapping, every call to `Asset.loadAsync()` creates a `resource.asset` span with an `asset.count` attribute.
39+
40+
## Notes
41+
42+
- Both `wrapExpoImage` and `wrapExpoAsset` are safe to call multiple times — the SDK guards against double-wrapping.
43+
- Spans are only created when a trace is active. If you're not using [tracing](/platforms/react-native/tracing/), no spans are created and there's no overhead.
44+
- `expo-image` and `expo-asset` are peer dependencies — the SDK does not require them to be installed.

‎docs/platforms/react-native/tracing/instrumentation/expo-router.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,34 @@ This option will enable automatic measuring of the time to initial display for e
6969

7070
This ensures that transactions that are from routes that've been seen and don't have any spans, are not being sampled. This removes a lot of clutter, making it so that most back navigation transactions are now ignored. The default value is `true`.
7171

72+
## Prefetch Instrumentation
73+
74+
<Alert level="info">
75+
76+
`router.prefetch()` requires **Expo Router v5 (Expo SDK 53) or later**. On older versions the method does not exist; calling it will throw a runtime error.
77+
78+
</Alert>
79+
80+
Expo Router's `router.prefetch()` preloads a route before the user navigates to it. By default, these prefetch calls are invisible in your traces. Wrapping the router with `Sentry.wrapExpoRouter()` adds an automatic `navigation.prefetch` span for each call so you can see prefetch timing alongside your other navigation spans.
81+
82+
```javascript {filename:app/(tabs)/index.tsx}
83+
import { useRouter } from 'expo-router';
84+
import * as Sentry from '@sentry/react-native';
85+
86+
function HomeScreen() {
87+
const router = Sentry.wrapExpoRouter(useRouter());
88+
89+
return (
90+
<Button
91+
title="Go to Details"
92+
onPress={() => router.prefetch('/details')}
93+
/>
94+
);
95+
}
96+
```
97+
98+
The span name is `Prefetch /details` (or `Prefetch unknown` for unresolvable routes). Span attributes include `route.href` and `route.name`.
99+
72100
## Notes
73101

74102
- Slow and Frozen frames, Time To Initial Display and Time To Full Display are only available in native builds, not in Expo Go.

0 commit comments

Comments
 (0)