Skip to content

Commit

Permalink
docs: add back source-map-explorer for SDK 50 and below
Browse files Browse the repository at this point in the history
  • Loading branch information
byCedric committed Jun 18, 2024
1 parent af21505 commit 96dffaf
Showing 1 changed file with 77 additions and 1 deletion.
78 changes: 77 additions & 1 deletion docs/pages/guides/analyzing-bundles.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { Terminal } from '~/ui/components/Snippet';

Bundle performance varies for different platforms. For example, web browsers don't support precompiled bytecode, so the JavaScript bundle size is important for improving startup time and performance. The smaller the bundle, the faster it can be downloaded and parsed.

## Analyzing bundle size
## Analyzing bundle size with Atlas

> Available only for **SDK 51 and above**.
Expand Down Expand Up @@ -48,6 +48,82 @@ You can also use Expo Atlas when generating a production bundle for your app or

You can also specify the platforms you want to analyze using the `--platform` option. Atlas will gather the data for the exported platforms only.

## Analyzing bundle size with source-map-explorer

> Alternative method for **SDK 50 and below**.
If you are using SDK 50 or below, you can use the [source-map-explorer](https://www.npmjs.com/package/source-map-explorer) package to visualize and analyze the production JavaScript bundle.

<Step label="1">

To use source map explorer, run the following command to install it:

<Terminal cmd={['$ npm i --save-dev source-map-explorer']} />

</Step>

<Step label="2">

Add a script to **package.json** to run it. You might have to adjust the input path depending on the platform or SDK you are using. For brevity, the following example assumes the project is Expo SDK 50 and does not use Expo Router `server` output.

```json package.json
{
"scripts": {
"analyze:web": "source-map-explorer 'dist/_expo/static/js/web/*.js' 'dist/_expo/static/js/web/*.js.map'",
"analyze:ios": "source-map-explorer 'dist/_expo/static/js/ios/*.js' 'dist/_expo/static/js/ios/*.js.map'",
"analyze:android": "source-map-explorer 'dist/_expo/static/js/android/*.js' 'dist/_expo/static/js/android/*.js.map'"
}
}
```

If you are using the SDK 50 `server` output for web, then use the following to map web bundles:

<Terminal
cmd={[
"$ npx source-map-explorer 'dist/client/_expo/static/js/web/*.js' 'dist/client/_expo/static/js/web/*.js.map'",
]}
/>

Web bundles are output to the **dist/client** subdirectory to prevent exposing server code to the client.

</Step>

<Step label="3">

Export your production JavaScript bundle and include the `--source-maps` flag so that the source map explorer can read the source maps:

<Terminal
cmd={[
'$ npx expo export --source-maps --platform web',
'# Native apps using Hermes can disable bytecode for analyzing the JavaScript bundle.',
'$ npx expo export --source-maps --platform ios --no-bytecode',
]}
/>

This command shows the JavaScript bundle and source map paths in the output. In the next step, you will pass these paths to the source map explorer.

> Avoid publishing source maps to production as they can cause both security issues and performance issues (a browser will download the large maps).
</Step>

<Step label="4">

Run the script to analyze your bundle:

<Terminal cmd={['$ npm run analyze:web']} />

On running this command, you might see the following error:

```text
You must provide the URL of lib/mappings.wasm by calling SourceMapConsumer.initialize({ 'lib/mappings.wasm': ... }) before using SourceMapConsumer
```

This is probably due to a [known issue](https://github.com/danvk/source-map-explorer/issues/247) in `source-map-explorer` in Node.js 18 and above. To resolve this, set the environment variable `NODE_OPTIONS=--no-experimental-fetch` before running the analyze script.

</Step>

You might encounter a warning such as `Unable to map 809/13787 bytes (5.87%)`. This occurs because source maps often exclude bundler runtime definitions (for example, `__d(() => {}, [])`). This value is consistent and not a reason for concern.

## Lighthouse

Lighthouse is a great way to see how fast, accessible, and performant your website is. You can test your project with the **Audit** tab in Chrome, or with the [Lighthouse CLI](https://github.com/GoogleChrome/lighthouse#using-the-node-cli).
Expand Down

0 comments on commit 96dffaf

Please sign in to comment.