From 94b0238f4460f237851b607fbe28abd2ef826bac Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Thu, 1 Sep 2022 17:52:27 -0400 Subject: [PATCH 1/6] feat: add sourcemap page --- docs/sourcemaps.md | 95 +++++++++++++++++++++++++++++++++++++++++++ website/sidebars.json | 1 + 2 files changed, 96 insertions(+) create mode 100644 docs/sourcemaps.md diff --git a/docs/sourcemaps.md b/docs/sourcemaps.md new file mode 100644 index 00000000000..873d1ad08a8 --- /dev/null +++ b/docs/sourcemaps.md @@ -0,0 +1,95 @@ +--- +id: sourcemaps +title: Source Maps +--- + +Source maps help map a minified file back to an un-packaged state. This is common when investigating issues from release builds. + +This helps if you have 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) +``` + +The power of source maps allow tracing that line and column number back to the original source stacktrace. + +```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: + +1. [Enable source maps on Android](sourcemaps.md#enable-source-maps-on-android) +2. [Enable source maps on iOS](sourcemaps.md#enable-source-maps-on-ios) +3. [Manual Symbolication](sourcemaps.md#manual-symbolication) + +## 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 enable source maps like: + +Editing `android/app/build.gradle` file with: + +```groovy +project.ext.react = [ + bundleInDebug: true, + hermesFlagsDebug: ["-O", "-output-source-map"], +] +``` + +## Enable source maps on iOS + +Source maps are built in Release mode by default. However, you might want to redirect the location of the source map for easier use. + +If so, within Xcode head to the build phrase - "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 56db20c5502..58eb334716a 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -23,6 +23,7 @@ "fast-refresh", "debugging", "symbolication", + "sourcemaps", "testing-overview", "libraries", "typescript", From 9a41d8438cde686a2cbf3bc96b0708f3a2daf46b Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Thu, 1 Sep 2022 17:52:51 -0400 Subject: [PATCH 2/6] feat: remove dated sourcemap from hermes profile page --- docs/profile-hermes.md | 24 +----------------------- 1 file changed, 1 insertion(+), 23 deletions(-) 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` From 419daafa4712771b04138749bd506117f60724c4 Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Fri, 9 Sep 2022 10:03:04 -0400 Subject: [PATCH 3/6] refactor: drop section of debug for hint as hermesFlagsDebug --- docs/sourcemaps.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/sourcemaps.md b/docs/sourcemaps.md index 873d1ad08a8..4c22df8c24d 100644 --- a/docs/sourcemaps.md +++ b/docs/sourcemaps.md @@ -55,16 +55,7 @@ Writing bundle output to:, android/app/build/generated/assets/react/release/inde 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 enable source maps like: - -Editing `android/app/build.gradle` file with: - -```groovy -project.ext.react = [ - bundleInDebug: true, - hermesFlagsDebug: ["-O", "-output-source-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 From 098ae1d5693829f24dea4183ea54ef7a466e65b2 Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Wed, 21 Sep 2022 13:03:00 -0400 Subject: [PATCH 4/6] refactor: adjusting grammar and removing ToC Co-authored-by: Bartosz Kaszubowski Co-authored-by: Dmytro Rykun --- docs/sourcemaps.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/sourcemaps.md b/docs/sourcemaps.md index 4c22df8c24d..624dd172a77 100644 --- a/docs/sourcemaps.md +++ b/docs/sourcemaps.md @@ -3,9 +3,9 @@ id: sourcemaps title: Source Maps --- -Source maps help map a minified file back to an un-packaged state. This is common when investigating issues from release builds. +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. -This helps if you have a stacktrace like +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 @@ -25,11 +25,7 @@ TypeError: Cannot read property 'data' of undefined This allows to triage release issues given a more accurate stacktrace. -Follow the instructions below to get started with source maps: - -1. [Enable source maps on Android](sourcemaps.md#enable-source-maps-on-android) -2. [Enable source maps on iOS](sourcemaps.md#enable-source-maps-on-ios) -3. [Manual Symbolication](sourcemaps.md#manual-symbolication) +Follow the instructions below to get started with source maps. ## Enable source maps on Android @@ -59,9 +55,9 @@ Development builds do not produce a bundle and thus already have symbols, but if ## Enable source maps on iOS -Source maps are built in Release mode by default. However, you might want to redirect the location of the source map for easier use. +Source maps are disabled by default. To enable them one has to define `SOURCEMAP_FILE` environment variable. -If so, within Xcode head to the build phrase - "Bundle React Native code and images" +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: From 9363198c4c6b0341dd6593bdcbcc259f5fd98c1b Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Wed, 21 Sep 2022 13:06:37 -0400 Subject: [PATCH 5/6] style: add missing period --- docs/sourcemaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sourcemaps.md b/docs/sourcemaps.md index 624dd172a77..319093239f7 100644 --- a/docs/sourcemaps.md +++ b/docs/sourcemaps.md @@ -57,7 +57,7 @@ Development builds do not produce a bundle and thus already have symbols, but if 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" +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: From 4f5e072c01163587f6c1bb83493b3fff7b3a5d3f Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Wed, 21 Sep 2022 13:12:53 -0400 Subject: [PATCH 6/6] refactor: reword sourcemap line --- docs/sourcemaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sourcemaps.md b/docs/sourcemaps.md index 319093239f7..604ebae92e9 100644 --- a/docs/sourcemaps.md +++ b/docs/sourcemaps.md @@ -14,7 +14,7 @@ TypeError: Cannot read property 'data' of undefined at p(app:///index.android.bundle:1:227785) ``` -The power of source maps allow tracing that line and column number back to the original source stacktrace. +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