Add Source Maps Page (#3293)

Co-authored-by: Bartosz Kaszubowski <gosimek@gmail.com>
Co-authored-by: Dmytro Rykun <dmitry.rykun@gmail.com>

docs/profile-hermes.md

@@ -42,32 +42,10 @@ npx react-native profile-hermes [destinationDir]
 
 ### Enabling source map
 
-A source map is used to enhance the profile and associate trace events with the application code. You can automatically generate a source map when converting the Hermes tracing profile to a Chrome tracing profile by enabling `bundleInDebug` if the app is running in development mode. This allows React Native to build the bundle during its running process. Here's how:
-
-1. In your app's `android/app/build.gradle` file, add:
-
-```groovy
-project.ext.react = [
-  bundleInDebug: true,
-]
-```
-
 :::info
-Be sure to clean the build whenever you make any changes to `build.gradle`
+You may read about source maps on the [source maps](sourcemaps.md) page.
 :::
 
-2. Clean the build by running:
-
-```sh
-cd android && ./gradlew clean
-```
-
-3. Run your app:
-
-```sh
-npx react-native run-android
-```
-
 ### Common errors
 
 #### `adb: no devices/emulators found` or `adb: device offline`

docs/sourcemaps.md

@@ -0,0 +1,82 @@
+---
+id: sourcemaps
+title: Source Maps
+---
+
+Source maps allows to map a transformed file back to the original source file. The main purpose of source maps is to aid debugging and help investigating issues from release builds.
+
+Without the source maps, when running into an error in the release build you will see a stacktrace like:
+
+```text
+TypeError: Cannot read property 'data' of undefined
+  at anonymous(app:///index.android.bundle:1:4277021)
+  at call(native)
+  at p(app:///index.android.bundle:1:227785)
+```
+
+With source maps generated, a stacktrace will include path, file name, and line number of the original source file:
+
+```text
+TypeError: Cannot read property 'data' of undefined
+  at anonymous(src/modules/notifications/Permission.js:15:requestNotificationPermission)
+  at call(native)
+  at p(node_modules/regenerator-runtime/runtime.js:64:Generator)
+```
+
+This allows to triage release issues given a more accurate stacktrace.
+
+Follow the instructions below to get started with source maps.
+
+## Enable source maps on Android
+
+### Hermes
+
+:::info
+Source maps are built in Release mode by default. However, if `hermesFlagsRelease` is set - source maps will have to be enabled.
+:::
+
+If so, ensure the following is set in your app's `android/app/build.gradle` file.
+
+```groovy
+project.ext.react = [
+    enableHermes: true,
+    hermesFlagsRelease: ["-O", "-output-source-map"], // plus whichever flag was required to set this away from default
+]
+```
+
+If done correctly - you may see the output location of the source map during Metro build output.
+
+```text
+Writing bundle output to:, android/app/build/generated/assets/react/release/index.android.bundle
+Writing sourcemap output to:, android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.map
+```
+
+Development builds do not produce a bundle and thus already have symbols, but if the development build is bundled you may use `hermesFlagsDebug` like above to enable source maps.
+
+## Enable source maps on iOS
+
+Source maps are disabled by default. To enable them one has to define `SOURCEMAP_FILE` environment variable.
+
+In order to do so, within Xcode head to the build phase - "Bundle React Native code and images".
+
+At the top of the file near the other export's, add an entry for `SOURCEMAP_FILE` to the preferred location and name. Like below:
+
+```
+export SOURCEMAP_FILE="$(pwd)/../main.jsbundle.map";
+
+export NODE_BINARY=node
+../node_modules/react-native/scripts/react-native-xcode.sh
+```
+
+If done correctly - you may see the output location of the source map during Metro build output.
+
+```text
+Writing bundle output to:, Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle
+Writing sourcemap output to:, Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle.map
+```
+
+## Manual Symbolication
+
+:::info
+You may read about manual symbolication of a stack trace on the [symbolication](symbolication.md) page.
+:::

website/sidebars.json

@@ -23,6 +23,7 @@
       "fast-refresh",
       "debugging",
       "symbolication",
+      "sourcemaps",
       "testing-overview",
       "libraries",
       "typescript",