diff --git a/packages/document/docs/en/config/options/options-shared.mdx b/packages/document/docs/en/config/options/options-shared.mdx index b4ae63b0..06142e55 100644 --- a/packages/document/docs/en/config/options/options-shared.mdx +++ b/packages/document/docs/en/config/options/options-shared.mdx @@ -23,6 +23,17 @@ Whether to automatically open the Rsdoctor report page. If you do not need to vi #### features values +The `features` attribute is used to analyze the function switches, and the specific functional items are as follows: + +- **loader**: Analysis of Loader time consumption and code compilation changes, enabled by default. +- **plugins**: Analysis of Plugins calls and time consumption, enabled by default. +- **bundle**: Analysis of build artifacts, enabled by default. +- **resolver**: resolver analysis, disabled by default. +- **lite**: [**depracated, please use [mode.lite](#mode)**] + lite mode. The difference between lite mode and normal mode is that source code information is no longer cached, only packaged code information is cached, so the code analyzed on the page will also be packaged. The default is normal mode. + +Therefore, **the default configuration enables bundle analysis capabilities and Loader and Plugin build-time analysis**. The Resolver analysis capability is not enabled, and Rspack does not currently support Resolver analysis capabilities. + :::tip **If an "out of memory" error occurs, you can try the following:** @@ -35,16 +46,6 @@ Whether to automatically open the Rsdoctor report page. If you do not need to vi ::: -The `features` attribute is used to analyze the function switches, and the specific functional items are as follows: - -- **loader**: Analysis of Loader time consumption and code compilation changes, enabled by default. -- **plugins**: Analysis of Plugins calls and time consumption, enabled by default. -- **bundle**: Analysis of build artifacts, enabled by default. -- **resolver**: resolver analysis, disabled by default. -- **lite**: lite mode. The difference between lite mode and normal mode is that source code information is no longer cached, only packaged code information is cached, so the code analyzed on the page will also be packaged. The default is normal mode. - -Therefore, **the default configuration enables bundle analysis capabilities and Loader and Plugin build-time analysis**. The Resolver analysis capability is not enabled, and Rspack does not currently support Resolver analysis capabilities. - #### features types - if the `features` is set as an `Array`, it will **open** the features which you define in this array **only**. diff --git a/packages/document/docs/en/config/options/options.mdx b/packages/document/docs/en/config/options/options.mdx index 9a78e718..10f8e27a 100644 --- a/packages/document/docs/en/config/options/options.mdx +++ b/packages/document/docs/en/config/options/options.mdx @@ -91,11 +91,22 @@ Whether to automatically open the Rsdoctor report page. If you do not need to vi #### features values +The `features` attribute is used to analyze the function switches, and the specific functional items are as follows: + +- **loader**: Analysis of Loader time consumption and code compilation changes, enabled by default. +- **plugins**: Analysis of Plugins calls and time consumption, enabled by default. +- **bundle**: Analysis of build bundles, enabled by default. +- **resolver**: resolver analysis, disabled by default. +- **lite**: [**depracated, please use [mode.lite](#mode)**] + lite mode. The difference between lite mode and normal mode is that source code information is no longer cached, only packaged code information is cached, so the code analyzed on the page will also be packaged. The default is normal mode. + +Therefore, **the default configuration enables bundle analysis capabilities and Loader and Plugin build-time analysis**. The Resolver analysis capability is not enabled, and Rspack does not currently support Resolver analysis capabilities. + :::tip **If an "out of memory" error occurs, you can try the following:** -1. Open the **lite** mode。 +1. Open the **lite** mode.[mode.lite](#mode) 2. Increase the node memory limit, for example: NODE_OPTIONS=--max-old-space-size=8096. - Reason: During the build process, source code information is cached, which exceeds memory. Therefore, enabling the **"lite" mode** can help alleviate the problem. @@ -103,63 +114,88 @@ Whether to automatically open the Rsdoctor report page. If you do not need to vi ::: -The `features` attribute is used to analyze the function switches, and the specific functional items are as follows: - -- **loader**: Analysis of Loader time consumption and code compilation changes, enabled by default. -- **plugins**: Analysis of Plugins calls and time consumption, enabled by default. -- **bundle**: Analysis of build artifacts, enabled by default. -- **resolver**: resolver analysis, disabled by default. -- **lite**: lite mode. The difference between lite mode and normal mode is that source code information is no longer cached, only packaged code information is cached, so the code analyzed on the page will also be packaged. The default is normal mode. - -Therefore, **the default configuration enables bundle analysis capabilities and Loader and Plugin build-time analysis**. The Resolver analysis capability is not enabled, and Rspack does not currently support Resolver analysis capabilities. - #### features types - if the `features` is set as an `Array`, it will **open** the features which you define in this array **only**. - if the `features` is set as an `Object`, it will **close** the features which you set the value is `false`. -### reportCodeType +#### RsdoctorWebpackPluginFeatures -- Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }` -- Optional: true -- Default: undefined -- Description +`features` type： - - Select the output analysis data: +import Features from '@en/shared/features.md'; - - undefined is all complete data; + - - noModuleSource: true is the output of data other than module code; Module code is the packaged module code of a file disassembled in the Bundle. +#### RsdoctorRspackPluginFeatures - - noAssetsAndModuleSource: true is the output of data other than module code and Assets product code. +`features` type： -- Example +import FeaturesRspack from '@en/shared/features-rspack.md'; -```js -new WebDoctorWebpackPlugin({ - disableClientServer: false, // It is recommended to disable the server capability in the CI environment, otherwise it will block the pipeline process. You can check the CI environment using `process.env.CI_ACTOR`. - features: ['loader', 'bundle', 'plugins'], - reportCodeType: { noModuleSource: true } // { noAssetsAndModuleSource: true } - }), + + +### mode + +- **Type:** `normal | brief | lite` +- **Optional:** `true` +- **Default:** `normal` + +Choose the Rsdoctor build report mode to use, which includes the following options: + +- normal: Normal mode, which generates a '.rsdoctor' folder in the build output directory. It contains different data files and the report page displays code. The output directory can be configured using [reportDir](#reportdir). +- brief: Brief mode, which generates an HTML report file in the `.rsdoctor` folder of the build output directory. You can open this HTML file in a browser to view the report. Brief mode also has additional configuration options, see [brief](#brief). +- lite: Lite mode, which is a mode based on normal mode that does not display source code and bundles codes. It only displays information about the built codes. + +### reportDir + +- **Type:** string +- **Optional:** `true` +- **Default:** undefined + +The output directory for Rsdoctor reports. By default, it is the build output directory. + +### brief + +- **Type:** [BriefType](#brieftype) +- **Optional:** `true` +- **Default:** undefined + +More configurations for Brief mode are as follows: + +- **reportHtmlName:** Configures the name of the HTML report for Brief mode. The default value is `report-rsdoctor.html`. +- **writeDataJson:** By default, in Brief mode, the analysis data is injected into the HTML file, so no additional build analysis data is generated. If you want to generate additional local data, you need to configure `writeDataJson: true`. + +#### briefType + +```ts +interface BriefConfig { + reportHtmlName?: string | undefined; + writeDataJson: boolean; +} ``` -### disableTOSUpload +### reportCodeType -- Type: boolean +- Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }` - Optional: true -- Default: false +- Default: undefined - Description - Turn tos upload on or off. True is to turn off tos upload, and false is tos upload on. + - Select the output analysis data: + + - default is all complete data; + + - noModuleSource: true is the output of data other than module code; Module code is the packaged module code of a file disassembled in the Bundle. + + - noAssetsAndModuleSource: true is the output of data other than module code and Assets product code. - Example ```js -new WebDoctorWebpackPlugin({ - disableClientServer: false, // It is recommended to disable the server capability in the CI environment, otherwise it will block the pipeline process. You can check the CI environment using `process.env.CI_ACTOR`. - features: ['loader', 'bundle', 'plugins'], - disableTOSUpload: true, - }), +new RsdoctorRspackPlugin({ + reportCodeType: { noModuleSource: true } // { noAssetsAndModuleSource: true } +}), ``` ### supports @@ -215,14 +251,14 @@ Disabling the Parse Bundle capability will only affect the visibility of the Bun diff --git a/packages/document/docs/en/guide/start/_meta.json b/packages/document/docs/en/guide/start/_meta.json index a2689a5b..3bb3c0e0 100644 --- a/packages/document/docs/en/guide/start/_meta.json +++ b/packages/document/docs/en/guide/start/_meta.json @@ -1 +1 @@ -["intro", "quick-start", "features", "cli"] +["intro", "quick-start", "features", "cicd", "cli"] diff --git a/packages/document/docs/en/guide/start/cicd.mdx b/packages/document/docs/en/guide/start/cicd.mdx new file mode 100644 index 00000000..5a0250e0 --- /dev/null +++ b/packages/document/docs/en/guide/start/cicd.mdx @@ -0,0 +1,30 @@ +# CI/CD Tutorial + +In CI/CD, there is often a desire to upload historical reports to the CDN as historical records. Because it's not convenient to achieve instant use in the standard mode, the **Brief** mode is supported. + +## Brief Mode + +In Brief mode, data reports are integrated into a single HTML page, making it easy for users to view historical build data in a summary form within CI/CD and other scenarios. + +### Enabling Brief Mode + +You can enable Brief mode by configuring the `mode.brief` option in the Rsdoctor plugin. After the build, Brief mode will generate a report in the build output directory: `[outputDir]/.rsdoctor/report-rsdoctor.html`. You can view the build analysis summary by opening the HTML file in a browser. + +- In Brief mode, no code data is displayed to prevent the page from crashing due to large data sizes. +- The report output directory and file name can be configured. Refer to: [Options](/config/options/options#brief). +- For more configurations, refer to: [Options](/config/options/options#brief). + +```ts title="rspack.config.js" +const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin'); + +module.exports = { + // ... + plugins: [ + process.env.RSDOCTOR && + new RsdoctorRspackPlugin({ + // other options + mode: 'brief', + }), + ].filter(Boolean), +}; +``` diff --git a/packages/document/docs/en/shared/features-rspack.md b/packages/document/docs/en/shared/features-rspack.md new file mode 100644 index 00000000..7dc7e03d --- /dev/null +++ b/packages/document/docs/en/shared/features-rspack.md @@ -0,0 +1,25 @@ +```ts +interface RsdoctorRspackPluginFeatures { + /** + * turn off it if you need not to analyze the executions of webpack loaders. + * @default true + */ + loader?: boolean; + /** + * turn off it if you need not to analyze the executions of webpack plugins. + * @default true + */ + plugins?: boolean; + /** + * turn off it if you need not to analyze the output bundle. + * @default true + */ + bundle?: boolean; + /** + * turn on it if you just use lite mode. This mode do not have source codes. + * @default false + * @deprecated + */ + lite?: boolean; +} +``` diff --git a/packages/document/docs/en/shared/features.md b/packages/document/docs/en/shared/features.md new file mode 100644 index 00000000..8e2150fb --- /dev/null +++ b/packages/document/docs/en/shared/features.md @@ -0,0 +1,30 @@ +```ts +interface RsdoctorWebpackPluginFeatures { + /** + * turn off it if you need not to analyze the executions of webpack loaders. + * @default true + */ + loader?: boolean; + /** + * turn off it if you need not to analyze the executions of webpack plugins. + * @default true + */ + plugins?: boolean; + /** + * turn off it if you need not to analyze the executions of resolver. + * @default false + */ + resolver?: boolean; + /** + * turn off it if you need not to analyze the output bundle. + * @default true + */ + bundle?: boolean; + /** + * turn on it if you just use lite mode. This mode do not have source codes. + * @default false + * @deprecated + */ + lite?: boolean; +} +``` diff --git a/packages/document/docs/zh/config/options/options-shared.mdx b/packages/document/docs/zh/config/options/options-shared.mdx index 1e259514..64e2e425 100644 --- a/packages/document/docs/zh/config/options/options-shared.mdx +++ b/packages/document/docs/zh/config/options/options-shared.mdx @@ -27,6 +27,16 @@ #### features values +features 属性是用于分析功能开关的，具体的功能项如下： + +- **loader**：Loaders 耗时及代码编译变化分析，默认开启。 +- **plugins**：Plugins 调用以及耗时分析，默认开启。 +- **bundle**：构建产物分析，默认开启。 +- **resolver**：resolver 分析，默认关闭。 +- **lite**: **(废弃，参考：[mode.lite]())** lite 模式。lite 模式和普通模式的区别就是不再缓存源码信息，只缓存打包后的代码信息，这样分析页面上的代码也将是打包后的。默认普通模式。 + +所以，**默认配置是开启了 Bundle 分析能力、 Loader he Plugin 构建时分析**。没有开启 Resolver 分析能力， Rspack 暂不支持 Resolver 分析能力。 + :::tip **如果出现了 out of memory 的报错，可以尝试：** @@ -38,16 +48,6 @@ ::: -features 属性是用于分析功能开关的，具体的功能项如下： - -- **loader**：Loaders 耗时及代码编译变化分析，默认开启。 -- **plugins**：Plugins 调用以及耗时分析，默认开启。 -- **bundle**：构建产物分析，默认开启。 -- **resolver**：resolver 分析，默认关闭。 -- **lite**: lite 模式。lite 模式和普通模式的区别就是不再缓存源码信息，只缓存打包后的代码信息，这样分析页面上的代码也将是打包后的。默认普通模式。 - -所以，**默认配置是开启了 Bundle 分析能力、 Loader he Plugin 构建时分析**。没有开启 Resolver 分析能力， Rspack 暂不支持 Resolver 分析能力。 - #### features types - 如果你将 `features` 设置为**数组**类型，该插件**只会开启**你在 `features` 数组中定义的功能。 diff --git a/packages/document/docs/zh/config/options/options.mdx b/packages/document/docs/zh/config/options/options.mdx index 0fe16b04..81994735 100644 --- a/packages/document/docs/zh/config/options/options.mdx +++ b/packages/document/docs/zh/config/options/options.mdx @@ -95,6 +95,16 @@ new RsdoctorWebpackPlugin({ #### features values +features 属性是用于分析功能开关的，具体的功能项如下： + +- **loader**：Loaders 耗时及代码编译变化分析，默认开启。 +- **plugins**：Plugins 调用以及耗时分析，默认开启。 +- **bundle**：构建产物分析，默认开启。 +- **resolver**：resolver 分析，默认关闭。 +- **lite**: **(废弃，使用 [mode.lite](#mode))** lite 模式。lite 模式和普通模式的区别就是不再展示源码信息，只展示打包后的代码信息，这样分析页面上的代码也将是打包后的。默认普通模式。 + +所以，**默认配置是开启了 Bundle 分析能力、 Loader he Plugin 构建时分析**。没有开启 Resolver 分析能力， Rspack 暂不支持 Resolver 分析能力。 + :::tip **如果出现了 out of memory 的报错，可以尝试：** @@ -106,16 +116,6 @@ new RsdoctorWebpackPlugin({ ::: -features 属性是用于分析功能开关的，具体的功能项如下： - -- **loader**：Loaders 耗时及代码编译变化分析，默认开启。 -- **plugins**：Plugins 调用以及耗时分析，默认开启。 -- **bundle**：构建产物分析，默认开启。 -- **resolver**：resolver 分析，默认关闭。 -- **lite**: lite 模式。lite 模式和普通模式的区别就是不再缓存源码信息，只缓存打包后的代码信息，这样分析页面上的代码也将是打包后的。默认普通模式。 - -所以，**默认配置是开启了 Bundle 分析能力、 Loader he Plugin 构建时分析**。没有开启 Resolver 分析能力， Rspack 暂不支持 Resolver 分析能力。 - #### features types - 如果你将 `features` 设置为**数组**类型，该插件**只会开启**你在 `features` 数组中定义的功能。 @@ -137,6 +137,66 @@ import FeaturesRspack from '@zh/shared/features-rspack.md'; +### mode + +- **Type:** `normal | brief | lite` +- **Optional:** `true` +- **Default:** `normal` + +选择使用的 Rsdoctor 构建报告模式，有以下几种： + +- normal：普通模式，会在构建产物目录生成 '.rsdoctor' 文件夹，里面会有不同的数据文件，报告页面中会有代码展示。输出目录可配置：[reportDir](#reportdir). +- brief: 简报模式，会在构建产物目录的 '.rsdoctor' 文件夹中生成一个 HTML 报告文件，可通过在浏览器中打开这个 HTML 查看报告.brief 模式还有更多配置项，查看：[brief](#brief) +- lite: 轻量模式，这个模式是在普通模式基础下不展示源码和产物代码的模式，只展示打包后的代码信息。 + +### reportDir + +- **Type:** string +- **Optional:** `true` +- **Default:** undefined + +Rsdoctor 报告输出目录，默认是构建产物输出目录。 + +### brief + +- **Type:** [BriefType](#brieftype) +- **Optional:** `true` +- **Default:** undefined + +Brief 模式更多配置，如下： + +- **reportHtmlName:** 配置 Brief 的 HTML 报告的名称，默认 `report-rsdoctor.html`。 +- **writeDataJson:** 默认 Brief 模式下将分析数据注入到 HTML 文件中，所以不会再产生构建分析数据。如果想要而外本地生成数据则需要配置 `writeDataJson: true`。 + +#### briefType + +```ts +interface BriefConfig { + reportHtmlName?: string | undefined; + writeDataJson: boolean; +} +``` + +### reportCodeType + +- Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }` +- Optional: true +- Default: undefined +- Description + + - 选择输出的分析数据： + - 默认是所有完整数据； + - noModuleSource: true 是输出除了 module 代码之外的数据，Module 代码即 Bundle 内一个一个文件的打包模块代码。 + - noAssetsAndModuleSource: true 是输出除了 module 代码和 Assets 产物代码之外的数据。 + +- Example + +```js +new RsdoctorRspackPlugin({ + reportCodeType: { noModuleSource: true } // { noAssetsAndModuleSource: true } +}), +``` + ### supports - **Type:** [Supports Types](#supports-types) @@ -145,7 +205,7 @@ import FeaturesRspack from '@zh/shared/features-rspack.md'; 该选项是配置 Rsdoctor 是否开启某些细节特性分析能力支持的，例如：是否开启对 BannerPlugin 的兼容能力。 -#### Supports Types +#### supportsTypes ```ts type ISupport = { @@ -189,14 +249,14 @@ chain.plugin('Rsdoctor').use(RsdoctorRspackPlugin, [ diff --git a/packages/document/docs/zh/guide/start/_meta.json b/packages/document/docs/zh/guide/start/_meta.json index a2689a5b..3bb3c0e0 100644 --- a/packages/document/docs/zh/guide/start/_meta.json +++ b/packages/document/docs/zh/guide/start/_meta.json @@ -1 +1 @@ -["intro", "quick-start", "features", "cli"] +["intro", "quick-start", "features", "cicd", "cli"] diff --git a/packages/document/docs/zh/guide/start/cicd.mdx b/packages/document/docs/zh/guide/start/cicd.mdx new file mode 100644 index 00000000..22a4b095 --- /dev/null +++ b/packages/document/docs/zh/guide/start/cicd.mdx @@ -0,0 +1,32 @@ +# CI/CD 使用教程 + +CI/CD 中，往往想要上报历史报告到 CDN 作为历史记录，因为普通模式下无法便捷的做到即开即用，所以支持了 **Brief** 模式。 + +## Brief 模式 + +Brief 模式中，会将数据报告整合到一个 HTML 页面中，方便用户在 CI/CD 及其他方试下使用简报来查看历史构建数据。 + +### 开启 Brief 模式 + +通过配置 Rsdoctor 插件的 `mode.brief` 选项，即可开启 Brief 模式。Brief 模式会在构建后生成一份报告到构建产物目录中： `[outputDir]/.rsdoctor/report-rsdoctor.html`，通过浏览器打开 HTML 文件， +即可看到构建分析简报。 + +- Brief 模式下是不展示任何的代码数据的，为了防止数据过大导致页面崩溃。 +- 报告输出的目录和文件名可配置，可参考：[Options](/config/options/options#brief)。 +- 更多配置可参考：[Options](/config/options/options#brief)。 + +```ts title="rspack.config.js" +const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin'); + +module.exports = { + // ... + plugins: [ + // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时 + process.env.RSDOCTOR && + new RsdoctorRspackPlugin({ + // 其他插件选项 + mode: 'brief', + }), + ].filter(Boolean), +}; +``` diff --git a/packages/document/docs/zh/shared/features-rspack.md b/packages/document/docs/zh/shared/features-rspack.md index 12b5769c..7dc7e03d 100644 --- a/packages/document/docs/zh/shared/features-rspack.md +++ b/packages/document/docs/zh/shared/features-rspack.md @@ -18,6 +18,7 @@ interface RsdoctorRspackPluginFeatures { /** * turn on it if you just use lite mode. This mode do not have source codes. * @default false + * @deprecated */ lite?: boolean; } diff --git a/packages/document/docs/zh/shared/features.md b/packages/document/docs/zh/shared/features.md index 1cbfab93..8e2150fb 100644 --- a/packages/document/docs/zh/shared/features.md +++ b/packages/document/docs/zh/shared/features.md @@ -23,6 +23,7 @@ interface RsdoctorWebpackPluginFeatures { /** * turn on it if you just use lite mode. This mode do not have source codes. * @default false + * @deprecated */ lite?: boolean; }