diff --git a/website/docs/en/config/performance/bundle-analyze.mdx b/website/docs/en/config/performance/bundle-analyze.mdx index f863318b91..9fc73e576b 100644 --- a/website/docs/en/config/performance/bundle-analyze.mdx +++ b/website/docs/en/config/performance/bundle-analyze.mdx @@ -15,17 +15,38 @@ const defaultConfig = { }; ``` -### Enable Bundle Analyze +## Enable Bundle Analyze -You have two ways to enable `webpack-bundle-analyzer` to analyze the size of the output files: +You have two ways to enable `webpack-bundle-analyzer` to analyze the size of the output files. -- Add the environment variable `BUNDLE_ANALYZE=true`, for example: +### Via Environment Variable -```bash -BUNDLE_ANALYZE=true pnpm build +Add the environment variable `BUNDLE_ANALYZE=true`, for example: + +```json title="package.json" +{ + "scripts": { + "build:analyze": "BUNDLE_ANALYZE=true rsbuild build" + } +} +``` + +Since the Windows system does not support the above usage, you can also use [cross-env](https://www.npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems: + +```json title="package.json" +{ + "scripts": { + "build:analyze": "cross-env BUNDLE_ANALYZE=true rsbuild build" + }, + "devDependencies": { + "cross-env": "^7.0.0" + } +} ``` -- Configure `performance.bundleAnalyze` to enable it permanently: +### Via Configuration + +Configure `performance.bundleAnalyze` to enable it permanently: ```js export default { @@ -35,6 +56,8 @@ export default { }; ``` +### Analysis Result + After enabling it, Rsbuild will generate an HTML file that analyzes the size of the output files, and print the following log in the Terminal: ```bash @@ -45,7 +68,7 @@ You can manually open the file in the browser and view the detail of the bundle ![](https://assets.rspack.dev/rsbuild/assets/bundle-analyzer-example.png) -### Override Default Configuration +## Override Default Configuration You can override the default configuration through `performance.bundleAnalyze`, such as enabling the server mode: @@ -62,7 +85,7 @@ export default { }; ``` -### Size Types +## Size Types In the `webpack-bundle-analyzer` panel, you can control size types in the upper left corner (default is `Parsed`): @@ -70,7 +93,7 @@ In the `webpack-bundle-analyzer` panel, you can control size types in the upper - `Parsed`: The size of the file on the disk, which reflects the size of the code after minification. - `Gzipped`: The file size requested in the browser reflects the size of the code after minification and gzip. -### Generate stats.json +## Generate stats.json By setting `generateStatsFile` to true, stats JSON file will be generated in bundle output directory. @@ -84,7 +107,7 @@ export default { }; ``` -### Notes +## Notes 1. Enabling the server mode will cause the `build` process to not exit normally. 2. Enabling `bundleAnalyzer` will reduce build speed. Therefore, this configuration should not be enabled during daily development, and it is recommended to enable it on demand through the `BUNDLE_ANALYZE` environment variable. diff --git a/website/docs/en/guide/debug/rsdoctor.mdx b/website/docs/en/guide/debug/rsdoctor.mdx index 75dc604ab8..bdef52d382 100644 --- a/website/docs/en/guide/debug/rsdoctor.mdx +++ b/website/docs/en/guide/debug/rsdoctor.mdx @@ -16,12 +16,27 @@ import { PackageManagerTabs } from '@theme'; 2. Add `RSDOCTOR=true` env variable before the CLI command: -```bash -# dev -RSDOCTOR=true rsbuild dev +```json title="package.json" +{ + "scripts": { + "dev:rsdoctor": "RSDOCTOR=true rsbuild dev", + "build:rsdoctor": "RSDOCTOR=true rsbuild build" + } +} +``` + +Since the Windows system does not support the above usage, you can also use [cross-env](https://www.npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems: -# build -RSDOCTOR=true rsbuild build +```json title="package.json" +{ + "scripts": { + "dev:rsdoctor": "cross-env RSDOCTOR=true rsbuild dev", + "build:rsdoctor": "cross-env RSDOCTOR=true rsbuild build" + }, + "devDependencies": { + "cross-env": "^7.0.0" + } +} ``` After running the above commands, Rsbuild will automatically register the Rsdoctor plugin, and after the build is completed, it will open the build analysis page. For complete features, please refer to [Rsdoctor document](https://rsdoctor.dev/). diff --git a/website/docs/en/plugins/list/plugin-react.mdx b/website/docs/en/plugins/list/plugin-react.mdx index 7488049f1b..a7ca33eca2 100644 --- a/website/docs/en/plugins/list/plugin-react.mdx +++ b/website/docs/en/plugins/list/plugin-react.mdx @@ -163,8 +163,25 @@ pluginReact({ Set `REACT_PROFILER=true` when running build script: -```bash -REACT_PROFILER=true npx rsbuild build +```json title="package.json" +{ + "scripts": { + "build:profiler": "REACT_PROFILER=true rsbuild build" + } +} +``` + +Since the Windows system does not support the above usage, you can also use [cross-env](https://www.npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems: + +```json title="package.json" +{ + "scripts": { + "build:profiler": "cross-env REACT_PROFILER=true rsbuild build" + }, + "devDependencies": { + "cross-env": "^7.0.0" + } +} ``` > See the [React docs](https://legacy.reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-devtools-profiler) for details about profiling using the React DevTools. diff --git a/website/docs/zh/config/performance/bundle-analyze.mdx b/website/docs/zh/config/performance/bundle-analyze.mdx index 571c4a814e..0b70303761 100644 --- a/website/docs/zh/config/performance/bundle-analyze.mdx +++ b/website/docs/zh/config/performance/bundle-analyze.mdx @@ -15,17 +15,38 @@ const defaultConfig = { }; ``` -### 启用 Bundle Analyze +## 启用 Bundle Analyze -你有两种方式开启 `webpack-bundle-analyzer` 来分析构建产物的体积: +你有两种方式开启 `webpack-bundle-analyzer` 来分析构建产物的体积。 -- 添加环境变量 `BUNDLE_ANALYZE=true`,比如: +### 通过环境变量 -```bash -BUNDLE_ANALYZE=true pnpm build +添加环境变量 `BUNDLE_ANALYZE=true`,比如: + +```json title="package.json" +{ + "scripts": { + "build:analyze": "BUNDLE_ANALYZE=true rsbuild build" + } +} +``` + +由于 Windows 系统不支持上述用法,你也可以使用 [cross-env](https://www.npmjs.com/package/cross-env) 来设置环境变量,这可以确保在不同的操作系统中都能正常使用: + +```json title="package.json" +{ + "scripts": { + "build:analyze": "cross-env BUNDLE_ANALYZE=true rsbuild build" + }, + "devDependencies": { + "cross-env": "^7.0.0" + } +} ``` -- 配置 `performance.bundleAnalyze` 来固定开启: +### 通过配置项 + +配置 `performance.bundleAnalyze` 来固定开启: ```js export default { @@ -35,6 +56,8 @@ export default { }; ``` +### 分析结果 + 在启用后,Rsbuild 会生成一个分析构建产物体积的 HTML 文件,并在 Terminal 中打印以下日志: ```bash @@ -45,7 +68,7 @@ Webpack Bundle Analyzer saved report to /Project/my-project/dist/report-web.html ![](https://assets.rspack.dev/rsbuild/assets/bundle-analyzer-example.png) -### 覆盖默认配置 +## 覆盖默认配置 你可以通过 `performance.bundleAnalyze` 来覆盖默认配置,比如开启 `server` 模式: @@ -62,7 +85,7 @@ export default { }; ``` -### Size 类型 +## Size 类型 在 `webpack-bundle-analyzer` 的面板中,你可以在左上角控制 Size 类型(默认为 `Parsed`): @@ -70,7 +93,7 @@ export default { - `Parsed`:磁盘上的文件体积,它反映了代码在压缩之后的体积。 - `Gzipped`:浏览器里请求的文件体积,它反映了代码在压缩和 gzip 后的体积。 -### 生成 stats.json +## 生成 stats.json `generateStatsFile` 设置为 true 时,将会生成 stats JSON 文件。 @@ -84,7 +107,7 @@ export default { }; ``` -### 注意事项 +## 注意事项 1. 开启 Server 模式会导致 `build` 进程不能正常退出。 2. 开启 bundleAnalyzer 会降低构建性能。因此,在日常开发过程中不应该开启此配置项,建议通过 `BUNDLE_ANALYZE` 环境变量来按需开启。 diff --git a/website/docs/zh/guide/debug/rsdoctor.mdx b/website/docs/zh/guide/debug/rsdoctor.mdx index b10817dc8a..f64009d403 100644 --- a/website/docs/zh/guide/debug/rsdoctor.mdx +++ b/website/docs/zh/guide/debug/rsdoctor.mdx @@ -16,12 +16,27 @@ import { PackageManagerTabs } from '@theme'; 2. 在 CLI 命令前添加 `RSDOCTOR=true` 环境变量: -```bash -# dev -RSDOCTOR=true rsbuild dev +```json title="package.json" +{ + "scripts": { + "dev:rsdoctor": "RSDOCTOR=true rsbuild dev", + "build:rsdoctor": "RSDOCTOR=true rsbuild build" + } +} +``` + +由于 Windows 系统不支持上述用法,你也可以使用 [cross-env](https://www.npmjs.com/package/cross-env) 来设置环境变量,这可以确保在不同的操作系统中都能正常使用: -# build -RSDOCTOR=true rsbuild build +```json title="package.json" +{ + "scripts": { + "dev:rsdoctor": "cross-env RSDOCTOR=true rsbuild dev", + "build:rsdoctor": "cross-env RSDOCTOR=true rsbuild build" + }, + "devDependencies": { + "cross-env": "^7.0.0" + } +} ``` 在项目内执行上述命令后,Rsbuild 会自动注册 Rsdoctor 的插件,并在构建完成后打开本次构建的分析页面,请参考 [Rsdoctor 文档](https://rsdoctor.dev/) 来了解完整功能。 diff --git a/website/docs/zh/plugins/list/plugin-react.mdx b/website/docs/zh/plugins/list/plugin-react.mdx index 69553790b9..d57dec4edd 100644 --- a/website/docs/zh/plugins/list/plugin-react.mdx +++ b/website/docs/zh/plugins/list/plugin-react.mdx @@ -165,8 +165,25 @@ pluginReact({ 执行构建脚本时,设置 `REACT_PROFILER=true` 即可: -```bash -REACT_PROFILER=true npx rsbuild build +```json title="package.json" +{ + "scripts": { + "build:profiler": "REACT_PROFILER=true rsbuild build" + } +} +``` + +由于 Windows 系统不支持上述用法,你也可以使用 [cross-env](https://www.npmjs.com/package/cross-env) 来设置环境变量,这可以确保在不同的操作系统中都能正常使用: + +```json title="package.json" +{ + "scripts": { + "build:profiler": "cross-env REACT_PROFILER=true rsbuild build" + }, + "devDependencies": { + "cross-env": "^7.0.0" + } +} ``` > 关于使用 React DevTools 进行性能分析的详细信息,请参见 [React 文档](https://legacy.reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-devtools-profiler)。