-
Notifications
You must be signed in to change notification settings - Fork 46
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(docs): add faq documents (#125)
- Loading branch information
Showing
5 changed files
with
125 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
["faq"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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**. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -13,5 +13,10 @@ | |
"type": "dir", | ||
"name": "topic", | ||
"label": "专题" | ||
}, | ||
{ | ||
"type": "dir", | ||
"name": "more", | ||
"label": "更多" | ||
} | ||
] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
["faq"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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` 模式和普通模式的区别就是不再存储**源码信息**,只存储**打包后的代码**,同时分析报告上的代码也将**只有打包后的代码**。 |