> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSignal for JavaScript with React Native and Expo

> Report errors from React Native and Expo apps with AppSignal for JavaScript, and upload Hermes sourcemaps so backtraces point to your source code.

AppSignal for JavaScript reports errors from React Native and Expo apps. Report the errors you catch with [`sendError`](/front-end/error-handling). Report render errors with the `ErrorBoundary` from [`@appsignal/react`](/front-end/integrations/react). AppSignal for JavaScript reports errors only. It doesn't support distributed tracing.

An error is easiest to fix when its backtrace points to your source code. A mobile app doesn't run your source code directly. Expo compiles your JavaScript into a [Hermes](https://reactnative.dev/docs/hermes) bundle that ships to each device. Backtrace lines then point to that bundle on the user's device, like this:

```text Android theme={null}
/data/user/0/com.example.myapp/files/.expo-internal/0123456789abcdef0123456789abcdef:1:123456
```

```text iOS theme={null}
/var/mobile/Containers/Data/Application/00000000-0000-0000-0000-000000000000/Library/Application Support/.expo-internal/abcdef0123456789abcdef0123456789.bundle:1:123456
```

A [sourcemap](/front-end/sourcemaps.md) translates a position in the bundle back to your source file, function, and line number. AppSignal finds the right sourcemap by the file name in the backtrace. Here, that name is different on every device and after every update, so no sourcemap matches it. To get readable backtraces:

1. [Give the bundle paths a fixed name](#give-the-bundle-paths-a-fixed-name) with `matchBacktracePaths`.
2. [Generate Hermes sourcemaps](#generate-hermes-sourcemaps) with `npx expo export --source-maps`.
3. [Upload the sourcemaps](#upload-the-sourcemaps) under that fixed name.

> [!NOTE]
>
> [Expo](https://expo.dev/) is a set of tools built on top of [React Native](https://reactnative.dev/). Every Expo app is a React Native app, but not every React Native app uses Expo. These steps are for Expo apps. Sourcemaps for apps without Expo are not documented yet.

These steps assume AppSignal for Front-end is already [installed](/front-end/installation.md) in your app. They rely on the `matchBacktracePaths` option, which is only available in that library. AppSignal for Browser doesn't support this option.

## Give the bundle paths a fixed name

The [`matchBacktracePaths`](/front-end/configuration/options#matchbacktracepaths) option rewrites each backtrace path before the error is sent. Add a function that gives the bundle a fixed name for each platform:

```typescript TypeScript theme={null}
import Appsignal from "@appsignal/javascript";
import { Platform } from "react-native";

export const appsignal = new Appsignal({
  key: "<your frontend API key>",
  revision: "<your app version>",
  matchBacktracePaths: [
    (path: string) => {
      if (path.includes("/.expo-internal/")) {
        return `index.${Platform.OS}.bundle`;
      }
      return undefined;
    },
  ],
});
```

```javascript JavaScript theme={null}
import Appsignal from "@appsignal/javascript";
import { Platform } from "react-native";

export const appsignal = new Appsignal({
  key: "<your frontend API key>",
  revision: "<your app version>",
  matchBacktracePaths: [
    (path) => {
      if (path.includes("/.expo-internal/")) {
        return `index.${Platform.OS}.bundle`;
      }
      return undefined;
    },
  ],
});
```

The function renames the bundle to `index.ios.bundle` on iOS and `index.android.bundle` on Android. iOS and Android need different names, because each platform has its own sourcemap. Other paths stay unchanged.

The backtrace from the start of this page then reaches AppSignal as `index.android.bundle:1:123456`.

The `revision` must match the revision you upload the sourcemaps with.

## Generate Hermes sourcemaps

Expo apps use the Hermes JavaScript engine by default. Export the app with sourcemaps:

```bash Shell theme={null}
npx expo export --source-maps
```

The export writes one sourcemap per platform, ending in `.hbc.map`, to `dist/_expo/static/js/android` and `dist/_expo/static/js/ios`.

Each `.hbc.map` file combines Metro's sourcemap with the Hermes sourcemap, so it maps the bytecode back to your source code. You don't need a separate Metro sourcemap.

> [!WARNING]
>
> Do not generate sourcemaps with `npx react-native bundle --sourcemap-output`. Its sourcemaps do not match the Hermes bundle an Expo app runs, so AppSignal cannot translate the backtrace.

## Upload the sourcemaps

Upload each `.hbc.map` file to the [sourcemaps API](/api/sourcemaps.md). Set `name[]` to the name your function returns, and `revision` to the same app version as the `revision` option in your app:

```bash Shell theme={null}
curl --fail -X POST \
  -F "push_api_key=$APPSIGNAL_PUSH_API_KEY" \
  -F "app_name=My App" \
  -F "environment=production" \
  -F "revision=<your app version>" \
  -F "name[]=index.android.bundle" \
  -F "file=@dist/_expo/static/js/android/<name>-<hash>.hbc.map" \
  "https://appsignal.com/api/sourcemaps"
```

Repeat the request for iOS, with `name[]=index.ios.bundle` and the sourcemap from `dist/_expo/static/js/ios`. Use the app name and environment shown in AppSignal.

Repeat the export and upload for every build or update you ship. A sourcemap only describes the code it was exported from.

### Check the result

Report a test error from your app, then open it in AppSignal. The backtrace shows your source files, functions, and line numbers.

![Backtrace panel showing the line /src/profile/screens/DevModeSettingsScreen.tsx:68:22.](https://mintcdn.com/appsignal-715f5a51/mM8bpWloa5M9x6f1/assets/images/screenshots/frontend/react-native-sourcemapped-backtrace.png?fit=max\&auto=format\&n=mM8bpWloa5M9x6f1\&q=85\&s=f661179f98f13a93e1daffdcaacbd099)

A backtrace line translated with an uploaded sourcemap, pointing to a source file in the app.

## Troubleshooting

If older errors still show the bundle paths, that's expected. AppSignal applies sourcemaps to errors reported after the upload. Errors reported before it keep their original backtraces. Report a new error to check your setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.