AppSignal for JavaScript with React Native and Expo

AppSignal for JavaScript reports errors from React Native and Expo apps. Report the errors you catch with sendError. Report render errors with the ErrorBoundary from @appsignal/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 bundle that ships to each device. Backtrace lines then point to that bundle on the user’s device, like this:

/data/user/0/com.example.myapp/files/.expo-internal/0123456789abcdef0123456789abcdef:1:123456

/var/mobile/Containers/Data/Application/00000000-0000-0000-0000-000000000000/Library/Application Support/.expo-internal/abcdef0123456789abcdef0123456789.bundle:1:123456

A sourcemap 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:

Give the bundle paths a fixed name with matchBacktracePaths.
Generate Hermes sourcemaps with npx expo export --source-maps.
Upload the sourcemaps under that fixed name.

Expo is a set of tools built on top of React Native. 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 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 option rewrites each backtrace path before the error is sent. Add a function that gives the bundle a fixed name for each platform:

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;
    },
  ],
});

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:

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.

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. Set name[] to the name your function returns, and revision to the same app version as the revision option in your app:

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.

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.

SDKs & telemetry

Language SDKs

Telemetry tools

AppSignal for JavaScript with React Native and Expo

Give the bundle paths a fixed name

Generate Hermes sourcemaps

Upload the sourcemaps

Check the result

Troubleshooting

​Give the bundle paths a fixed name

​Generate Hermes sourcemaps

​Upload the sourcemaps

​Check the result

​Troubleshooting

Give the bundle paths a fixed name

Generate Hermes sourcemaps

Upload the sourcemaps

Check the result

Troubleshooting