Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(RN): Improve documentation on React Native source maps #4452

Merged
merged 9 commits into from
Dec 1, 2021
1 change: 1 addition & 0 deletions src/platforms/react-native/manual-setup/codepush.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ codePush.getUpdateMetadata().then(update => {
Sentry.init({
// ...
release: `${update.appVersion}+codepush:${update.label}`,
dist: update.label,
});
}
});
Expand Down
32 changes: 25 additions & 7 deletions src/platforms/react-native/manual-setup/hermes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,34 +22,52 @@ If you do not need custom sourcemaps, the `sentry.gradle` build step fully suppo

## Custom Source Maps

If you are manually bundling and building React Native apps for Android, follow this three-step process. For Hermes on iOS, follow the [normal source maps guide](/platforms/react-native/sourcemaps/).
If you are manually bundling and building React Native apps, follow this three-step process.

### Compile for Android
### Compile Sourcemaps

1. Bundle/minify with `metro` (`react-native`) to get the packager source map (`.packager.map`):

```bash {tabTitle:Android}
npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output index.android.bundle --sourcemap-output index.android.bundle.packager.map
```

```bash {tabTitle:iOS}
npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output main.jsbundle --sourcemap-output main.jsbundle.packager.map
```

2. Compile to bytecode using `hermes` to get the compiler source map (`.hbc.map`):

<Note>
`OS-BIN` is `osx-bin`, `win64-bin`, or `linux64-bin`, depending on which operating system you are using.
</Note>
<Note>

`OS-BIN` is `osx-bin`, `win64-bin`, or `linux64-bin`, depending on which operating system you are using.

</Note>

```bash {tabTitle:Android}
node_modules/hermes-engine/{OS-BIN}/hermesc -O -emit-binary -output-source-map -out=index.android.bundle.hbc index.android.bundle
```

```bash {tabTitle:iOS}
node_modules/hermes-engine/{OS-BIN}/hermesc -O -emit-binary -output-source-map -out=main.jsbundle.hbc main.jsbundle
```

3. Merge the two source maps using `compose-source-maps` to get the final source map (`.map`):

```bash {tabTitle:Android}
node node_modules/react-native/scripts/compose-source-maps.js index.android.bundle.packager.map index.android.bundle.hbc.map -o index.android.bundle.map
```

```bash {tabTitle:iOS}
node node_modules/react-native/scripts/compose-source-maps.js main.jsbundle.packager.map main.jsbundle.hbc.map -o main.jsbundle.map
```

### Upload the Bundle and Source Maps

Upload your source maps following [Step 3 on the normal source maps guide](/platforms/react-native/sourcemaps/#3-upload-the-bundle-and-source-maps).

<Note>

You will upload the **original** bundle (output from Step 1) and the **composed** source map (output from Step 3)

</Note>
6 changes: 4 additions & 2 deletions src/platforms/react-native/sourcemaps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ Configure the CLI by reviewing the [configuration guide](/product/cli/configurat

### 2. Generate the bundle and source maps

<Alert level="warning" title="Hermes on Android">
<Alert level="warning" title="Hermes">

If you use the **Hermes engine** on Android, you will need to [follow this guide to compile source maps for Hermes on Android](/platforms/react-native/manual-setup/hermes/#custom-source-maps). This alternative step is not required for Hermes on iOS and you can continue following the steps below.
If you use the **Hermes engine**, you will need to [follow this guide to compile source maps for Hermes](/platforms/react-native/manual-setup/hermes/#custom-source-maps).

</Alert>

Expand Down Expand Up @@ -122,3 +122,5 @@ If source maps are still not recognized, check for warnings similar to:
![Missing sources warning](001-manual-sourcemaps.png)

The bundle filename needs to match the filename on the event (and shown on the warning) to correctly apply the source maps.

Find more troubleshooting cases in our [Troubleshooting documentation](/platforms/react-native/troubleshooting/#source-maps).
8 changes: 6 additions & 2 deletions src/platforms/react-native/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,13 @@ Common fixes to this issue include:

[For more details, please read the guide on React Native source maps.](/platforms/react-native/sourcemaps)

### Source Maps with Hermes on Android
### Source Maps With Hermes

You will need to perform some extra steps when using the source maps with the Hermes engine on Android. [You can follow the guide here.](/platforms/react-native/manual-setup/hermes/#custom-source-maps)
Although the build script should already handle this for you most of the time, you may need to perform some extra steps when using the source maps with the Hermes engine. [You can follow the guide here.](/platforms/react-native/manual-setup/hermes/#custom-source-maps).

### Different Bundles for Different Platforms

Your app could have different bundles for each platform that it supports, such as iOS and Android. To associate the correct bundle and sourcemap to each platform, you will need a unique release/dist combination for each platform. An easy way to do this is to include the platform name in the `dist` value.

## iOS Build Script Failed

Expand Down