Skip to content

Commit

Permalink
chore(docs): add faq documents (#125)
Browse files Browse the repository at this point in the history
  • Loading branch information
easy1090 authored Jan 17, 2024
1 parent fa0d784 commit 7c7a6bc
Show file tree
Hide file tree
Showing 5 changed files with 125 additions and 0 deletions.
1 change: 1 addition & 0 deletions document/docs/en/guide/more/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
["faq"]
59 changes: 59 additions & 0 deletions document/docs/en/guide/more/faq.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# FAQ

## How to use only a specific feature of Rsdoctor?

When we **only need** the bundle size analysis feature of Rsdoctor, we can configure the corresponding [Features](/config/options/index) option when integrating the Rsdoctor plugin. Refer to the code snippet below:

```ts
import { RsdoctorWebpackPlugin } from "@rsdoctor/webpack-plugin";

new RsdoctorWebpackPlugin({
features: ["bundle"], // Represents enabling only the bundle size analysis feature
});
```

## Loader time-consuming data is inaccurate?

The time-consuming data provided by Rsdoctor for loaders is an **estimated time**. Why can't it accurately measure the timing? It's because we know that loader execution can be both **asynchronous** and **synchronous**.
Additionally, the builder will **parallelize the execution** of multiple non-conflicting loader functions. Since JavaScript is single-threaded, multiple loader functions can **compete for the current task queue**.
Furthermore, the asynchronous logic within loader functions cannot be recognized, causing a single loader function to potentially span across the execution of multiple other loaders. As a result, there are three possible cases, as shown in the following diagram:

<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/loader-cases.jpeg" style={{ width: "250px" }} />

Therefore, the loader timing provided by Rsdoctor is an **estimate**. The timing data we provide is adapted to handle Case 1 and Case 2 from the diagram. As for Case 3, we are still exploring solutions.

## `out of memory` error when using `Rsdoctor` for building

If you encounter an `out of memory` error, you can try the following two methods, with the first one being recommended:

### Method 1

Increase the memory limit of Node, for example: NODE_OPTIONS=--max-old-space-size=8096.

### Method 2

You can add the `lite` field to the `features` array to use the lite mode. Additionally, since the `features` array overrides the default configuration when it is an array, you should:

- Add `loader` and `plugins` to the `features` array if you need build-time analysis to enable the analysis of loader and plugin timings.

- Add `bundle` to the `features` array if you need bundle analysis to enable the analysis of build artifacts.

The following example enables the lite mode, build-time analysis, and bundle analysis:

```js
const { RsdoctorWebpackPlugin } = require("@rsdoctor/webpack-plugin");

// adding the plugin to your configuration
module.exports = {
// ...
plugins: [
new RsdoctorWebpackPlugin({
disableClientServer: false,
features: ["lite", "loader", "plugins", "bundle"]
}),
].filter(Boolean),
};
```

- Cause: During the build process, the source code information is stored, which exceeds the memory limit. Enabling the `lite` mode can alleviate this issue.
- Difference: The difference between the **lite mode** and the **normal mode** is that the **lite mode** no longer stores the **source code information**, only the **bundled code** is stored. Additionally, the code displayed in the analysis report will only consist of the **bundled code**.
5 changes: 5 additions & 0 deletions document/docs/zh/guide/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,10 @@
"type": "dir",
"name": "topic",
"label": "专题"
},
{
"type": "dir",
"name": "more",
"label": "更多"
}
]
1 change: 1 addition & 0 deletions document/docs/zh/guide/more/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
["faq"]
59 changes: 59 additions & 0 deletions document/docs/zh/guide/more/faq.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# FAQ

## 如何只使用 Rsdoctor 的某个功能?

当我们**只需要** Rsdoctor 内 [Bundle Size]() {/* TODO: link */} 分析产物大小的功能时,我们可以在接入 Rsdoctor 插件时配置对应的 [Features](/config/options/index) 配置项,参考下方代码:

```ts
import { RsdoctorWebpackPlugin } from "@rsdoctor/webpack-plugin";

new RsdoctorWebpackPlugin({
features: ["bundle"], // 代表只开启 bundle size 的功能分析
});
```


## Loader 耗时数据不准?

Rsdoctor 提供的 Loader 耗时时间是**预估耗时**,为什么没法统计到准确耗时?是因为我们知道 Loader 执行可能是**异步**函数也可能是**同步**函数,同时,构建器会**并行执行多个**不冲突的 Loader 函数,其中 **JS 是单线程**的,多个 Loader 函数均可能**抢占当前的任务队列**,同时 Loader 函数内的**异步逻辑没法识别**,导致单个 Loader 函数在执行过程中,**可能横跨**多个其他 Loader 的执行过程,所以会存在如下图所示的三种 case:

<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/loader-cases.jpeg" style={{ width: "250px" }} />

因此,Rsdoctor 提供的 Loader 耗时是一个**预估**的数据,而我们给出的耗时数据适配了上图中 Case 1 和 Case 2 的情况,对于 Case 3 的解决方案,我们目前还在探索中。


## 使用 `Rsdoctor` 构建时出现了 `out of memory` 问题

如果出现了 `out of memory` 的报错,可以尝试下列两个方法,推荐优先使用第一个:

### 方法一

增大 node 内存上限, 例如:NODE_OPTIONS=--max-old-space-size=8096。

### 方法二

可以在 `features` 数组中添加 `lite` 字段,使用 lite 模式,同时,因为 features 为数组时会覆盖掉默认配置,所以:

- 如果需要构建时分析,`features` 数组中添加 `loader``plugins`,是开启 `loader``plugins` 的耗时分析。

- 如果需要构建产物分析,`features` 数组中添加 `bundle`,是开启构建产物分析。

下面示例是开启了 lite 模式以及构建时和构建产物分析:

```js
const { RsdoctorWebpackPlugin } = require("@rsdoctor/webpack-plugin");

// adding the plugin to your configuration
module.exports = {
// ...
plugins: [
new RsdoctorWebpackPlugin({
disableClientServer: false,
features: ["lite", "loader", "plugins", "bundle"]
}),
].filter(Boolean),
};
```

- 原因:因为构建过程中,存储了源码信息,超过了内存,所以开启 `lite` 模式可以缓解。
- 区别:`lite` 模式和普通模式的区别就是不再存储**源码信息**,只存储**打包后的代码**,同时分析报告上的代码也将**只有打包后的代码**

0 comments on commit 7c7a6bc

Please sign in to comment.