Upload Source Maps
To get unminified stack traces for JavaScript code in your React Native app, source maps must be generated and uploaded using the Pulse CLI.
Overview
The Pulse CLI provides commands to upload bundled JavaScript and source maps generated during a release build to the Pulse CLI upload source map API. The upload command is the primary command, with platform-specific subcommands for React Native Android and iOS.
Versions, build information and other metadata are required to identify the release build. These values can be provided by command line options.
What Gets Uploaded
- JavaScript Source Maps - For deobfuscating JavaScript stack traces
- ProGuard Mapping Files - For deobfuscating native Android stack traces
- dSYM Files - Upload command will have its support soon for native iOS crash symbolication
- Android NDK Symbol Files - Upload command will have its support soon for native Android NDK stack traces
Installation
The Pulse CLI is included with the React Native SDK package. No additional installation is required.
# Verify CLI is available
yarn pulse-cli --version
After installation, you can use the upload command with platform-specific subcommands. To see all available upload commands and options, run:
yarn pulse-cli upload -h
Currently supported subcommands:
yarn pulse-cli upload react-native-android- Upload source maps for Android buildsyarn pulse-cli upload react-native-ios- Upload source maps for iOS builds
Each subcommand has its own set of required and optional options. See React Native Android and React Native iOS sections below for detailed usage.
Upload Source Maps
React Native Android
The react-native-android command uploads JavaScript source maps and optional ProGuard mapping files generated during a release build to the Pulse source map API.
The command requires you to provide the API URL, app version, version code, and path to the JavaScript source map file. Optionally, you can include a ProGuard mapping file for deobfuscating native Android stack traces. All values must be provided via command line options.
Example Usage
Upload JavaScript source maps only:
This command uploads the JavaScript source map file to enable deobfuscation of JavaScript stack traces in error reports.
yarn pulse-cli upload react-native-android \
--api-url=http://localhost:8080/v1/symbolicate/file/upload \
--app-version=1.0.0 \
--version-code=7 \
--js-sourcemap=./android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.map
Upload JavaScript source maps and ProGuard mapping file:
This command uploads both the JavaScript source map and the ProGuard mapping file to enable deobfuscation of both JavaScript and native Android stack traces.
yarn pulse-cli upload react-native-android \
--api-url=http://localhost:8080/v1/symbolicate/file/upload \
--app-version=1.0.0 \
--version-code=7 \
--js-sourcemap=./android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.map \
--mapping=./android/app/build/outputs/mapping/release/mapping.txt
Available Options
| Option | Required | Description |
|---|---|---|
--api-url / -u | Yes | URL for uploading source maps to the Pulse source map API |
--app-version / -v | Yes | App version string (e.g., 1.0.0) |
--version-code / -c | Yes | Version code as an integer (e.g., 7) |
--js-sourcemap / -j | Yes | Path to JavaScript source map file (relative or absolute) |
--mapping / -m | No | Path to ProGuard mapping file for deobfuscating native Android stack traces |
--bundle-id / -b | No | CodePush bundle label for identifying specific bundle versions in OTA updates |
--debug / -d | No | Show detailed debug information during upload process |
OTA Updates: OTA (Over-The-Air) updates allow pushing JavaScript code changes without app store review. Services like CodePush enable this. The bundle ID helps identify which deployment caused an issue when the same native app version runs multiple JavaScript bundles.
React Native iOS
The react-native-ios command uploads JavaScript source maps generated during a release build to the Pulse source map API.
The command requires you to provide the API URL, bundle version (from Info.plist), version code, and path to the JavaScript source map file. All values must be provided via command line options. Native iOS crash symbolication via dSYM file upload will be supported in a future release.
Example Usage
Upload JavaScript source maps:
This command uploads the JavaScript source map file to enable deobfuscation of JavaScript stack traces in error reports for iOS builds.
yarn pulse-cli upload react-native-ios \
--api-url=http://localhost:8080/v1/symbolicate/file/upload \
--bundle-version=1.0.0 \
--version-code=123 \
--js-sourcemap=./ios/build/Build/Products/Release-iphoneos/main.jsbundle.map
Available Options
| Option | Required | Description |
|---|---|---|
--api-url / -u | Yes | URL for uploading source maps to the Pulse source map API |
--bundle-version / -v | Yes | Bundle version from Info.plist CFBundleShortVersionString (e.g., 1.0.0) |
--version-code / -c | Yes | Version code as an integer (e.g., 123) |
--js-sourcemap / -j | Yes | Path to JavaScript source map file (relative or absolute) |
--bundle-id / -b | No | CodePush bundle label for identifying specific bundle versions in OTA updates |
--debug / -d | No | Show detailed debug information during upload process |
Finding Source Map Files
Source map files are generated automatically during release builds. The exact location depends on your build configuration, React Native version, and build tools. The paths listed below are common default locations, but your project may have different paths based on custom build scripts or configuration.
JavaScript Source Maps
React Native Android:
Default locations (may vary by React Native version):
android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.mapandroid/app/build/generated/sourcemaps/react/release/index.android.bundle.map
If using custom build scripts, check your configured build output directory.
React Native iOS:
Default locations:
ios/build/Build/Products/Release-iphoneos/main.jsbundle.map- Or in your Xcode build output directory
The source map file name typically matches the bundle name (e.g., main.jsbundle.map for main.jsbundle).
ProGuard Mapping Files
React Native Android:
Location: android/app/build/outputs/mapping/release/mapping.txt
This file is only generated if minifyEnabled = true is set in your build.gradle release build type. If you don't see this file, ensure minification is enabled in your release build configuration.
Troubleshooting
Getting Help
View all available commands and options:
yarn pulse-cli -h
yarn pulse-cli upload -h
yarn pulse-cli upload react-native-android -h
yarn pulse-cli upload react-native-ios -h
Debug Mode
For detailed error information, use the --debug flag:
yarn pulse-cli upload react-native-android --debug