From 54f9a7dbc8971c3287c517f96b3f74ae9990c065 Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Fri, 23 Sep 2022 03:02:12 -0400 Subject: [PATCH] Add Source Maps Page (#3293) Co-authored-by: Bartosz Kaszubowski Co-authored-by: Dmytro Rykun --- docs/profile-hermes.md | 24 +------------ docs/sourcemaps.md | 82 ++++++++++++++++++++++++++++++++++++++++++ website/sidebars.json | 1 + 3 files changed, 84 insertions(+), 23 deletions(-) create mode 100644 docs/sourcemaps.md diff --git a/docs/profile-hermes.md b/docs/profile-hermes.md index 6eae014655a..c16793cf18a 100644 --- a/docs/profile-hermes.md +++ b/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` diff --git a/docs/sourcemaps.md b/docs/sourcemaps.md new file mode 100644 index 00000000000..604ebae92e9 --- /dev/null +++ b/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. +::: diff --git a/website/sidebars.json b/website/sidebars.json index 3bf2d97e9f0..59ab3f6d548 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -23,6 +23,7 @@ "fast-refresh", "debugging", "symbolication", + "sourcemaps", "testing-overview", "libraries", "typescript",