Upload source maps for React Native iOS builds

To get unminified stack traces for JavaScript code in your React Native app built for iOS, source maps must be generated and uploaded to BugSnag.

For installation instructions for the BugSnag CLI, please see our Installation guide.


The react-native-ios command uploads the bundled JavaScript and source maps generated during a build and uploads it to the React Native source map API.

In addition to the source maps, the command extracts version and build information, including your BugSnag API key, required for the upload from your Xcode project file. These values can be overridden, or provided entirely, by command line options.

Example usage

The simplest way to run the command is from the root directory of your React Native project:

$ bugsnag-cli upload react-native-ios

Or by providing a specific bundle file and associated mapping file to upload:

$ bugsnag-cli upload react-native-ios \
    --bundle ~/Library/Developer/Xcode/DerivedData/AwesomeProject-abcd/Build/Products/Release-iphoneos/AwesomeProject.app/main.jsbundle \
    --source-map ios/build/main.jsbundle.map

If your build contains multiple variants or has a non-standard project layout, you might need to provide extra options:

$ bugsnag-cli upload react-native-android \
    --xcode-project ios/AwesomeProject.xcodeproj \
    --scheme AwesomeProject

Available options

API key (--api-key)

Your project’s API key. This defaults to the value of bugsnag.apiKey in your app’s Info.plist file, if found.

You can find your API key in Project Settings from your BugSnag dashboard.

Bundle path (--bundle)

The path to the bundled JavaScript generated by the React Native build. By default, the command uses the build settings in your app’s workspace to locate the file.

Bundle version (--bundle-version)

The bundle version of this build of the app. This defaults to the value of CFBundleVersion in your app’s Info.plist, if found.

Code Bundle ID (--code-bundle-id)

A unique identifier for the JavaScript bundle. If you use CodePush, or similar mechanism, to update the JavaScript bundle of your app without changing the native version or build number, use the code bundle ID to uniquely identify the update. This same ID must also be set in the BugSnag configuration in your app, so that errors match the uploaded bundle.

Dev (--dev)

Whether the app is a debug or release build. This value should mirror the value used when generating source map files with react-native bundle.

Dry run (--dry-run)

Used to see the files and options that would be uploaded without actually sending them to the BugSnag endpoint.

Overwrite (--overwrite)

Whether to ignore and overwrite existing uploads with same identifier. By default the command will fail if a matching file exists.

Plist (--plist)

The path to the app’s Info.plist, which is used to extract app information required for the upload. By default, the command uses the build settings in your app’s project to locate the file.

Project root (--project-root)

Path to strip from the beginning of source file names referenced in stacktraces when displayed as an error in your dashboard. This will default to your project’s root directory if the command has detected one, otherwise it’s empty.

Retries (--retries)

The number of retry attempts before failing an upload. By default it is only attempted once.

Scheme (--scheme)

The Xcode scheme used to build the app.

Source map path (--source-map)

The path to the source map generated by the React Native build. The command attempts to use the SOURCEMAP_FILE environment variable, which can be set during a build to specify the location of the source map. If this is not set, the command then checks ios/build/sourcemaps.

Timeout (--timeout)

The number of seconds to wait before failing an upload attempt. By default the upload is given 300s (5 mins).

Upload API root URL (--upload-api-root-url)

The BugSnag On-premise upload server hostname, optionally containing port number. The command will append the appropriate path to access the correct BugSnag API upload endpoint.

Version name (--version-name)

The version of the app. This defaults to the value of CFBundleShortVersionString in your app’s Info.plist file, if found.

Xcode Project (--xcode-project)

The path to your Xcode project, workspace or containing directory, from which the command attempts to automatically derive build locations and information for upload.