How do you get a source map for a React Native release build on Android and on iOS, and which file do you use?

## Why the platforms differ Both platforms bundle JavaScript for a release build with the same pieces: **Metro** writes the bundle (and, when asked, a *packager* source map), **hermesc** compiles it to bytecode (and, when asked, a *compiler* source map), and a script composes the two into the map you symbolicate with. The difference is the default: the **Android Gradle plugin asks for the map unless you stop it**, while the **iOS build script only asks when you set a variable**. | | Android | iOS | |---|---|---| | Default | On | Off | | Switch | `hermesFlags` includes `-output-source-map` (the default) | `SOURCEMAP_FILE` exported in the bundling build phase | | Map to use | `android/app/build/generated/sourcemaps/react/<variant>/index.android.bundle.map` | Whatever path you gave `SOURCEMAP_FILE` | | Intermediates | `intermediates/sourcemaps/react/<variant>/*.packager.map` and `*.compiler.map` are kept | Deleted after composition | ## Android The React Native Gradle plugin configures release bundling. Its `hermesFlags` property defaults to `["-O", "-output-source-map"]`, so a normal release build produces a map without any change. The docs show the explicit form in `android/app/build.gradle`: ```groovy react { hermesFlags = ["-O", "-output-source-map"] } ``` Points worth knowing: - The map you want is the **composed** one in `generated/sourcemaps/react/release/`. The build also leaves a packager map and a compiler map under `intermediates/`; the docs warn that several maps are generated and you should use the one in the documented location. - If you override `hermesFlags` and drop `-output-source-map`, the plugin skips composition and **no map appears** in `generated/sourcemaps`. - The build log confirms it: Metro prints a `Writing sourcemap output to:` line. ## iOS The Xcode build phase **"Bundle React Native code and images"** runs `react-native-xcode.sh`. It emits a source map only when `SOURCEMAP_FILE` is set: 1. Open the app target's build phases in Xcode and edit **Bundle React Native code and images**. 2. Above the other exports, add `export SOURCEMAP_FILE="$(pwd)/../main.jsbundle.map"`, or any path outside the app bundle. 3. Build or archive the Release configuration and look for `Writing sourcemap output to:` in the build log. When the variable is set, the script passes `--sourcemap-output` to Metro. With Hermes it also adds `-output-source-map` to the hermesc call, composes the two maps into `SOURCEMAP_FILE` with `compose-source-maps.js`, and deletes the two intermediate maps. Choose a path outside the app bundle and one your archive step knows about, since that is the only copy. Without the variable, an iOS release build produces **no map at all**, and a crash from it cannot be symbolicated later unless you can reproduce that exact build. ## Running metro-symbolicate With the map in hand, feed the stack trace on standard input: - from a saved file: `npx metro-symbolicate <map> < stacktrace.txt`; - straight from Android logs: `adb logcat -d | npx metro-symbolicate <map>`; - with no arguments, `npx metro-symbolicate` prints its usage. One trap from the docs: if `metro-symbolicate` **exits immediately with success**, it was reading from the terminal instead of a pipe or redirect, so it received no trace. ## Checking the map before you need it A map is only discovered to be missing or wrong when a crash needs it, which is the worst moment. Cheap checks at build time: 1. Confirm the file exists at the expected path and is not empty. 2. Open it and check that its `sources` list contains your own files, for example `src/screens/CheckInScreen.tsx`, not only `node_modules` paths. 3. Once per setup change, plant a JavaScript crash in a release build, capture the trace and confirm `metro-symbolicate` points at the planted line. The third check is the only one that proves the whole chain: generation, composition, archiving and matching. ## Where the map should live The map is written next to the build outputs, not packaged into the app, and it describes only the bundle it came from. Treat it as part of the release: - store it with the build that produced it, keyed by version, build number and commit; - make the release pipeline fail if the expected map is missing; - regenerate nothing after the fact; a rebuilt map from different inputs will not line up.