docs: improve tree shaking docs

.changeset/four-radios-poke.md

@@ -0,0 +1,2 @@
+---
+---

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

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