From e0d6e498d0ba1ab5f51918295f7928bf09eb9898 Mon Sep 17 00:00:00 2001
From: Vivek JM <vivekjm77@gmail.com>
Date: Sun, 17 May 2026 12:07:41 +0530
Subject: [PATCH 1/2] docs: improve tree shaking docs

---
 docsite/docs/guides/bundling.mdx            |  3 ++
 packages/metro-serializer-esbuild/README.md | 53 +++++++++++++++++++++
 2 files changed, 56 insertions(+)

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

From 86f60501a256189045e8239607e705172fa7dc1f Mon Sep 17 00:00:00 2001
From: Vivek JM <vivekjm77@gmail.com>
Date: Fri, 22 May 2026 19:05:20 +0530
Subject: [PATCH 2/2] docs(changeset):

---
 .changeset/four-radios-poke.md | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 .changeset/four-radios-poke.md

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 @@
+---
+---