@rsdoctor/docs 1.2.4-beta.5 → 1.3.0-beta.0

package/docs/en/config/options/output.mdx

@@ -32,6 +32,9 @@ Mode does not have a lite configuration option. The lite mode will be deprecated
 Brief mode is used to generate lightweight analysis reports, supporting both HTML and JSON output formats.
 
 - **`type`**: Output type, supports `'html'` and `'json'` arrays, allowing multiple formats to be selected simultaneously
+  - If configured with `['html', 'json']`, it will generate both an HTML file and a JSON file.
+  - If configured with `['json']`, it will generate a JSON file named `rsdoctor-data.json`.
+  - If configured with `['html']`, it will generate an HTML file. The filename can be configured via `htmlOptions.reportHtmlName`.
 - **`htmlOptions`**: HTML output related configuration
   - **`reportHtmlName`**: HTML report filename, defaults to `report-rsdoctor.html`
 - **`jsonOptions`**: JSON output related configuration
@@ -40,6 +43,10 @@ Brief mode is used to generate lightweight analysis reports, supporting both HTM
     - **`chunkGraph`**: Whether to include Chunk graph data, defaults to `true`
     - **`rules`**: Whether to include rules data, defaults to `true`
 
+**Notes:**
+
+- In Brief mode, the **`reportCodeType`** configuration item is invalid because only **`'noCode'`** is supported.
+
 **Configuration Example:**
 
 ```js
@@ -57,11 +64,58 @@ new RsdoctorRspackPlugin({
 });
 ```
 
-**Notes:**
+#### HTML vs JSON Output Format Differences
 
-- In Brief mode, the **`reportCodeType`** configuration item is invalid because only **`'noCode'`** is supported.
-- In Brief mode, when **type is 'html'**, analysis data is directly injected into the HTML file, making it convenient for single-file sharing.
-- In Brief mode, when **type is 'json'**, structured data files are generated, making it convenient for programmatic processing.
+| Feature               | HTML Format                                                                                    | JSON Format                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **File Structure**    | Single file containing complete analysis report page                                           | Pure data file requiring client support                                                  |
+| **Usage**             | Can be opened directly in browser for viewing                                                  | Needs to be uploaded to Playground or parsed with client                                 |
+| **Data Completeness** | Contains all analysis data and visualization interface                                         | Contains only raw analysis data                                                          |
+| **File Size**         | Larger (includes styles and scripts)                                                           | Smaller (data only)                                                                      |
+| **Use Cases**         | • Offline report viewing<br/>• Direct sharing with others<br/>• No secondary processing needed | • Upload to Playground<br/>• Programmatic processing<br/>• Data analysis and integration |
+| **Dependencies**      | Self-contained, no external dependencies                                                       | Requires Rsdoctor client support                                                         |
+
+> For viewing analysis reports in Playground, see [Playground](/guide/start/playground).
+
+**Configuration Example Comparison:**
+
+```js
+// Generate HTML report only (suitable for offline viewing)
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['html'],
+      htmlOptions: {
+        reportHtmlName: 'build-report.html',
+      },
+    },
+  },
+});
+
+// Generate JSON data only (suitable for uploading to Playground)
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['json'],
+    },
+  },
+});
+
+// Generate both formats (suitable for different use cases)
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['html', 'json'],
+      htmlOptions: {
+        reportHtmlName: 'build-report.html',
+      },
+    },
+  },
+});
+```
 
 ### mode: 'normal'
 

package/docs/en/guide/start/_meta.json

@@ -1 +1 @@
-["intro", "quick-start", "features", "cicd", "cli", "mcp"]
+["intro", "quick-start", "features", "cicd", "cli", "mcp", "playground"]

package/docs/en/guide/start/playground.mdx

@@ -0,0 +1,93 @@
+# Playground
+
+## Introduction
+
+Playground is an online analysis tool provided by Rsdoctor that supports uploading build analysis data and viewing analysis reports online. No local installation of Rsdoctor is required to quickly experience build analysis features, with support for complete report display.
+
+## Supported Data Formats
+
+### 1. Rsdoctor Analysis Data
+
+Supports uploading JSON format analysis data generated by Rsdoctor to re-display complete analysis reports.
+
+#### Configuration Requirements
+
+Need to configure `output.mode: 'brief'` and set `output.options.type` to `['json']` or `['html', 'json']`:
+
+```js title="rspack.config.mjs/webpack.config.mjs"
+export default {
+  plugins: [
+    new RsdoctorRspackPlugin({
+      output: {
+        mode: 'brief',
+        options: {
+          type: ['json'], // or ['html', 'json']
+        },
+      },
+    }),
+  ],
+};
+```
+
+- Optional configuration
+  - `optimizationBailout`: Optional configuration. If not enabled, it will only affect the display of [Bailout Reason](/guide/usage/module-analysis#bailout-reason) for each Module.
+
+#### Usage Steps
+
+1. After building the project, find the `rsdoctor-data.json` file in the output directory
+2. Visit the [Playground page](https://rsdoctor.rs/preview/#/resources/uploader)
+3. Upload the `rsdoctor-data.json` file
+4. View the complete analysis report
+
+:::tip
+Difference between Brief mode and Normal mode:
+
+- **Brief mode**: Generates single files (HTML or JSON), convenient for sharing and uploading
+- **Normal mode**: Generates folders containing multiple files, suitable for local viewing
+  :::
+
+### 2. Webpack/Rspack Stats Data
+
+Supports uploading `stats.json` files from Webpack or Rspack to automatically generate analysis reports.
+
+#### Configuration Requirements
+
+Need to configure detailed stats options to get complete build information:
+
+**Method 1: Use verbose mode**
+
+`verbose` mode outputs all build information (except debug info) and automatically includes all data required by Rsdoctor. For custom configuration, refer to the example below. See [Rspack stats](https://rspack.dev/config/stats) for detailed information.
+
+```js title="rspack.config.mjs/webpack.config.mjs"
+export default {
+  stats: 'verbose',
+};
+```
+
+**Method 2: Stats configuration**
+
+Configure according to the Stats options below.
+
+```js title="rspack.config.mjs/webpack.config.mjs"
+export default {
+  stats: {
+    all: false,
+    chunks: true,
+    assets: true,
+    modules: true,
+    chunkModules: true,
+    hash: true,
+    ids: true,
+    version: true,
+    optimizationBailout: true, // Optional configuration
+  },
+};
+```
+
+#### Usage Steps
+
+1. Set the above stats options in the build configuration
+2. Build the project to generate the `stats.json` file
+3. Visit the [Playground page](https://rsdoctor.rs/preview/#/resources/uploader)
+4. Upload the `stats.json` file
+5. View the automatically generated analysis report

package/docs/zh/config/options/output.mdx

@@ -32,6 +32,9 @@ mode 是没有 lite 配置项的，lite 模式即将废弃，参考 [lite 模式
 Brief 模式用于生成轻量级的分析报告，支持 HTML 和 JSON 两种输出格式。
 
 - **`type`**：输出类型，支持 `'html'` 和 `'json'` 数组，可同时选择多种格式
+  - 如果配置了 `['html', 'json']`，则会生成一个 html 文件，同时生成一个 json 文件。
+  - 如果配置了 `['json']`，则会生成一个 json 文件。文件名为 `rsdoctor-data.json`。
+  - 如果配置了 `['html']`，则会生成一个 html 文件。文件名可通过 `htmlOptions.reportHtmlName` 配置。
 - **`htmlOptions`**：HTML 输出相关配置
   - **`reportHtmlName`**：HTML 报告文件名，默认为 `report-rsdoctor.html`
 - **`jsonOptions`**：JSON 输出相关配置
@@ -40,6 +43,10 @@ Brief 模式用于生成轻量级的分析报告，支持 HTML 和 JSON 两种
     - **`chunkGraph`**：是否包含 Chunk 图数据，默认为 `true`
     - **`rules`**：是否包含规则数据，默认为 `true`
 
+**注意事项：**
+
+- Brief 模式下，**`reportCodeType`** 配置项无效，因为只支持 **`'noCode'`**。
+
 **配置示例：**
 
 ```js
@@ -57,11 +64,58 @@ new RsdoctorRspackPlugin({
 });
 ```
 
-**注意事项：**
+#### HTML 与 JSON 输出格式的区别
 
-- Brief 模式下，**`reportCodeType`** 配置项无效，因为只支持 **`'noCode'`**。
-- Brief 模式下，**type 为 'html' 时**，分析数据会直接注入到 HTML 文件中，便于单文件分享。
-- Brief 模式下，**type 为 'json' 时**，会生成结构化的数据文件，便于程序化处理。
+| 特性           | HTML 格式                                                | JSON 格式                                                 |
+| -------------- | -------------------------------------------------------- | --------------------------------------------------------- |
+| **文件结构**   | 单文件，包含完整的分析报告页面                           | 纯数据文件，需要配合客户端使用                            |
+| **使用方式**   | 可直接在浏览器中打开查看                                 | 需要上传到 Playground 或配合客户端解析                    |
+| **数据完整性** | 包含所有分析数据和可视化界面                             | 仅包含原始分析数据                                        |
+| **文件大小**   | 较大（包含样式和脚本）                                   | 较小（仅数据）                                            |
+| **适用场景**   | • 离线查看报告<br/>• 直接分享给他人<br/>• 不需要二次处理 | • 上传到 Playground<br/>• 程序化处理<br/>• 数据分析和集成 |
+| **依赖关系**   | 无外部依赖，自包含                                       | 需要 Rsdoctor 客户端支持                                  |
+
+> Playground 查看分析报告，详见 [Playground](/guide/start/playground)。
+
+**配置示例对比：**
+
+```js
+// 仅生成 HTML 报告（适合离线查看）
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['html'],
+      htmlOptions: {
+        reportHtmlName: 'build-report.html',
+      },
+    },
+  },
+});
+
+// 仅生成 JSON 数据（适合上传到 Playground）
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['json'],
+    },
+  },
+});
+
+// 同时生成两种格式（适合不同使用场景）
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+    options: {
+      type: ['html', 'json'],
+      htmlOptions: {
+        reportHtmlName: 'build-report.html',
+      },
+    },
+  },
+});
+```
 
 ### mode: 'normal'
 

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

@@ -1 +1 @@
-["intro", "quick-start", "features", "cicd", "cli", "mcp"]
+["intro", "quick-start", "features", "cicd", "cli", "mcp", "playground"]

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

@@ -0,0 +1,97 @@
+# Playground
+
+## 介绍
+
+Playground 是 Rsdoctor 提供的在线分析工具，支持上传构建分析数据并在线查看分析报告。无需本地安装 Rsdoctor，即可快速体验构建分析功能，支持完整报告展示。
+
+## 支持的数据格式
+
+### 1. Rsdoctor 分析数据
+
+支持上传 Rsdoctor 生成的 JSON 格式分析数据，重新展示完整的分析报告。
+
+#### 配置要求
+
+需要配置 `output.mode: 'brief'` 并设置 `output.options.type` 为 `['json']` 或 `['html', 'json']`：
+
+> 具体配置可查看 [output 配置](/config/options/output)。
+
+```js title="rspack.config.mjs 或 webpack.config.mjs"
+export default {
+  plugins: [
+    new RsdoctorRspackPlugin({
+      output: {
+        mode: 'brief',
+        options: {
+          type: ['json'], // 或 ['html', 'json']
+        },
+      },
+    }),
+  ],
+};
+```
+
+#### 使用步骤
+
+1. 构建项目后，在输出目录中找到 `rsdoctor-data.json` 文件
+2. 访问 [Playground 页面](https://rsdoctor.rs/preview/#/resources/uploader)
+3. 上传 `rsdoctor-data.json` 文件
+4. 查看完整的分析报告
+
+:::tip
+
+Brief 模式与 Normal 模式的区别：
+
+- **Brief 模式**：生成单一文件（HTML 或 JSON），便于分享和上传
+- **Normal 模式**：生成包含多个文件的文件夹，适合本地查看
+
+:::
+
+### 2. Rspack Stats 数据
+
+支持上传 Rspack 或 webpack 的 `stats.json` 文件，自动生成分析报告。
+
+#### 配置要求
+
+需要配置详细的 stats 选项以获取完整的构建信息：
+
+**方式一：使用 verbose 模式**
+
+`verbose` 模式会输出所有构建信息（除调试信息外），自动包含 Rsdoctor 所需的数据。如想精简 stats 的输出数据，可参考下方示例。详细说明请查看 [Rspack stats](https://rspack.dev/config/stats)。
+
+```js title="rspack.config.mjs 或 webpack.config.mjs"
+export default {
+  stats: 'verbose',
+};
+```
+
+**方式二：stats 配置**
+
+需要按照下面的 Stats options 进行配置。
+
+```js title="rspack.config.mjs 或 webpack.config.mjs"
+export default {
+  stats: {
+    all: false,
+    chunks: true,
+    assets: true,
+    modules: true,
+    chunkModules: true,
+    hash: true,
+    ids: true,
+    version: true,
+    optimizationBailout: true, // 可选配置
+  },
+};
+```
+
+- 可选配置
+  - `optimizationBailout`：可选配置，如果不开启该配置，只会影响每个 Module 的 [Bailout Reason](/guide/usage/module-analysis#bailout-reason) 的展示。
+
+#### 使用步骤
+
+1. 在构建配置中设置上述 stats 选项
+2. 构建项目，生成 `stats.json` 文件
+3. 访问 [Playground 页面](https://rsdoctor.rs/preview/#/resources/uploader)
+4. 上传 `stats.json` 文件
+5. 查看自动生成的分析报告

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdoctor/docs",
-  "version": "1.2.4-beta.5",
+  "version": "1.3.0-beta.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/rsdoctor",
@@ -33,7 +33,7 @@
     "rspress-plugin-sitemap": "^1.1.4",
     "typescript": "^5.9.2",
     "@rsbuild/plugin-sass": "^1.4.0",
-    "@rsdoctor/types": "1.2.4-beta.5"
+    "@rsdoctor/types": "1.3.0-beta.0"
   },
   "dependencies": {
     "@rstack-dev/doc-ui": "1.11.0",