diff --git a/.changeset/four-radios-poke.md b/.changeset/four-radios-poke.md new file mode 100644 index 0000000000..a845151cc8 --- /dev/null +++ b/.changeset/four-radios-poke.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/docsite/docs/guides/bundling.mdx b/docsite/docs/guides/bundling.mdx index 96932e55d5..e540816f25 100644 --- a/docsite/docs/guides/bundling.mdx +++ b/docsite/docs/guides/bundling.mdx @@ -277,6 +277,9 @@ Tree shaking is _off_ by default. You can control it with the } ``` +For setup details, options, bundle-size checks, and known limitations, see the +[`@rnx-kit/metro-serializer-esbuild` documentation](/docs/tools/metro-serializer-esbuild). + ### Duplicate Dependencies Did you know that your app bundle can have multiple copies of a single package diff --git a/packages/metro-serializer-esbuild/README.md b/packages/metro-serializer-esbuild/README.md index 9febbbc5aa..419726f331 100644 --- a/packages/metro-serializer-esbuild/README.md +++ b/packages/metro-serializer-esbuild/README.md @@ -38,6 +38,55 @@ Native below 0.64. ## Usage +If you use `@rnx-kit/cli` (or `react-native rnx-bundle`), enable tree shaking in +your rnx-kit configuration: + +```json +{ + "rnx-kit": { + "bundle": { + "entryFile": "index.js", + "targets": ["android", "ios"], + "treeShake": true + } + } +} +``` + +Then create a production bundle: + +```sh +react-native rnx-bundle --platform ios --dev false +``` + +The `treeShake` property can also be an options object for this serializer. See +the [Options](#options) section for all available options. + +```json +{ + "rnx-kit": { + "bundle": { + "treeShake": { + "analyze": true, + "metafile": "dist/esbuild-meta.json", + "drop": ["debugger"] + } + } + } +} +``` + +For one-off validation, use the command-line override: + +```sh +react-native rnx-bundle --platform ios --dev false --tree-shake true +``` + +Tree shaking only runs for production bundles. If `--dev` is true, it is turned +off even when `treeShake` is enabled. + +### Manual Metro Setup + esbuild works best when we pass it ES6 modules. The first thing we must do is to disable import/export transformation by enabling `disableImportExportTransform` in `babel.config.js`: @@ -242,6 +291,10 @@ format. See the full documentation at https://esbuild.github.io/api/#metafile. +You can load the generated JSON in the +[esbuild bundle size analyzer](https://esbuild.github.io/analyze/) to inspect +which modules contributed to the final bundle. + ## Metro + ESM Support Metro currently does not support ESM. However, if you're looking to save even