From 40bf59447b122e23d13406274764235f063e3a12 Mon Sep 17 00:00:00 2001 From: yifancong Date: Mon, 30 Sep 2024 15:07:28 +0800 Subject: [PATCH] chore(docs): add bundle-diff documents (#546) --- packages/components/src/utils/i18n/cn.ts | 15 +- packages/document/docs/en/guide/start/cli.mdx | 19 +++ .../document/docs/en/guide/start/features.mdx | 2 +- .../document/docs/en/guide/usage/_meta.json | 3 +- .../docs/en/guide/usage/bundle-diff.mdx | 129 ++++++++++++++++++ packages/document/docs/zh/guide/start/cli.mdx | 19 +++ .../document/docs/zh/guide/start/features.mdx | 2 +- .../document/docs/zh/guide/usage/_meta.json | 3 +- .../docs/zh/guide/usage/bundle-diff.mdx | 129 ++++++++++++++++++ 9 files changed, 312 insertions(+), 9 deletions(-) create mode 100644 packages/document/docs/en/guide/usage/bundle-diff.mdx create mode 100644 packages/document/docs/zh/guide/usage/bundle-diff.mdx diff --git a/packages/components/src/utils/i18n/cn.ts b/packages/components/src/utils/i18n/cn.ts index bd5117dd..afb237fa 100644 --- a/packages/components/src/utils/i18n/cn.ts +++ b/packages/components/src/utils/i18n/cn.ts @@ -17,20 +17,25 @@ const cn: typeof en = { 'Project Overall': '项目信息概览', 'Compile Overall': '编译数据概览', 'Bundle Overall': '产物数据概览', - 'Expand Omitted': ' reasons 树会默认折叠中间的第三方引入的模块，点击这个图标可以查看完整树图', + 'Expand Omitted': + ' reasons 树会默认折叠中间的第三方引入的模块，点击这个图标可以查看完整树图', 'Concatenated Tag': '串联模块，hover 上去可以显示聚合成的主模块名称。注：聚合模块 bundled size 为零，有可能是因为被聚合到了主模块中。', - 'the file content not changed after transpiled by this loader': '该文件内容在 loader 处理前后没有发生变化', + 'the file content not changed after transpiled by this loader': + '该文件内容在 loader 处理前后没有发生变化', /** Bundle Size */ 'Output Assets List': '产物文件列表', - 'filter the output assets which size is greater than the input value': '筛选大小大于输入值的产物文件', - 'filter the modules which size is greater than the input value': '筛选大小大于输入值的模块', + 'filter the output assets which size is greater than the input value': + '筛选大小大于输入值的产物文件', + 'filter the modules which size is greater than the input value': + '筛选大小大于输入值的模块', 'After Compile': '编译后', 'After Bundle': '打包后', CodeModeExplain: 'Lite 模式下或纯 stats.json 上传的情况下只有 source code.', - DuplicatePakCodeExplain: '纯 stats.json 输入的情况下没有代码，可使用 web-doctor 插件参与构建会有对应代码。', + DuplicatePakCodeExplain: + '纯 stats.json 输入的情况下没有代码，可使用 Rsdoctor 插件参与构建会有对应代码。', }; export default cn; diff --git a/packages/document/docs/en/guide/start/cli.mdx b/packages/document/docs/en/guide/start/cli.mdx index 5a1d486f..79cd70f5 100644 --- a/packages/document/docs/en/guide/start/cli.mdx +++ b/packages/document/docs/en/guide/start/cli.mdx @@ -49,6 +49,25 @@ rsdoctor analyze --profile rsdoctor analyze --profile "./dist/.rsdoctor/manifest.json" ``` +### `bundle-diff` Command + +The `bundle-diff` command is used to load **two** [manifest.json](/config/options/term#manifestjson) files **locally** and open the Rsdoctor [Bundle Diff](../usage/bundle-diff) page for **comparison and analysis of build bundles**. + +```bash +rsdoctor bundle-diff --baseline --current +``` + +**Parameter Definitions** + +- `baselineManifestJsonPath` Path to the [manifest.json](/config/options/term#manifestjson) used as the **baseline** (supports local paths as well as online URLs). +- `currentManifestJsonPath` Path to the [manifest.json](/config/options/term#manifestjson) used as the **current** (supports local paths as well as online URLs) for comparison with the **baseline**. + +**Usage Example** + +```bash +rsdoctor bundle-diff --baseline="baseline/.rsdoctor/manifest.json" --current="current/.rsdoctor/manifest.json" +``` + ## Node API We provide a Node.js API in `@rsdoctor/cli` that allows you to make calls during runtime in Node.js. diff --git a/packages/document/docs/en/guide/start/features.mdx b/packages/document/docs/en/guide/start/features.mdx index a248ad49..ca322b8c 100644 --- a/packages/document/docs/en/guide/start/features.mdx +++ b/packages/document/docs/en/guide/start/features.mdx @@ -33,4 +33,4 @@ Here you can learn about the main features supported by Rsdoctor. | Bundle Analysis | Analysis of the relationships between assets, chunks, and modules in the artifact, as well as the packaged code and size analysis of each module, etc. | [Bundle Analysis](../usage/bundle-size) | | Module Analysis | Analysis of module dependencies | [Modules Dependency Analysis](../usage/module-analysis) | | Duplicate Packages Optimization | Inspection of duplicate dependencies used in the project | [Duplicate Packages Optimization](../../blog/topic/duplicate-pkg-problem) | -| Bundle Diff | Comparative analysis of two artifacts | Planned support | +| Bundle Diff | Comparative analysis of two artifacts | [Bundle Diff](../usage/bundle-diff) | diff --git a/packages/document/docs/en/guide/usage/_meta.json b/packages/document/docs/en/guide/usage/_meta.json index bf2c99f1..704c0a66 100644 --- a/packages/document/docs/en/guide/usage/_meta.json +++ b/packages/document/docs/en/guide/usage/_meta.json @@ -10,5 +10,6 @@ "bundle-size", "module-analysis", "resolver", - "rule-config" + "rule-config", + "bundle-diff" ] diff --git a/packages/document/docs/en/guide/usage/bundle-diff.mdx b/packages/document/docs/en/guide/usage/bundle-diff.mdx new file mode 100644 index 00000000..6f0252e5 --- /dev/null +++ b/packages/document/docs/en/guide/usage/bundle-diff.mdx @@ -0,0 +1,129 @@ +# Bundle Diff + + + +We provide the Bundle Diff feature, which allows you to compare and analyze the changes between two build bundles. + +Currently, we offer the following usage methods: + +- [Open locally with CLI](/guide/start/cli) +- Online upload analysis (planned support) + +## Usage + +### Open locally with CLI + +First, you need to prepare **2 copies** of the [manifest.json](/config/options/term#manifestjson) produced by Rsdoctor. Then, install [@rsdoctor/cli](/guide/start/cli#cli-tutorial) and use the CLI command `bundle-diff`. For detailed command usage, see [command usage tutorial](/guide/start/cli#bundle-diff-command). + +### Online upload analysis (planned support) + +We plan to provide an online page for Bundle Diff analysis. You can upload **2 copies** of the [manifest.json](/config/options/term#manifestjson) produced by Rsdoctor on the page, one as the Baseline and the other as the Current. By clicking Start Diff, you can enter our analysis page. + + + +## User Guide + +### Feature Overview + +In the Bundle Diff module, you can see the comparison of information between the two build bundles, including: + +- **total size changes** +- **size changes of different file types** +- **initial bundles size changes** +- **changes in the number of duplicate packages** +- **changes in the number of NPM Packages**, and more. + +In addition to the above data overview, we can also perform more in-depth data query and analysis through the **details list** module at the bottom of the page. + +### Terminology + +| Term | Description | +| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| Baseline | Represents the **reference data source** | +| Current | Represents the **target data source** to be compared with the Baseline | +| Asset / Assets | Represents the **build files** | +| Bundle Size | Represents the **total size** of all files in the build | +| Total JS | Represents the total size of all `.js` files in the build | +| Initial JS | Represents the total size of all **first screen** `.js` files in the build | +| Total CSS | Represents the total size of all `.css` files in the build | +| Initial CSS | Represents the total size of all **first screen** `.css` files in the build | +| Image | Represents the total size of all `.png`/`.jpg`/`.svg`/`.webp`/`.jpeg`/`.gif`/`.bmp` files in the build | +| Font | Represents the total size of all `.ttf`/`.fnt`/`.fon`/`.otf` files in the build | +| Media | Represents the total size of all `.mp3`/`.mp4`/`.avi`/`.wav`/`.flv`/`.mov`/`.mpg`/`.mpeg` files in the build | +| HTML | Represents the total size of all `.html` files in the build | +| Duplicate Packages | Represents the **total number of duplicate packages** in the build | +| Modules | Represents the total number of modules in the build | +| Packages | Represents the total number of **NPM Packages** in the build | +| New | Represents **newly added** items, i.e., **not present in Baseline but present in Current** | +| Deleted | Represents **removed** items, i.e., **present in Baseline but not in Current** | +| Changed | Represents items that **only changed in content**, i.e., **present in both Baseline and Current but with content changes** | +| Parsed Size | Represents the **final size** of the build bundles | + +### Instructions + +#### Dashboard + +At the top of the page, we can see many data points composed of different cards, including the following information: + +- **Bundle Size** includes the total size of the two builds and the change rate. +- **Total JS | Initial JS** includes the total size and change rate of all JS and first screen JS in the two builds. +- **Total CSS | Initial CSS** includes the total size and change rate of all CSS and first screen CSS in the two builds. +- **Image | Font | Media** includes the size and change rate of image, font, and media files. +- **HTML** includes the size and change rate of HTML files. +- **Others** represents the size and change rate of all other files not mentioned above. +- **Duplicate Package** represents the number of duplicate packages in the two builds. Clicking on it allows you to view the details of the duplicate packages. +- **Modules** represents the number of modules in the two builds. +- **Packages** represents the total number of NPM Packages in the two builds, as well as the number of new, deleted, and changed packages. + + + +#### Overview + +In the Overview module, we can see the **size**, **quantity**, and **change rate** of different **file types**. + + + +#### Assets + +:::tip +When displaying Asset names, Rsdoctor tries to remove the hash values from the build file names to facilitate comparison. +::: + +In the Assets module, we can see the **size** and **change rate** of the build files. + + + +By **clicking** the **"+" button** in front of the list items, you can expand to see the **list of modules** contained in the corresponding Asset (i.e., `Modules of "xxx"`), which shows the **size** and **change rate** of the modules. + + + +Rsdoctor is compatible with the situation where Assets files have **the same name but different hashes**. However, for Assets with **different names generated by splitting packages**, Rsdoctor cannot identify their comparison objects. + +Therefore, the Rsdoctor Assets module also provides a select component, allowing you to **manually select the Assets resources you want to compare**. + + + +#### Modules + +In the Modules module, we can see the **name**, **size**, and **change rate** of all modules contained in the two builds. + +The `New` / `Deleted` / `Changed` tags indicate whether the module is newly added, deleted, or just changed in the `Current` build. + +The `node_modules` tag indicates that the module's path contains `/node_modules/`. + + + +On the right side of the list items, you can view the module code changes by clicking the corresponding "View Changes" button. + +**Code comparison includes several types of data:** + +- **Source Code: Source code data.** Available in `Normal` mode, not available in `Lite` mode, and not available in `Brief` mode. +- **Bundled Code: Built code.** Available in `Normal` mode, available in `Lite` mode, and not available in `Brief` mode. + + + +#### Packages + +In the Packages module, we can see the **list of all NPM Packages** contained in the two builds. Each list item includes the **Package Name**, **Version**, and **Parsed Size** (final size after packaging). + + diff --git a/packages/document/docs/zh/guide/start/cli.mdx b/packages/document/docs/zh/guide/start/cli.mdx index 876ca260..bf981c2f 100644 --- a/packages/document/docs/zh/guide/start/cli.mdx +++ b/packages/document/docs/zh/guide/start/cli.mdx @@ -49,6 +49,25 @@ rsdoctor analyze --profile rsdoctor analyze --profile "./dist/.rsdoctor/manifest.json" ``` +### bundle-diff 命令 + +`bundle-diff` 命令是用于在**本地**加载**两份** [manifest.json](/config/options/term#manifestjson) 并且打开 Rsdoctor 的 [Bundle Diff](../usage/bundle-diff) 页面进行**构建产物的对比和分析**。 + +```bash +rsdoctor bundle-diff --baseline --current +``` + +**参数定义** + +- `baselineManifestJsonPath` 当作 **基准** 的 [manifest.json](/config/options/term#manifestjson) 的路径（支持本地路径以及在线 url） +- `currentManifestJsonPath` 当作 **当前** 的 [manifest.json](/config/options/term#manifestjson) 的路径（支持本地路径以及在线 url），用于和 **基准** 进行对比 + +**使用示例** + +```bash +rsdoctor bundle-diff --baseline="baseline/.rsdoctor/manifest.json" --current="current/.rsdoctor/manifest.json" +``` + ## Node API 我们在 `@rsdoctor/cli` 中提供了 Node.js API，可以让你在 Node.js 运行时进行调用。 diff --git a/packages/document/docs/zh/guide/start/features.mdx b/packages/document/docs/zh/guide/start/features.mdx index 575425a1..8afeaed3 100644 --- a/packages/document/docs/zh/guide/start/features.mdx +++ b/packages/document/docs/zh/guide/start/features.mdx @@ -33,4 +33,4 @@ | 产物分析 | 产物中 assets、chunks、modules 关系分析，以及每个 module 打包代码及大小分析等 | [产物分析](../usage/bundle-size) | | 模块分析 | Modules 依赖关系分析 | [Modules 依赖链分析](../usage/module-analysis) | | 重复包优化 | 检查项目使用的依赖包的重复情况 | [重复包优化](../../blog/topic/duplicate-pkg-problem) | -| Bundle Diff | 两份产物对比分析 | 计划支持 | +| Bundle Diff | 两份产物对比分析 | [Bundle Diff](../usage/bundle-diff) | diff --git a/packages/document/docs/zh/guide/usage/_meta.json b/packages/document/docs/zh/guide/usage/_meta.json index bf2c99f1..704c0a66 100644 --- a/packages/document/docs/zh/guide/usage/_meta.json +++ b/packages/document/docs/zh/guide/usage/_meta.json @@ -10,5 +10,6 @@ "bundle-size", "module-analysis", "resolver", - "rule-config" + "rule-config", + "bundle-diff" ] diff --git a/packages/document/docs/zh/guide/usage/bundle-diff.mdx b/packages/document/docs/zh/guide/usage/bundle-diff.mdx new file mode 100644 index 00000000..62df53d5 --- /dev/null +++ b/packages/document/docs/zh/guide/usage/bundle-diff.mdx @@ -0,0 +1,129 @@ +# Bundle Diff + + + +我们提供了 Bundle Diff 的功能，可以让你进行对比分析两次构建产物发生的变化。 + +目前我们提供了以下几种使用方式： + +- [CLI 本地打开](/guide/start/cli) +- 在线上传分析（计划支持） + +## 使用方式 + +### CLI 本地打开 + +首先你需要准备 **2 份** Rsdoctor 产出的[manifest.json](/config/options/term#manifestjson)，然后通过安装[@rsdoctor/cli](/guide/start/cli#%E5%AE%89%E8%A3%85-rsdoctorcli) 并使用 CLI 提供的 `bundle-diff` 命令，详见[命令使用教程](/guide/start/cli#bundle-diff-%E5%91%BD%E4%BB%A4)。 + +### 在线上传分析（计划支持） + +我们计划提供了一个在线页面用于 Bundle Diff 分析，你可以通过在页面中上传 **2 份** Rsdoctor 产出的[manifest.json](/config/options/term#manifestjson)，其中一份作为基准（Baseline），另一份则作为当前产物结果 (Current)，通过点击 Start Diff 则就可以进入我们的分析页面。 + + + +## 使用指南 + +### 功能概览 + +在 Bundle Diff 模块，你可以看到两次产物结果的信息对比，其中包含: + +- **总体积变化** +- **不同类型文件的体积变化** +- **首屏资源的体积变化** +- **重复包的数量变化** +- **NPM Packages 的数量变化** 等信息 + +除了上面的数据变化概览之外，我们还能通过页面下方的**详情列表**模块，进行更深入的数据查询分析。 + +### 名词释义 + +| 名词 | 描述说明 | +| -------------------------------- | ---------------------------------------------------------------------------------- | +| Baseline | 代表作为**基准的数据源** | +| Current | 代表当前需要**与 Baseline 进行对比的目标数据源** | +| Asset / Assets | 代表当前**产物文件** | +| Bundle Size | 代表产物中**所有文件**的体积 | +| Total JS | 代表产物中所有 `.js` 文件的体积 | +| Initial JS | 代表产物中所有**首屏**加载的 `.js` 文件的体积 | +| Total CSS | 代表产物中所有 `.css` 文件的体积 | +| Initial CSS | 代表产物中所有**首屏**加载的 `.css` 文件的体积 | +| Image | 代表产物中所有 `.png`/`.jpg`/`.svg`/`.webp`/`.jpeg`/`.gif`/`.bmp` 的文件体积 | +| Font | 代表产物中所有 `.ttf`/`.fnt`/`.fon`/`.otf` 的文件体积 | +| Media | 代表产物中所有 `.mp3`/`.mp4`/`.avi`/`.wav`/`.flv`/`.mov`/`.mpg`/`.mpeg` 的文件体积 | +| HTML | 代表产物中所有 `.html` 的文件体积 | +| Duplicate Packages | 代表产物中存在的**重复包总数** | +| Modules | 代表产物中 Module 总数 | +| Packages | 代表产物中存在的 **NPM Packages 总数** | +| New | 代表**新增**，即 **Baseline 中不存在，Current 中存在** | +| Deleted | 代表**移除了**，即 **Baseline 中存在，Current 中不存在** | +| Changed | 代表**只发生了内容改变**，即 **Baseline 和 Current 中都存在**，但是**内容变化**了 | +| Parsed Size | 代表**打包进产物的最终体积** | + +### 使用说明 + +#### Dashboard + +在页面顶部，我们可以看到很多数据由不同的卡片组成，其中包含了如下信息： + +- **Bundle Size** 包含了两次产物总体积以及变化幅度。 +- **Total JS | Initial JS** 包含了两次产物中 所有 JS 与 首屏 JS 的总体积以及变化幅度。 +- **Total CSS | Initial CSS** 包含了两次产物中 所有 CSS 与 首屏 CSS 的总体积以及变化幅度。 +- **Image | Font | Media** 包含了图片、字体、音频类文件的体积以及变化幅度。 +- **HTML** 包含了 html 文件的体积以及变化幅度。 +- **Others** 代表除了上述文件外的其他所有文件的体积以及变化幅度。 +- **Duplicate Package** 代表两次产物中存在的重复包数量，点击则可以查看对应的重复包详情。 +- **Modules** 代表两次产物中存在的 Modules 数量。 +- **Packages** 代表两次产物中存在的 NPM Packages 总数，以及新增、删除、变更的数量变化。 + + + +#### Overview + +在 Overview 模块中，我们可以看到不同**文件类型维度**的**体积**、**数量**以及**变化幅度**。 + + + +#### Assets + +:::tip +Rsdoctor 在展示 Asset 名称时，会尝试移除产物文件名中的 hash 值，以方便进行产物文件对比。 +::: + +在 Assets 模块中，我们可以看到产物文件之间的**体积**以及**变化幅度**。 + + + +同时**点击**列表项目前的 **"+" 按钮**，则可以展开看到对应 Asset 所**包含的模块列表**（即 `Modules of "xxx"`），其中则会显示模块之间的**体积**以及**变化幅度**。 + + + +Rsdoctor 会**兼容同名 Assets 文件 hash 不同**的情况，但是对于**拆包产生的命名不同的 Assets**，Rsdoctor 则无法辨别其比较对象。 + +所以 Rsdoctor Assets 模块**还提供了 select 组件**，你可以**手动选择想要对比的 Assets 资源**。 + + + +#### Modules + +在 Modules 模块中，我们可以看到两次产物中包含的所有模块的**名称**、**体积**以及**变化幅度**。 + +其中 `New` / `Deleted` / `Changed` 标签则代表模块在 `Current` 中到底是 新增 还是 被删除 或者只是发生了改变。 + +而 `node_modules` 标签则意味着该模块的路径中包含了 `/node_modules/`。 + + + +在列表项的右侧，则可以通过对应的「View Changes」按钮来查看模块代码的变更。 + +**代码对比，分几种数据：** + +- **Source Code: 源码数据。** `Normal` 模式下存在代码资源，`Lite` 模式下不存在代码资源，`Brief` 模式不存在代码资源。 +- **Bundled Code: 构建后代码。** `Normal` 模式下存在代码资源，`Lite` 模式下存在代码资源，`Brief` 模式不存在代码资源。 + + + +#### Packages + +在 Packages 模块，我们可以看到两次产物中包含的**所有 NPM Packages 列表**，每个列表项则会包含其对应的 **Package Name**、**Version（版本号）**、**Parsed Size（打包后的最终体积）**。 + +