@rsdoctor/docs 0.0.0-next-20240620044732

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

@@ -0,0 +1,195 @@
+# Options
+
+## RsdoctorRspackPlugin
+
+`RsdoctorRspackPlugin` class are exported by `@rsdoctor/rspack-plugin`, and the option is [RsdoctorRspackPluginOptions](#options-1).
+
+<Tabs>
+
+<Tab label="cjs">
+
+```js
+const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');
+
+new RsdoctorRspackPlugin({
+  /** RsdoctorRspackPluginOptions */
+});
+```
+
+</Tab>
+
+<Tab label="esm">
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+new RsdoctorRspackPlugin({
+  /** RsdoctorRspackPluginOptions */
+});
+```
+
+</Tab>
+
+</Tabs>
+
+## RsdoctorWebpackPlugin
+
+`RsdoctorWebpackPlugin` class are exported by `@rsdoctor/webpack-plugin`, and the option is [RsdoctorWebpackPluginOptions](#options-1).
+
+import { Tab, Tabs } from '@theme';
+
+<Tabs>
+
+<Tab label="cjs">
+
+```js
+const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+
+new RsdoctorWebpackPlugin({
+  /** RsdoctorWebpackPluginOptions */
+});
+```
+
+</Tab>
+
+<Tab label="esm">
+
+```ts
+import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+
+new RsdoctorWebpackPlugin({
+  /** RsdoctorWebpackPluginOptions */
+});
+```
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+**Type:** `Object`
+
+This is the options for the [RsdoctorWebpackPlugin](#rsdoctorwebpackplugin) and [RsdoctorRspackPlugin](#rsdoctorrspackplugin). It contains these properties:
+
+- [disableClientServer](#disableclientserver)
+- [features](#features)
+
+### disableClientServer
+
+- **Type:** `boolean`
+- **Optional:** `true`
+- **Default:** `false`
+
+Whether to automatically open the Rsdoctor report page. If you do not need to view the analysis report provided by Rsdoctor in the browser, you can enable this configuration item.
+
+### features
+
+- **Type:** [RsdoctorWebpackPluginFeatures](#rsdoctorwebpackpluginfeatures) | [Array\<keyof RsdoctorWebpackPluginFeatures\>](#rsdoctorwebpackpluginfeatures) | [RsdoctorRspackPluginFeatures](#rsdoctorrspackpluginfeatures) | [Array\<keyof RsdoctorRspackPluginFeatures\>](#rsdoctorrspackpluginfeatures)
+- **Optional:** `true`
+- **Default:** `['loader', 'plugins', 'bundle']`
+
+#### features values
+
+:::tip
+
+**If an "out of memory" error occurs, you can try the following:**
+
+1. Open the **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.
+- Difference: The difference between the "lite" mode and the normal mode is that source code information is no longer cached, only packaged code information is cached. Thus, the code analyzed on the page will also only be packaged.
+
+:::
+
+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
+
+- Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }`
+- Optional: true
+- Default: undefined
+- Description
+
+  - Select the output analysis data:
+
+    - 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.
+
+    - 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'],
+        reportCodeType: { noModuleSource: true } // { noAssetsAndModuleSource: true }
+      }),
+```
+
+### disableTOSUpload
+
+- Type: boolean
+- Optional: true
+- Default: false
+- Description
+
+  Turn tos upload on or off. True is to turn off tos upload, and false is tos upload on.
+
+- 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,
+      }),
+```
+
+### supports
+
+- **Type:** [Supports Types](#supports-types)
+- **Optional:** `true`
+- **Default:** `undefined`
+
+This option is used to configure whether Rsdoctor enables support for certain detailed feature analysis capabilities, such as whether to enable compatibility with BannerPlugin.
+
+#### Supports Types
+
+```ts
+type ISupport = {
+  banner: boolean;
+};
+```
+
+#### banner
+
+:::danger
+When enabling the analysis of BannerPlugin, Rsdoctor should not be used in production versions.
+:::
+
+If `supports.banner` is enabled, Rsdoctor will enable compatibility logic for BannerPlugin. For more details, please refer to: [Supports BannerPlugin](../../guide/usage/bundle-size#supports-bannerplugin)
+
+### port
+
+- **Type:** `number`
+- **Optional:** `true`
+- **Default:** `random(3000, 8999)`
+
+Configure the port for the Rsdoctor server.

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

@@ -0,0 +1,10 @@
+# Terminology
+
+## Common Terminology
+
+### manifest.json
+
+When your project integrates with plugins provided by **Rsdoctor** (such as `@rsdoctor/webpack-plugin`, etc.), Rsdoctor will write **build-related data information** into a local JSON file:
+
+- The **filename is `manifest.json`**
+- The output path of this file is `output directory of the project/.rsdoctor/manifest.json`

package/docs/en/guide/_meta.json

@@ -0,0 +1,17 @@
+[
+  {
+    "type": "dir",
+    "name": "start",
+    "label": "Getting Started"
+  },
+  {
+    "type": "dir",
+    "name": "usage",
+    "label": "Usage"
+  },
+  {
+    "type": "dir",
+    "name": "more",
+    "label": "More"
+  }
+]

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

@@ -0,0 +1 @@
+["faq", "rules"]

package/docs/en/guide/more/faq.mdx

@@ -0,0 +1,104 @@
+# FAQ
+
+## How to use only a specific feature of Rsdoctor?
+
+When we **only need** the [bundle size analysis](../usage/bundle-size) feature of Rsdoctor, we can configure the corresponding [Features](/config/options/options) 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**.
+
+## Next.js
+
+### Issue with Next.js project report page
+
+Initialize the RsdoctorWebpackPlugin plugin in the [Webpack Config](https://nextjs.org/docs/app/api-reference/next-config-js/webpack) of `next.config.js`.
+
+However, in Next.js, when Rsdoctor is enabled and the **build command** is executed, the report server started by Rsdoctor will be disconnected. Therefore, if you need to reopen the report, you can use **[@rsdoctor/cli](../start/cli.mdx)** without performing the build operation.
+
+For example, if the build artifact of Rsdoctor is located at the path `.next/.rsdoctor/manifest.json`, you can open the report page by executing the following command:
+
+```bash
+npx @rsdoctor/cli analyze --profile .next/.rsdoctor/manifest.json
+
+```
+
+### Loader analysis with rule override is not supported in Next.js
+
+- Rsdoctor Loader logic: Since Rsdoctor modifies the Loader Rules, Rsdoctor wraps the Module in a Proxy to support Loader logic with rule override.
+
+- Next.js specific logic: In Next.js, the LoaderContext adds the currentTraceSpan property, which is obtained from the value retrieved using the Module as the key. However, since Rsdoctor wraps the Module in a Proxy (referred to as ProxyModule), retrieving the value using ProxyModule as the key will result in no value being obtained.
+
+Based on the above reason, Rsdoctor does not wrap the Module in a Proxy in Next.js projects, which means it does not support Loader analysis with rule override. If you encounter Loader errors, you need to configure the **[features](../../config/options/options#features)** parameter to disable **Loader** analysis. You can use the following configuration:
+
+```js title="next.config.js"
+const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+
+module.exports = {
+  // ...
+  webpack: (config, { isServer }) => {
+    config.plugins.push(
+      new RsdoctorWebpackPlugin({
+        // 插件选项
+        features: ['bundle', 'plugins'],
+      }),
+    );
+    return config;
+  },
+};
+```
+
+- **Options:** The plugin provides some configurations, please refer to [Options](../../config/options/options).

package/docs/en/guide/more/rules.mdx

@@ -0,0 +1,5 @@
+# Rule Index
+
+import RuleIndex from '@src/components/RuleIndex';
+
+<RuleIndex />

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

@@ -0,0 +1 @@
+["intro", "quick-start", "features", "cli"]

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

@@ -0,0 +1,94 @@
+# CLI Tutorial
+
+We provide `@rsdoctor/cli` for you to use Rsdoctor's features locally through the CLI program.
+
+:::tip
+`@rsdoctor/webpack-plugin`, `@rsdoctor/rspack-plugin`, and `@rsdoctor/cli` should have the same major and minor versions.
+:::
+
+## Install @rsdoctor/cli
+
+:::tip
+
+- @rsdoctor/cli & @rsdoctor/webpack-plugin & @rsdoctor/rspack-plugin >= 0.1.3.
+- You can also use the non-installation method by using the `npx @rsdoctor/cli <command> [options]` command.
+
+:::
+
+import { PackageManagerTabs } from '@theme';
+
+import { Tab, Tabs } from 'rspress/theme';
+
+<PackageManagerTabs command="add @rsdoctor/cli -D" />
+
+## Command Usage
+
+```linux
+
+rsdoctor <command> [options]
+
+```
+
+`@rsdoctor/cli` currently provides the following commands for different functionalities:
+
+### analyze Command
+
+The `analyze` command is mainly used to load the [manifest.json](../../config/options/term.mdx) file locally and start Rsdoctor's analysis report page without the need to rebuild.
+
+```linux
+rsdoctor analyze --profile <manifestFile>
+```
+
+**Parameter Definition**
+
+- `manifestFile` is the path to the [manifest.json](../../config/options/term.mdx) file (supports local path)
+
+**Usage Example**
+
+```bash
+rsdoctor analyze --profile "./dist/.rsdoctor/manifest.json"
+```
+
+## Node API
+
+We provide a Node.js API in `@rsdoctor/cli` that allows you to make calls during runtime in Node.js.
+
+**Importing the Module**
+
+<Tabs>
+
+<Tab label="cjs">
+
+```js
+const { execute } = require('@rsdoctor/cli');
+```
+
+</Tab>
+
+<Tab label="esm">
+
+```js
+import { execute } from '@rsdoctor/cli';
+```
+
+</Tab>
+
+</Tabs>
+
+**execute()**
+
+The `execute` asynchronous function is the execution function of Rsdoctor CLI. By calling the `execute` function, it will automatically parse [process.argv](https://nodejs.org/dist/latest-v18.x/docs/api/process.html#processargv) and invoke different commands.
+
+**execute('analyze', \{...\})**
+
+If you need to directly execute the [analyze command](#analyze-command) through the Node.js API, you can call it as follows:
+
+```ts
+execute('analyze', {
+  profile: 'input the manifest.json path or url',
+}).then((sdk) => {
+  console.log('execute "anaylze" command success');
+  // you can stop the Rsdoctor's dev-server by calling the sdk'api below:
+  // sdk.dispose();
+});
+```

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

@@ -0,0 +1,36 @@
+# Features
+
+Here you can learn about the main features supported by Rsdoctor.
+
+## Build Overview
+
+| Feature              | Description                                                            | Related Links                                |
+| -------------------- | ---------------------------------------------------------------------- | -------------------------------------------- |
+| Project Overview     | View information such as the current project configuration and version | [Project Overall](../usage/project-overall)  |
+| Bundle Overview      | View information about the artifacts built for the current project     | [Bundle Overall](../usage/bundle-overall)    |
+| Compilation Overview | View data information about the current project's compilation process  | [Compile Overall](../usage/compile-overall)  |
+| Bundle Alert         | The ability to perform detection based on build artifact data          | [Bundle Alert](../usage/bundle-alerts)       |
+| Compilation Alert    | The ability to perform detection based on compilation data             | [Compilation Alert](../usage/compile-alerts) |
+
+## Compilation Analysis
+
+| Feature                                           | Description                                                                                                                  | Related Links                                                            |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Compilation Overview                              | View data information about the current project's compilation process                                                        | [Compile Overall](../usage/compile-overall)                              |
+| Compilation Alert                                 | The ability to perform detection based on compilation data                                                                   | [Compilation Alert](../usage/compile-alerts)                             |
+| Loader Compilation Behavior Analysis              | Loader analysis data in directory and file dimensions, displaying the compilation behavior of a single file at the same time | [Loaders Analysis](../usage/loaders-analysis)                            |
+| Loader Time Consumption Analysis                  | Execution sequence diagram of all Loaders in the current project                                                             | [Loaders Timeline](../usage/loaders-timeline)                            |
+| Plugins Analysis                                  | Data analysis of the plugins used in the project                                                                             | [Plugins Analysis](../usage/plugins-analysis)                            |
+| Resolver Analysis                                 | Analysis data on Resolver parsing capabilities                                                                               | [Resolver Analysis](../usage/resolver)                                   |
+| Loader Time Consumption Analysis and Optimization | This document describes how to use Rsdoctor to analyze and optimize build time consumption                                   | [Loader Analysis and Optimization](../../blog/topic/loader-optimization) |
+
+## Bundle Analysis
+
+| Feature                         | Description                                                                                                                                            | Related Links                                                             |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Bundle Overview                 | View information about the artifacts built for the current project                                                                                     | [Bundle Overall](../usage/bundle-overall)                                 |
+| Bundle Alert                    | The ability to perform detection based on build artifact data                                                                                          | [Bundle Alert](../usage/bundle-alerts)                                    |
+| Bundle Analysis                 | Analysis of the relationships between assets, chunks, and modules in the artifact, as well as the packaged code and size analysis of each module, etc. | [Bundle Analysis](../usage/bundle-size)                                   |
+| Module Analysis                 | Analysis of module dependencies                                                                                                                        | [Modules Dependency Analysis](../usage/module-analysis)                   |
+| Duplicate Packages Optimization | Inspection of duplicate dependencies used in the project                                                                                               | [Duplicate Packages Optimization](../../blog/topic/duplicate-pkg-problem) |
+| Bundle Diff                     | Comparative analysis of two artifacts                                                                                                                  | Planned support                                                           |

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

@@ -0,0 +1,115 @@
+# Introduction
+
+## 💡 What is Rsdoctor?
+
+- Rsdoctor is a one-stop tool for diagnosing and analyzing the build process and build artifacts.
+- Rsdoctor is a tool that supports Webpack and Rspack build analysis.
+- Rsdoctor is an analysis tool that can display the time-consuming and behavioral details of the compilation.
+- Rsdoctor is a tool that provides bundle Diff and other anti-degradation capabilities simultaneously.
+
+## 🔥 Features
+
+- **Compilation Visualization**: Rsdoctor visualizes the compilation behavior and time consumption, making it easy to view build issues.
+- **Multiple Analysis Capabilities**: Rsdoctor supports build artifact, build-time analysis, and anti-degradation capabilities:
+  - Build artifact support for resource lists and module dependencies, etc.
+  - Build-time analysis supports Loader, Plugin, and Resolver building process analysis, including: Rspack's builtin:swc-loader.
+  - Build rules support duplicate package detection and ES Version Check, etc.
+  - Currently, bundle Diff capabilities are also available.
+- **Support Custom Rules**: In addition to built-in build scan rules, Rsdoctor also supports users adding custom component scan rules based on the build data of Rsdoctor.
+- **Framework-Independent**: Rsdoctor support all projects built on Webpack or Rspack.
+
+## 🛠️ Introduction
+
+### ⭐️ Overview
+
+- The overview page (i.e. the home page) can know **project configuration, diagnostic information, compilation information, and product status**.
+
+![Overall](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/overall.jpg)
+
+- In addition to the project overview, we also provide diagnostic functions, including compilation diagnostics and duplicate packages diagnostics. If your compilation and products hit the diagnostic rules we defined,
+  the corresponding warning alerts will appear on the tool's home page. **where you can see the detailed reference path of duplicate packages**:
+
+![Overall-Alerts](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/overall-alerts.jpg)
+
+### ⭐️ Compilation Analysis
+
+Provides corresponding data and analysis functions for **Loaders, Plugins, and Module Resolve** to help you analyze problems in the compilation process.
+
+#### Loader Analysis
+
+- This module mainly provides the function of data analysis such as input and output, estimated time consumption, and parameters within Rspack / Webpack Loaders.
+
+<div style={{ display: 'flex' }}>
+  <img
+    src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/loader-timeline-overall.png"
+    width="55%"
+    style={{ margin: 'auto' }}
+  />
+  <img
+    src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/loader-anlaysis-all.png"
+    width="45%"
+    style={{ margin: 'auto' }}
+  />
+</div>
+
+#### Plugin Analysis
+
+- This module mainly intercepts and collects data information such as the number of calls and estimated time consumption of Plugins.
+
+<p>
+  <img
+    alt="bundle"
+    src={
+      'https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/compile-plugin.jpg'
+    }
+    width="600px"
+    style={{ margin: 'auto' }}
+  />
+</p>
+
+#### Resolve Analysis
+
+- This module mainly provides path data and estimated time consumption for module resolution in a single file within the project. Rspack does not currently support this module.
+
+<p>
+  <img
+    alt="bundle"
+    src={
+      'https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/resolver.jpeg'
+    }
+    width="700px"
+    style={{ margin: 'auto' }}
+  />
+</p>
+
+### ⭐️ Product Analysis
+
+- In the **Bundle Size** page, we can see an overview of the product data information of the current project, as well as analyze the size and reasons for duplicate package imports.
+
+- In addition, we can also use the **Bundle Analysis** page to further analyze the relationship between the product and module in the current product, size data and other information, as well as the reasons for module introduction.
+
+<p>
+  <img
+    alt="bundle"
+    src={
+      'https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/bundle-size.jpg'
+    }
+    width="700px"
+    style={{ margin: 'auto' }}
+  />
+</p>
+
+### ⭐️ Bundle Diff
+
+::: tip
+Support in progress...
+:::
+
+Using the bundle diff function provided by Rsdoctor, you can see the changes in **the size of resources, duplicate packages, Packages and other data in the product**, as well as **the size of module files and code changes in each resource**.
+
+| ![bundle-diff-1](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/bundle-diff-2.png) | ![bundle-diff-2](https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/start/bundle-diff-1.png) |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+
+## 🧑‍💻 Community
+
+Come and chat with us on [Discord](https://discord.gg/wrBPBT6rkM)! The Rsdoctor team and users are active there, and we're always looking for contributions.