@rsdoctor/docs 0.0.0-next-20240620044732

package/docs/zh/guide/start/cli.mdx

@@ -0,0 +1,94 @@
+# CLI 使用教程
+
+我们提供了 `@rsdoctor/cli` 让你可以在本地通过 CLI 程序来使用 Rsdoctor 提供的功能
+
+:::tip
+`@rsdoctor/webpack-plugin`、`@rsdoctor/rspack-plugin` 与 `@rsdoctor/cli` 要保持同一个 major 和 minor 版本。
+:::
+
+## 安装 @rsdoctor/cli
+
+:::tip
+
+- @rsdoctor/cli & @rsdoctor/webpack-plugin & @rsdoctor/rspack-plugin >= 0.1.2。
+- 可以使用非安装方式，使用 `npx @rsdoctor/cli <command> [options]`。
+
+:::
+
+import { PackageManagerTabs } from '@theme';
+
+import { Tab, Tabs } from 'rspress/theme';
+
+<PackageManagerTabs command="add @rsdoctor/cli -D" />
+
+## 命令使用
+
+```linux
+
+rsdoctor <command> [options]
+
+```
+
+`@rsdoctor/cli` 目前提供了以下几个命令对应不同的功能：
+
+### analyze 命令
+
+`analyze` 命令主要是用于在**本地**加载 [manifest.json](../../config/options/term.mdx) 并且无需再次构建直接启动 Rsdoctor 的分析报告页面。
+
+```linux
+rsdoctor analyze --profile <manifestFile>
+```
+
+**参数定义**
+
+- `manifestFile` 即为 [manifest.json](../../config/options/term.mdx) 的路径（支持本地路径）
+
+**使用示例**
+
+```bash
+rsdoctor analyze --profile "./dist/.rsdoctor/manifest.json"
+```
+
+## Node API
+
+我们在 `@rsdoctor/cli` 中提供了 Node.js API，可以让你在 Node.js 运行时进行调用。
+
+**引入模块**
+
+<Tabs>
+
+<Tab label="cjs">
+
+```js
+const { execute } = require('@rsdoctor/cli');
+```
+
+</Tab>
+
+<Tab label="esm">
+
+```js
+import { execute } from '@rsdoctor/cli';
+```
+
+</Tab>
+
+</Tabs>
+
+**execute()**
+
+`execute` 异步函数是 Rsdoctor CLI 的执行函数，通过调用 `execute` 函数就会自动解析 [process.argv](https://nodejs.org/dist/latest-v18.x/docs/api/process.html#processargv)，然后调用不同的命令。
+
+**execute('analyze', \{...\})**
+
+如果你需要通过 Node.js API 直接执行 [analyze 命令](#analyze-命令)，则可以通过如下方式调用：
+
+```ts
+execute('analyze', {
+  profile: 'input the manifest.json path or url',
+}).then((sdk) => {
+  console.log('execute "anaylze" command success');
+  // you can stop the Rsdoctor's dev-server by calling the sdk'api below:
+  // sdk.dispose();
+});
+```

package/docs/zh/guide/start/features.mdx

@@ -0,0 +1,36 @@
+# 功能导航
+
+在这里，你可以了解到 Rsdoctor 支持的主要功能。
+
+## 构建概览
+
+| 功能     | 描述                           | 相关链接                             |
+| -------- | ------------------------------ | ------------------------------------ |
+| 项目概览 | 查看当前项目配置、版本等信息   | [项目概览](../usage/project-overall) |
+| 产物概览 | 查看当前项目构建产物的信息     | [产物概览](../usage/bundle-overall)  |
+| 编译概览 | 查看当前项目编译过程的数据信息 | [编译概览](../usage/compile-overall) |
+| 产物预警 | 基于构建产物数据做检测的能力   | [产物预警](../usage/bundle-alerts)   |
+| 编译预警 | 基于编译数据做检测的能力       | [编译预警](../usage/compile-overall) |
+
+## 编译分析
+
+| 功能                  | 描述                                                     | 相关链接                                                        |
+| --------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
+| 编译概览              | 查看当前项目编译过程的数据信息                           | [编译概览](../usage/compile-overall)                            |
+| 编译预警              | 基于编译数据做检测的能力                                 | [编译预警](../usage/compile-alerts)                             |
+| Loader 编译行为分析   | 以目录与文件维度的 Loader 分析数据，展示单个文件编译行为 | [Loaders 分析](../usage/loaders-analysis)                       |
+| Loaders 耗时分析      | 当前项目中所有 Loader 的执行时序图                       | [Loaders 时序图](../usage/loaders-timeline)                     |
+| Plugins 分析          | 项目所使用插件的数据分析                                 | [Plugins 分析](../usage/plugins-analysis)                       |
+| Resolver 分析         | Resolver 解析能力分析数据                                | [Resolver 分析](../usage/resolver)                              |
+| Loader 耗时分析及优化 | 该文档介绍如何使用 Rsdoctor 进行构建耗时分析并优化       | [ Loader 耗时分析及优化 ](../../blog/topic/loader-optimization) |
+
+## 构建产物分析
+
+| 功能        | 描述                                                                          | 相关链接                                             |
+| ----------- | ----------------------------------------------------------------------------- | ---------------------------------------------------- |
+| 产物概览    | 查看当前项目构建产物的信息                                                    | [产物概览](../usage/bundle-overall)                  |
+| 产物预警    | 基于构建产物数据做检测的能力                                                  | [产物预警](../usage/bundle-alerts)                   |
+| 产物分析    | 产物中 assets、chunks、modules 关系分析，以及每个 module 打包代码及大小分析等 | [产物分析](../usage/bundle-size)                     |
+| 模块分析    | Modules 依赖关系分析                                                          | [Modules 依赖链分析](../usage/module-analysis)       |
+| 重复包优化  | 检查项目使用的依赖包的重复情况                                                | [重复包优化](../../blog/topic/duplicate-pkg-problem) |
+| Bundle Diff | 两份产物对比分析                                                              | 计划支持                                             |

package/docs/zh/guide/start/intro.mdx

@@ -0,0 +1,116 @@
+# 介绍
+
+## 💡 什么是 Rsdoctor？
+
+- Rsdoctor 是一个面向构建过程与构建产物提供诊断和分析的一站式工具。
+- Rsdoctor 是一个支持 Webpack 及 Rspack 构建分析工具。
+- Rsdoctor 是一个可以展示编译耗时及编译行为细节的分析工具。
+- Rsdoctor 是一个提供 Bundle Diff 等防劣化能力的工具。
+
+## 🔥 特性
+
+- **编译可视化**：Rsdoctor 将编译行为及耗时进行可视化展示，方便开发同学查看构建问题。
+- **多种分析能力**：支持构建产物、构建时分析能力：
+  - 构建产物支持资源列表及模块依赖等。
+  - 构建时分析支持 Loader、Plugin、Resolver 构建过程分析。
+  - 支持 Rspack 的 builtin:swc-loader 分析。
+  - 构建规则支持重复包检测及 ES Version Check 检查等。
+- **支持自定义规则**：除了内置构建扫描规则外，还支持用户根据 Rsdoctor 的构建数据添加自定义构建扫描规则。
+- **框架无关**：支持所有基于 Webpack 或 Rspack 构建的项目。
+
+## 🛠️ 功能介绍
+
+### ⭐️ 概览
+
+- 概览页（即首页）能够知道**项目配置、诊断信息、编译信息、产物情况**。
+
+![Overall](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/overall.jpg)
+
+- 除了有项目概览之外，我们还提供了诊断模块，分别是编译诊断、重复包诊断等。如果你的编译、产物命中了我们定义的诊断规则，就会在工具首页出现对应的警示模块, **其中重复包可以查看到详细的引用路径**:
+
+![Overall-Alerts](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/overall-alerts.jpg)
+
+### ⭐️ 编译分析
+
+面向 **Loaders、Plugins、Module Resolve** 提供了对应的数据与分析功能，来帮助你分析编译过程上的问题。
+
+#### Loader 分析
+
+- 该模块主要提供了 **Rspack 或 Webpack 的 Loaders** 内的输入输出、预估耗时、参数等数据分析的功能。
+
+<div style={{ display: 'flex' }}>
+  <img
+    src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/loader-timeline-overall.png"
+    width="55%"
+    style={{ margin: 'auto' }}
+  />
+  <img
+    src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/loader-anlaysis-all.png"
+    width="45%"
+    style={{ margin: 'auto' }}
+  />
+</div>
+
+#### Plugin 分析
+
+- 该模块主要拦截并收集了 Plugins 的调用次数、预估耗时等数据信息。
+
+<p>
+  <img
+    alt="bundle"
+    src={
+      'https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/compile-plugin.jpg'
+    }
+    width="600px"
+    style={{ margin: 'auto' }}
+  />
+</p>
+
+#### Resolve 分析
+
+- 该模块主要提供了项目内部单个文件中模块解析的路径数据以及预估耗时。Rspack 暂时未支持该模块。
+
+<p>
+  <img
+    alt="bundle"
+    src={
+      'https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/resolver.jpeg'
+    }
+    width="700px"
+    style={{ margin: 'auto' }}
+  />
+</p>
+
+### ⭐️ 产物分析
+
+- 我们在「Bundle Size」模块中，可以看到当前项目的产物数据信息概览，以及分析重复包引入的体积与原因。
+
+- 此外，我们还可以通过「Bundle Analysis」 模块来进一步分析当前产物中产物与模块关系，体积数据等信息以及模块引入的原因。
+
+<p>
+  <img
+    alt="bundle"
+    src={
+      'https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/bundle-size.jpg'
+    }
+    width="700px"
+    style={{ margin: 'auto' }}
+  />
+</p>
+
+### ⭐️ Bundle Diff
+
+::: tip
+功能支持中...
+:::
+
+使用 Rsdoctor 提供的 Bundle Diff 功能，可以看到产物内的资源体积、重复包、Packages 等数据的变化以及每个资源中的模块文件的大小及代码的变化。
+
+| ![bundle-diff-1](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/bundle-diff-2.png) | ![bundle-diff-2](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/bundle-diff-1.png) |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+
+## 🧑‍💻 社区
+
+欢迎加入我们的 [Discord](https://discord.gg/wrBPBT6rkM) 交流频道！Rsdoctor 团队和用户都在那里活跃，并且我们一直期待着各种贡献。
+
+你也可以加入 [飞书群](https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=3c3vca77-bfc0-4ef5-b62b-9c5c9c92f1b4) 与大家一起交流。

package/docs/zh/guide/start/quick-start-shared.mdx

@@ -0,0 +1,183 @@
+## 第二步：注册插件
+
+依赖安装完成后，你需要在项目中接入 Rsdoctor 插件，下面是一些常见工具和框架的示例：
+
+### Rspack 项目
+
+在 `rspack.config.js` 的 [plugins](https://www.rspack.dev/config/plugins.html#plugins) 中初始化 RsdoctorRspackPlugin 插件，参考：
+
+```js title="rspack.config.js"
+const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');
+
+module.exports = {
+  // ...
+  plugins: [
+    // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
+    process.env.RSDOCTOR &&
+      new RsdoctorRspackPlugin({
+        // 插件选项
+      }),
+  ].filter(Boolean),
+};
+```
+
+- **Options:** 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+
+### Rsbuild 项目
+
+在 `rsbuild.config.ts` 的 [tools.rspack](https://rsbuild.dev/config/tools/rspack) 中初始化 RsdoctorWebpackPlugin 插件，参考：
+
+```js title="rsbuild.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  // ...
+  tools: {
+    rspack(config, { appendPlugins }) {
+      // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
+      if (process.env.RSDOCTOR) {
+        appendPlugins(
+          new RsdoctorRspackPlugin({
+            // 插件选项
+          }),
+        );
+      }
+    },
+  },
+};
+```
+
+- **Options:** 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+
+### Webpack 项目
+
+在 `webpack.config.js` 的 [plugins](https://webpack.js.org/configuration/plugins/#plugins) 中初始化 RsdoctorWebpackPlugin 插件，参考：
+
+```js title="webpack.config.js"
+const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+
+module.exports = {
+  // ...
+  plugins: [
+    // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
+    process.env.RSDOCTOR &&
+      new RsdoctorWebpackPlugin({
+        // 插件选项
+      }),
+  ].filter(Boolean),
+};
+```
+
+- **Options:** 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+
+### Modern.js 项目
+
+在 `modern.config.ts` 的 [tools.bundlerChain](https://modernjs.dev/configure/app/tools/rspack) 中初始化插件，参考：
+
+```ts title="modern.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  // ...
+  tools: {
+    rspack(config, { appendPlugins }) {
+      // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
+      if (process.env.RSDOCTOR) {
+        appendPlugins(
+          new RsdoctorRspackPlugin({
+            // 插件选项
+          }),
+        );
+      }
+    },
+  },
+};
+```
+
+- **Options:** 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+
+:::tip
+对于使用 Modern.js Webpack 模式的项目，请使用 [tools.webpack](https://modernjs.dev/configure/app/tools/webpack) 注册 `RsdoctorWebpackPlugin` 插件。
+:::
+
+### Next.js 项目
+
+在 `next.config.js` 的 [Webpack Config](https://nextjs.org/docs/app/api-reference/next-config-js/webpack) 中初始化 RsdoctorWebpackPlugin 插件。
+
+```ts title="next.config.mjs"
+import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+
+export default {
+  // ...
+  webpack: (config, { isServer }) => {
+    config.plugins.push(
+      new RsdoctorWebpackPlugin({
+        // 插件选项
+      }),
+    );
+    return config;
+  },
+};
+```
+
+- **Options:** 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+
+#### 📢 Next.js 项目使用注意
+
+1. Next.js 项目报告页面问题
+
+详情查看：[FAQ](../more/faq#nextjs)
+
+2. Next.js 中不支持对 rules 进行重写的 Loader 分析
+
+详情查看：[FAQ](../more/faq#nextjs)
+
+### Vue 项目
+
+在配置文件中初始化 `@rsdoctor/webpack-plugin` 或 `@rsdoctor/rspack-plugin` 插件，以下是使用 rsbuild 项目作为示例：
+
+```ts title="rsbuild.config.ts"
+import { defineConfig } from '@rsbuild/core';
+import { pluginVue } from '@rsbuild/plugin-vue';
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default defineConfig({
+  plugins: [pluginVue()],
+  performance: {
+    buildCache: false,
+  },
+  tools: {
+    bundlerChain: (chain, { CHAIN_ID }) => {
+      chain.plugin('Rsdoctor').use(RsdoctorRspackPlugin, [
+        {
+          // 插件选项
+        },
+      ]);
+    },
+  },
+});
+```
+
+- **Options:** 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+
+#### 📢 Vue 项目使用注意
+
+由于目前不支持对 `vue-loader` 进行分析，对于 Vue 项目，默认情况下禁用了 loader 分析。但是，仍然可以进行插件和构建产物的分析。
+
+---
+
+## 第三步：执行构建
+
+现在你可以在项目内执行 **build** 命令，在完成构建后，Rsdoctor 会自动打开本次构建的分析页面。
+
+```bash
+# 开启 Rsdoctor
+RSDOCTOR=true npm run build
+
+# 未开启 Rsdoctor
+npm run build
+```
+
+:::tip
+Rsdoctor 插件提供了一些配置项，请参考 [Options](../../config/options/options)。
+:::

package/docs/zh/guide/start/quick-start.mdx

@@ -0,0 +1,29 @@
+# 快速开始
+
+本文档将介绍如何接入 Rsdoctor 能力。
+
+## 第一步：安装依赖
+
+import { PackageManagerTabs } from '@theme';
+
+### Rspack 项目
+
+基于 Rspack 或 Rsbuild 的项目，安装以下依赖：
+
+<PackageManagerTabs command="add @rsdoctor/rspack-plugin -D" />
+
+### Webpack 项目
+
+:::tip
+不支持 Webpack 4 项目。
+:::
+
+基于 Webpack 的项目，安装以下依赖：
+
+<PackageManagerTabs command="add @rsdoctor/webpack-plugin -D" />
+
+---
+
+import QuickStartShared from './quick-start-shared.mdx';
+
+<QuickStartShared />

package/docs/zh/guide/usage/_meta.json

@@ -0,0 +1,14 @@
+[
+  "project-overall",
+  "bundle-overall",
+  "compile-overall",
+  "compile-alerts",
+  "bundle-alerts",
+  "loaders-timeline",
+  "loaders-analysis",
+  "plugins-analysis",
+  "bundle-size",
+  "module-analysis",
+  "resolver",
+  "rule-config"
+]

package/docs/zh/guide/usage/bundle-alerts.mdx

@@ -0,0 +1,49 @@
+# 产物预警
+
+## 功能介绍
+
+### 重复第三方包
+
+- `Duplicate Packages` 卡片上展示了项目重复第三方包数目。点击图片可以查看重复第三方包的具体详情。注：这里的第三方都是被打包的第三方包。
+
+  <div style={{ display: 'flex' }}>
+    <img
+      src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-1.png"
+      height="200px"
+      width="360px"
+      style={{ margin: 'auto' }}
+    />
+    <img
+      src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-2.png"
+      height="300px"
+      width="440px"
+      style={{ margin: 'auto' }}
+    />
+  </div>
+
+- 重复包预警卡片
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts.png" />
+
+- 点击图标展开重复包详情，可以看到：重复包的包名、版本、大小、引用文件。
+
+  - 点击最右侧 **「Show Relations」** 可以查看具体这个第三方的引用链路和对应的引用文件代码位置。
+
+  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-relations.png" />
+
+  - 点击最右侧 **「!（叹号）」** 图标，可以查看重复第三方包的规则的具体解释。
+
+  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-rule.png" />
+
+### 重复包优化问题
+
+请查看[重复包优化方案](../../blog/topic/duplicate-pkg-problem)。
+
+### ECMA 版本检查
+
+产物预警中会对产物进行 ECMA 版本做检查，如下图：
+
+{' '}
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts-ecma.png" />
+
+点击 「**More**」可以查看对应规则解释。

package/docs/zh/guide/usage/bundle-overall.mdx

@@ -0,0 +1,57 @@
+# 产物概览
+
+## 功能概览
+
+我们在启动 **Rsdoctor** 的首页中，会看到名为 `Bundle Overall` 的一个卡片，可以通过它了解到当前项目**构建产物**的信息，其内容如下图所示：
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/overall/bundle-overall-1.jpg"
+  width="400px"
+  height="500px"
+  style={{ margin: 'auto' }}
+/>
+
+## 名词释义
+
+| 名词                             | 描述说明                                                                           |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| <b><i>total files</i></b>        | 代表产物中所有文件的数量                                                           |
+| <b><i>total size</i></b>         | 代表产物中所有文件的总体积                                                         |
+| <b><i>js files</i></b>           | 代表产物中所有 `.js` 的文件数量                                                    |
+| <b><i>css files</i></b>          | 代表产物中所有 `.css` 文件数量                                                     |
+| <b><i>image files</i></b>        | 代表产物中所有 `.png`/`.jpg`/`.svg`/`.webp`/`.jpeg`/`.gif`/`.bmp` 的文件数量       |
+| <b><i>font files</i></b>         | 代表产物中所有 `.ttf`/`.fnt`/`.fon`/`.otf`/`.woff`/`.woff2` 的文件数量             |
+| <b><i>media files</i></b>        | 代表产物中所有 `.mp3`/`.mp4`/`.avi`/`.wav`/`.flv`/`.mov`/`.mpg`/`.mpeg` 的文件数量 |
+| <b><i>html files</i></b>         | 代表产物中所有 `.html` 的文件数量                                                  |
+| <b><i>modules</i></b>            | 代表产物中 module 总数                                                             |
+| <b><i>duplicate packages</i></b> | 代表产物中存在的重复包总数                                                         |
+
+## 使用说明
+
+### View Bundle Artifacts
+
+- 卡片上的 **「TOTAL Size」** 数据是项目的总大小。点击该数字可以跳转到 [Bundle Size 页面](./bundle-size.mdx)
+
+- 卡片上还可以查看到不同类型文件的个数及总 Size，点击对应的蓝色图标则可以查看到对应的文件列表，如下图：
+  - **Initial:** 是指该资源是入口的主 Chunk。
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/overall/bundle-overall-files.png"
+  width="400px"
+  height="600px"
+  style={{ margin: 'auto' }}
+/>
+
+### [Duplicate Packages](../../blog/topic/duplicate-pkg-problem.mdx)
+
+如果卡片中的 `Duplicate Packages` 显示的数字大于 0，则可以**点击来查看对应的重复包详情列表**，其内容如下图所示：
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/overall/bundle-overall-dup-pkg.jpg"
+  width="600px"
+  style={{ margin: 'auto' }}
+/>
+
+我们可以看到当前 Rsdoctor 在本次构建产物中检测出来的所有重复包的列表。
+
+更多请查看[重复第三方包](/guide/usage/bundle-alerts)。