react-native-bundle-discovery-ui 2.5.0 → 2.7.0-rc.0

package/README.md

@@ -1,73 +1,92 @@
 # react-native-bundle-discovery
 
-[![react-native-bundle-discovery on npm](https://badgen.net/npm/v/react-native-bundle-discovery)](https://www.npmjs.com/package/react-native-bundle-discovery)
-[![react-native-bundle-discovery downloads](https://badgen.net/npm/dm/react-native-bundle-discovery)](https://www.npmtrends.com/react-native-bundle-discovery)
-
-A simple package that helps developers visualize and analyze the bundle size of React Native apps.
-With this tool, you can easily explore your app's codebase, identify large or heavy packages, and inspect the structure of modules and code within your project.
-
-<img width="800" alt="" src="./assets/img.png" />
-
-### Packages:
-
-- `react-native-bundle-discovery` - simple JS library to generate a JSON report of the bundle.
-- `react-native-bundle-discovery-ui` - UI to visualize the bundle report.
-- `react-native-bundle-discovery-cli` - CLI to analyze the bundle report.
-- `react-native-bundle-discovery-rozenite-plugin` - Rozenite plugin to integrate UI tool to [React Native DevTools](https://reactnative.dev/docs/react-native-devtools).
-
----
-
-### Setup:
-
-There are two ways to install the package:
-
-1. As in independent tool (UI + CLI)
-2. Or as a [Rozenite](_rozenite/README.md) plugin (see: [_rozenite/README.md](_rozenite/README.md))
-
-
-> 🚀 If you've migrated to [Re.Pack](https://re-pack.dev/), you can still use this package to analyze 📊 JS bundles 📦 generated by Re.Pack.
+[![npm version](https://badgen.net/npm/v/react-native-bundle-discovery)](https://www.npmjs.com/package/react-native-bundle-discovery)
+[![npm downloads](https://badgen.net/npm/dm/react-native-bundle-discovery)](https://www.npmtrends.com/react-native-bundle-discovery)
+[![license](https://badgen.net/npm/license/react-native-bundle-discovery)](https://www.npmjs.com/package/react-native-bundle-discovery)
+
+Visualize and analyze the JS bundle of your React Native app. Find heavy packages, duplicates and deprecated
+dependencies, inspect every module, and catch bundle size regressions in CI.
+
+<img width="800" alt="Bundle Discovery UI" src="./assets/img.png" />
+
+## Contents
+
+- [Features](#features)
+- [Packages](#packages)
+- [Quick start](#quick-start)
+- [Other setups](#other-setups)
+- [Usage](#usage)
+  - [UI](#ui)
+  - [CLI](#cli)
+  - [Bundle size checks in CI](#bundle-size-checks-in-ci)
+- [API](#api)
+  - [`createSerializer`](#createserializeroptions)
+  - [`createResolveRequest`](#createresolverequestoptions)
+- [Similar projects](#similar-projects)
+- [Support the project](#support-the-project)
+- [License](#license)
+
+## Features
+
+- 📊 Interactive UI to explore packages, modules and their source/bundled code
+- 💡 Optimization recommendations (duplicates, deprecated / outdated / dev-only packages, and more)
+- 🔍 CLI to list the heaviest packages and modules
+- 🆚 Compare two reports and fail CI on bundle size regressions
+- 🧩 Works with Metro, [Re.Pack](./Re.Pack.md) and [React Native DevTools](./packages/rozenite-plugin/README.md) (via Rozenite)
+
+## Packages
+
+| Package                                                                  | What it does                                                                                    | Required |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | -------- |
+| `react-native-bundle-discovery`                                          | Generates a JSON report (`metro-stats.json`) of your bundle                                     | ✅ Yes   |
+| `react-native-bundle-discovery-ui`                                       | Shows the report in the browser                                                                 | Optional |
+| `react-native-bundle-discovery-cli`                                      | Analyzes and compares reports in the terminal / CI                                              | Optional |
+| [`react-native-bundle-discovery-rozenite-plugin`](./packages/rozenite-plugin/README.md) | Shows the UI inside [React Native DevTools](https://reactnative.dev/docs/react-native-devtools) | Optional |
+
+## Quick start
+
+This setup is for a standard **Metro** project.
+Using Re.Pack or Rozenite? See [Other setups](#other-setups).
+
+> [!TIP]
+> **Using an AI coding agent?** Skip the manual steps below. Point your agent (Claude Code, Cursor, Codex, etc.)
+> at the [`setup-react-native-bundle-discovery`](./skills/setup-react-native-bundle-discovery/SKILL.md) skill.
+> It installs the package and sets up Metro or Re.Pack for you:
 >
-> 💡 Learn more: 📖 [Re.Pack.md](./Re.Pack.md)
+> ```bash
+> npx skills add retyui/react-native-bundle-discovery
+> ```
 
-#### 1. Install (independent tool)
+### 1. Install
 
 ```bash
-yarn add -D react-native-bundle-discovery # required for generating the JSON report
-yarn add -D react-native-bundle-discovery-ui # optional: used for visualizing the report in the browser
-yarn add -D react-native-bundle-discovery-cli # optional: used for analysis of the report in the CLI
+yarn add -D react-native-bundle-discovery      # required: generates the report
+yarn add -D react-native-bundle-discovery-ui   # optional: browser UI
+yarn add -D react-native-bundle-discovery-cli  # optional: CLI
 ```
 
-Add to your `metro.config.js`:
+### 2. Configure Metro
 
 ```diff
 // metro.config.js
-const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
-+const {createSerializer} = require('react-native-bundle-discovery');
-
-+const mySerializer = createSerializer({
-+  includeCode: true, // Useful if you want to compare source/bundle code (but a report file will be larger)
-+  projectRoot: __dirname,
-+   //^^^ ⚠️ WARNING: In a monorepo setup, this should point to the monorepo root,
-+   //                not the individual package directory.
-+});
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
++const { createSerializer } = require('react-native-bundle-discovery');
 
 -const config = {};
 +const config = {
-  serializer: { customSerializer: mySerializer },
-};
++  serializer: {
++    customSerializer: createSerializer({
++      projectRoot: __dirname, // ⚠️ In a monorepo, use the monorepo root instead
++    }),
++  },
++};
 
 module.exports = mergeConfig(getDefaultConfig(__dirname), config);
 ```
 
-#### 2. Install (as plugin for Rozenite)
-
-See: [_rozenite/README.md](_rozenite/README.md)
-
----
-
-### 3. Build the app
+See all options in [`createSerializer`](#createserializeroptions).
 
-For example, for iOS you can run the following command, and it will generate the `metro-stats.json` file in the root of your project:
+### 3. Build a release bundle
 
 ```bash
 npx react-native bundle \
@@ -78,97 +97,153 @@ npx react-native bundle \
   --assets-dest ios/assets
 ```
 
-### 4. Commands
+This writes `metro-stats.json` to your project root.
+
+### 4. Explore the report
+
+```bash
+npx react-native-bundle-discovery-ui metro-stats.json   # open in the browser
+npx react-native-bundle-discovery-cli metro-stats.json  # get recommendations in the terminal
+```
 
-#### CLI package
+## Other setups
 
-You need to install `react-native-bundle-discovery-cli`
+| Setup                      | Guide                                                                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Re.Pack (Rspack / Webpack) | [Re.Pack.md](./Re.Pack.md)                                                                                                   |
+| React Native DevTools      | [Rozenite plugin](./packages/rozenite-plugin/README.md)                                                                                     |
+| AI coding agent            | Point your agent at the [`setup-react-native-bundle-discovery`](./skills/setup-react-native-bundle-discovery/SKILL.md) skill |
+
+## Usage
+
+### UI
+
+Requires `react-native-bundle-discovery-ui`.
+
+```bash
+# Start a local server (default port: 8079)
+npx react-native-bundle-discovery-ui metro-stats.json [--port <port>]
+
+# Build a static HTML report (default output: .bundle-discovery)
+npx react-native-bundle-discovery-ui build metro-stats.json [--output <path>]
+```
+
+### CLI
+
+Requires `react-native-bundle-discovery-cli`. Run any command with `--help` to see all options.
+
+| Command    | Description                                   |
+| ---------- | --------------------------------------------- |
+| _(none)_   | Show recommended optimizations for the bundle |
+| `packages` | List all packages in the bundle               |
+| `modules`  | List the heaviest modules                     |
+| `compare`  | Compare two reports                           |
 
 ```bash
-# Display all recommended optimizations for the bundle
+# Recommended optimizations
 npx react-native-bundle-discovery-cli metro-stats.json
 
-# Display all packages in the bundle report
+# All packages
 npx react-native-bundle-discovery-cli packages metro-stats.json [--sort size|name] [--format json|table|default]
 
-# Display the heaviest modules in the bundle report (default limit: 50, --limit 0 shows all)
-# --filter accepts plain text (case-insensitive) or a regexp: --filter '/\.json/i'
+# Heaviest modules (default --limit: 50, use 0 to show all)
+# --filter accepts plain text (case-insensitive) or a regexp, e.g. --filter '/\.json/i'
 npx react-native-bundle-discovery-cli modules metro-stats.json [--limit 50] [--filter <text|/regexp/>] [--sort size|name] [--format json|table|default]
+
+# Diff two reports: total size, added/removed/changed modules and packages,
+# version changes, new duplicates and new deprecated packages
+npx react-native-bundle-discovery-cli compare --before main-stats.json --after pr-stats.json [--limit 50] [--format json|markdown|default]
 ```
 
-#### UI package
+### Bundle size checks in CI
 
-You need to install `react-native-bundle-discovery-ui`
+`compare` exits with code `1` when any check fails:
 
-```bash
-# Start server to view the report in the browser (default port: 8079)
-npx react-native-bundle-discovery-ui metro-stats.json [--port <port>]
+| Option               | Fails when                                                    | Example                         |
+| -------------------- | ------------------------------------------------------------- | ------------------------------- |
+| `--fail-on-increase` | The bundle grows more than the limit (bytes or % of "before") | `50KB`, `0.5MB`, `51200`, `5%`  |
+| `--max-size`         | The "after" bundle is bigger than the limit                   | `3MB`                           |
+| `--fail-on`          | New duplicate and/or deprecated packages appear               | `new-duplicates,new-deprecated` |
 
-# Build the report into a static HTML file
-npx react-native-bundle-discovery-ui build metro-stats.json
+```bash
+npx react-native-bundle-discovery-cli compare --before main-stats.json --after pr-stats.json \
+  --fail-on-increase 50KB \
+  --max-size 3MB \
+  --fail-on new-duplicates,new-deprecated
 ```
 
----
+**GitHub Actions** works out of the box: the markdown report is added to the job summary and failed checks
+are shown as error annotations.
+
+```yaml
+- run: npx react-native-bundle-discovery-cli compare --before main-stats.json --after pr-stats.json --fail-on-increase 5%
+```
 
-### `react-native-bundle-discovery` JS API
+To post the report as a PR comment, use `--format markdown`.
 
-#### `createSerializer(options: Options)`
+## API
 
-| Prop                   | Default value             | Description                                                                                                                              |
-| ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| serializer: Function   | Default serializer        | A custom serializer function. If not provided, a default serializer is used.                                                             |
-| projectRoot: string    | Required                  | The root directory of the project. ⚠️ In a monorepo setup, this should point to the monorepo root, not the individual package directory. |
-| outputJsonPath: string | `<root>/metro-stats.json` | The path where the JSON report will be saved. Defaults to `metro-stats.json` in project root.                                            |
-| includeCode: boolean   | `true`                    | Whether to include the source and output code in the JSON report.                                                                        |
+Exported from `react-native-bundle-discovery`.
 
-**⚠️ Be cautious sharing reports with `includeCode` enabled**
+### `createSerializer(options)`
 
-Enabling this option significantly increases report size and **embeds the source code** of your assets.
+Creates a Metro serializer that writes the JSON report. Use it as `serializer.customSerializer` (see [Quick start](#2-configure-metro)).
 
-If your code is proprietary 🔒, share these reports responsibly 🤝!
+| Option                  | Type       | Default                          | Description                                                                               |
+| ----------------------- | ---------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
+| `projectRoot`           | `string`   | **Required**                     | Project root. ⚠️ In a monorepo, use the monorepo root, not the app package directory.     |
+| `outputJsonPath`        | `string`   | `<projectRoot>/metro-stats.json` | Where to save the report.                                                                 |
+| `includeCode`           | `boolean`  | `true`                           | Include source and bundled code of each module in the report (larger file).               |
+| `includeEnvs`           | `string[]` | `[]`                             | Names of environment variables to include in the report.                                  |
+| `fetchPackagesMetadata` | `boolean`  | `true`                           | Fetch package metadata (publish date, deprecation, latest version) from the npm registry. |
+| `silent`                | `boolean`  | `false`                          | Disable log output.                                                                       |
+| `serializer`            | `Function` | Metro default serializer         | Custom serializer to wrap.                                                                |
 
----
+> [!WARNING]
+> With `includeCode: true` (the default) the report **contains your source code**.
+> If your code is proprietary, be careful who you share the report with.
 
-### `createResolveRequest(options: ResolveRequestOptions)`
+### `createResolveRequest(options)`
 
-| Prop                           | Default value | Description                                                                                                                   |
-| ------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| removePromisePolyfill: boolean | `false`       | Remove the Promise polyfill as Hermes provide own impl. (issue: [#57702](https://github.com/react/react-native/issues/57702)) |
-| removeUTFSequence: boolean     | `false`       | Remove useless undocumented RN module.                                                                                        |
+Creates a Metro `resolveRequest` that removes unnecessary React Native modules from **release** bundles
+(dev builds are not affected). The CLI recommends these options when they apply to your bundle.
 
-Helper that creates a custom resolve request function to filter out unnecessary modules from the bundle.
-You can get recommendations during the analysis of the bundle report using the CLI tool.
+| Option              | Type      | Default | Description                                                                      |
+| ------------------- | --------- | ------- | -------------------------------------------------------------------------------- |
+| `removeUTFSequence` | `boolean` | `false` | Remove the unused `react-native/Libraries/UTFSequence.js` module.                |
+| `removeNewRenderer` | `boolean` | `false` | Remove the Fabric renderer. Enable only if the New Architecture is **disabled**. |
 
 ```js
 // metro.config.js
 const { createResolveRequest } = require("react-native-bundle-discovery");
-const resolveRequest = createResolveRequest({
-  removePromisePolyfill: true,
-  removeUTFSequence: true,
-});
+
 const config = {
   resolver: {
-    resolveRequest,
+    resolveRequest: createResolveRequest({
+      removeUTFSequence: true,
+    }),
   },
 };
 ```
 
-### Financial Contributors
+## Similar projects
 
-Become a financial contributor at [OpenCollective](https://opencollective.com/react-native-bundle-discovery) or [GitHub Sponsors](https://github.com/sponsors/retyui)
+- [expo-atlas](https://github.com/expo/atlas)
+- [expo-atlas-without-expo](https://github.com/v3ron/expo-atlas-without-expo)
+- [react-native-bundle-visualizer](https://github.com/callstack/react-native-bundle-visualizer)
+- [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)
+- [bundle-stats](https://github.com/relative-ci/bundle-stats/tree/master/packages/cli#readme)
+- [statoscope](https://github.com/statoscope/statoscope)
 
-### Other
+Built with [Discovery.js](https://github.com/discoveryjs/discovery)
+([views showcase](https://discoveryjs.github.io/discovery/#views-showcase),
+[Jora syntax](https://discoveryjs.github.io/jora/#article:jora-syntax-operators)).
 
-**Similar projects:**
+## Support the project
 
-- [expo-atlas](https://github.com/expo/atlas) [![expo-atlas downloads](https://badgen.net/npm/dm/expo-atlas)](https://www.npmtrends.com/expo-atlas) [![expo-atlas install size](https://packagephobia.com/badge?p=expo-atlas)](https://packagephobia.com/result?p=expo-atlas)
-- [expo-atlas-without-expo](https://github.com/v3ron/expo-atlas-without-expo) [![expo-atlas-without-expo downloads](https://badgen.net/npm/dm/expo-atlas-without-expo)](https://www.npmtrends.com/expo-atlas-without-expo) [![expo-atlas-without-expo install size](https://packagephobia.com/badge?p=expo-atlas-without-expo)](https://packagephobia.com/result?p=expo-atlas-without-expo)
-- [react-native-bundle-visualizer](https://github.com/callstack/react-native-bundle-visualizer) [![react-native-bundle-visualizer downloads](https://badgen.net/npm/dm/react-native-bundle-visualizer)](https://www.npmtrends.com/react-native-bundle-visualizer)[![react-native-bundle-visualizer install size](https://packagephobia.com/badge?p=react-native-bundle-visualizer)](https://packagephobia.com/result?p=react-native-bundle-visualizer)
-- [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) [![webpack-bundle-analyzer downloads](https://badgen.net/npm/dm/webpack-bundle-analyzer)](https://www.npmtrends.com/webpack-bundle-analyzer)[![webpack-bundle-analyzer install size](https://packagephobia.com/badge?p=webpack-bundle-analyzer)](https://packagephobia.com/result?p=webpack-bundle-analyzer)
-- [bundle-stats](https://github.com/relative-ci/bundle-stats/tree/master/packages/cli#readme) [![bundle-stats downloads](https://badgen.net/npm/dm/bundle-stats)](https://www.npmtrends.com/bundle-stats)[![bundle-stats install size](https://packagephobia.com/badge?p=bundle-stats)](https://packagephobia.com/result?p=bundle-stats)
-- [statoscope](https://github.com/statoscope/statoscope) [![@statoscope/cli downloads](https://badgen.net/npm/dm/@statoscope/cli)](https://www.npmtrends.com/@statoscope/cli)[![@statoscope/cli install size](https://packagephobia.com/badge?p=@statoscope/cli)](https://packagephobia.com/result?p=@statoscope/cli)
+Become a financial contributor on [OpenCollective](https://opencollective.com/react-native-bundle-discovery)
+or [GitHub Sponsors](https://github.com/sponsors/retyui).
 
-**Built using [Discovery.js](https://github.com/discoveryjs/discovery):**
+## License
 
-- Build blocks for pages: https://discoveryjs.github.io/discovery/#views-showcase
-- Jora syntax: https://discoveryjs.github.io/jora/#article:jora-syntax-operators
+MIT

package/assets/global.css

@@ -0,0 +1,171 @@
+hr {
+  border: 1px solid rgb(222 222 222);
+  margin-top: 1rem;
+  margin-bottom: 1rem;
+}
+
+.inline-block {
+  display: inline-block;
+}
+.discovery-content > .page-default {
+  height: 100%;
+  overflow: hidden;
+  padding-top: 16px;
+  padding-bottom: 16px;
+}
+.view-tabs-content > .view-content-filter > .view-input {
+  padding-top: 12px;
+  padding-bottom: 12px;
+  margin: 0;
+  background-color: var(--discovery-background-color);
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+.main-tabs {
+  height: calc(100% - 20px);
+  margin-top: 12px;
+}
+.main-tabs .view-tabs-content {
+  height: calc(100% - 32px);
+}
+.foamtree-filter,
+.view-foamtree {
+  width: 100%;
+  height: 100%;
+}
+.foamtree-filter > .content {
+  height: calc(100% - 60px);
+  width: 100%;
+}
+.tooltip {
+  position: absolute;
+  z-index: 10;
+  display: none;
+  background-color: #fff;
+  border: 1px solid #ccc;
+  padding: 5px;
+  border-radius: 5px;
+  box-shadow: 0 0 5px #ccc;
+}
+.tooltip-name {
+  text-transform: capitalize;
+}
+.flex-no-wrap {
+  flex-wrap: nowrap;
+}
+.width-50p {
+  width: 50%;
+}
+.my-icon {
+  display: block;
+  height: 100%;
+  width: 100%;
+}
+.my-icon-inline {
+  display: inline-block;
+  vertical-align: middle;
+  margin-left: 4px;
+}
+.my-icon-12 {
+  width: 12px;
+  height: 12px;
+}
+.no-margin {
+  margin: 0;
+}
+.two-column > * {
+  width: 50%;
+}
+.m-v-8 {
+  margin-top: 8px;
+  margin-bottom: 8px;
+}
+.i-duplicate {
+  display: inline-block;
+  background: #da444e;
+  color: #fff;
+  border-radius: 0.5em;
+  padding: 0 0.5em;
+}
+.m-l-0_5em {
+  margin-left: 0.5em;
+}
+.m-r-0_3em {
+  margin-right: 0.3em;
+}
+.copy-to-clipboard {
+  /* from: https://tabler.io/icons/icon/clipboard-copy */
+  background: url("data:image/svg+xml,%3Csvg%20%20xmlns=%22http://www.w3.org/2000/svg%22%20%20width=%2224%22%20%20height=%2224%22%20%20viewBox=%220%200%2024%2024%22%20%20fill=%22none%22%20%20stroke=%22currentColor%22%20%20stroke-width=%222%22%20%20stroke-linecap=%22round%22%20%20stroke-linejoin=%22round%22%20%20class=%22icon%20icon-tabler%20icons-tabler-outline%20icon-tabler-clipboard-copy%22%3E%3Cpath%20stroke=%22none%22%20d=%22M0%200h24v24H0z%22%20fill=%22none%22/%3E%3Cpath%20d=%22M9%205h-2a2%202%200%200%200%20-2%202v12a2%202%200%200%200%202%202h3m9%20-9v-5a2%202%200%200%200%20-2%20-2h-2%22%20/%3E%3Cpath%20d=%22M13%2017v-1a1%201%200%200%201%201%20-1h1m3%200h1a1%201%200%200%201%201%201v1m0%203v1a1%201%200%200%201%20-1%201h-1m-3%200h-1a1%201%200%200%201%20-1%20-1v-1%22%20/%3E%3Cpath%20d=%22M9%203m0%202a2%202%200%200%201%202%20-2h2a2%202%200%200%201%202%202v0a2%202%200%200%201%20-2%202h-2a2%202%200%200%201%20-2%20-2z%22%20/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center;
+  display: inline-block;
+  height: 32px;
+  width: 32px;
+}
+.copy-to-clipboard::before {
+  position: absolute;
+  top: -8px;
+  font-size: 0.7rem;
+  border-radius: 4px;
+  display: inline-block;
+  padding: 1px 4px;
+  color: #fff;
+  left: 78%;
+  opacity: 0;
+  transition: opacity 0.3s ease-in-out;
+}
+.copy-to-clipboard.done::before {
+  content: "Copied!";
+  background: green;
+  opacity: 1;
+}
+.copy-to-clipboard.err::before {
+  content: "Error!";
+  background: red;
+  opacity: 1;
+}
+.prettify-checkbox {
+  position: absolute;
+  right: 31px;
+  margin-top: -26px;
+  z-index: 1;
+}
+.ask-chatgpt {
+  color: var(--discovery-view-button-color, #000);
+  text-decoration: none;
+  vertical-align: middle;
+  position: absolute;
+  z-index: 9;
+  margin-top: 12px;
+  /* biome-ignore lint/complexity/noImportantStyles: overrides discovery.js styles */
+  margin-left: 105px !important;
+  height: 35px;
+}
+.ask-chatgpt::before {
+  content: "”";
+  font-size: 2em;
+  vertical-align: middle;
+  font-family: math;
+  margin-right: 0.2em;
+  display: inline-block;
+  height: 15px;
+}
+/* biome-ignore lint/style/noDescendingSpecificity: order is intentional, kept as is */
+.packages-content > .view-input {
+  padding-left: 265px;
+}
+.copy-before-ask-chatgpt {
+  width: 95px;
+  background-position: left center;
+  padding-left: 25px;
+  position: absolute;
+  z-index: 9;
+  margin-top: 12px;
+  height: 35px;
+}
+.bundlejs-badge-img {
+  line-height: 0;
+  margin-bottom: -5px;
+  margin-left: 10px;
+}