-
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 rsdoctor quick-start docs (#101)
- Loading branch information
Showing
15 changed files
with
710 additions
and
9 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
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,7 @@ | ||
[ | ||
{ | ||
"type": "dir", | ||
"name": "options", | ||
"label": "Options" | ||
} | ||
] |
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 @@ | ||
["index"] |
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,137 @@ | ||
# 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`. | ||
|
||
|
||
#### RsdoctorWebpackPluginFeatures | ||
|
||
The types of `features` are as follows: | ||
|
||
import Features from '@zh/shared/features.md'; | ||
|
||
<Features /> | ||
|
||
#### RsdoctorRspackPluginFeatures | ||
|
||
The types of `features` are as follows: | ||
|
||
import FeaturesRspack from '@zh/shared/features-rspack.md'; | ||
|
||
<FeaturesRspack /> |
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 |
---|---|---|
@@ -1,4 +1,174 @@ | ||
# Quick Start | ||
::: tip | ||
Working On Progress... | ||
::: | ||
|
||
This document will explain how to access the Rsdoctor ability. | ||
|
||
## Step 1: Install dependencies | ||
|
||
### Rspack Projects | ||
|
||
<Tabs> | ||
|
||
<Tab label="pnpm"> | ||
|
||
```bash | ||
pnpm add @rsdoctor/rspack-plugin -D | ||
``` | ||
|
||
</Tab> | ||
|
||
<Tab label="npm"> | ||
|
||
```bash | ||
npm install @rsdoctor/rspack-plugin -D | ||
``` | ||
|
||
</Tab> | ||
|
||
<Tab label="yarn"> | ||
|
||
```bash | ||
yarn add @rsdoctor/rspack-plugin -D | ||
``` | ||
|
||
</Tab> | ||
|
||
</Tabs> | ||
|
||
### Webpack Projects | ||
|
||
import { Tabs, Tab } from "@theme"; | ||
|
||
<Tabs> | ||
|
||
<Tab label="pnpm"> | ||
|
||
```bash | ||
pnpm add @rsdoctor/webpack-plugin -D | ||
``` | ||
|
||
</Tab> | ||
|
||
<Tab label="npm"> | ||
|
||
```bash | ||
npm install @rsdoctor/webpack-plugin -D | ||
``` | ||
|
||
</Tab> | ||
|
||
<Tab label="yarn"> | ||
|
||
```bash | ||
yarn add @rsdoctor/webpack-plugin -D | ||
``` | ||
|
||
</Tab> | ||
|
||
</Tabs> | ||
|
||
## Step 2: Register Plugin | ||
|
||
After the dependency installation is completed, you need to integrate the Rsdoctor plugin into the project. You can configure it according to the corresponding configuration guide based on the project framework. | ||
|
||
|
||
### Rspack | ||
|
||
We need to initialize the RsdoctorRspackPlugin in the [plugins](https://www.rspack.dev/config/plugins.html#plugins) of `rspack.config.js`, referring to the following code: | ||
|
||
```js | ||
const { RsdoctorRspackPlugin } = require("@rsdoctor/rspack-plugin"); | ||
|
||
module.exports = { | ||
// ... | ||
plugins: [ | ||
process.env.ANALYZE && // It is recommended to execute the analysis plugin when ANALYZE is true, because the plugin may increase the build time. | ||
new RsdoctorRspackPlugin(options), // Details of the options are provided below. | ||
].filter(Boolean), | ||
}; | ||
``` | ||
|
||
Next, when you execute the **build** command within the project and complete the build, Rsdoctor will automatically open the analysis page of the build results. | ||
|
||
- **Options Config** | ||
|
||
Please refer to [Options Configuration](../../config/options/index) for Options configuration items. | ||
|
||
|
||
### Webpack | ||
|
||
We need to initialize the RsdoctorWebpackPlugin in the [plugins](https://webpack.js.org/configuration/plugins/#plugins) of `webpack.config.js`, referring to the following code: | ||
|
||
```js | ||
const { RsdoctorWebpackPlugin } = require("@rsdoctor/webpack-plugin"); | ||
|
||
module.exports = { | ||
// ... | ||
plugins: [ | ||
process.env.ANALYZE && // It is recommended to execute the analysis plugin when ANALYZE is true, because the plugin may increase the build time. | ||
new RsdoctorWebpackPlugin(options), // Details of the options are provided below. | ||
].filter(Boolean), | ||
}; | ||
``` | ||
|
||
Next, when you execute the **build** command within the project and complete the build, Rsdoctor will automatically open the analysis page of the build results. | ||
|
||
- **Options Config** | ||
|
||
Please refer to [Options Configuration](../../config/options/index) for Options configuration items. | ||
|
||
|
||
### Modern.js Framework | ||
|
||
We need to initialize the RsdoctorWebpackPlugin in the [tools.bundlerChain](https://modernjs.dev/configure/app/tools/bundler-chain.html#toolsbundlerchain) of `modern.config.ts`, referring to the following code: | ||
|
||
```js | ||
import { RsdoctorWebpackPlugin } from "@rsdoctor/webpack-plugin"; | ||
|
||
module.exports = { | ||
// ... | ||
tools: { | ||
bundlerChain: (chain) => { | ||
if (process.env.ANALYZE) { // It is recommended to execute the analysis plugin when ANALYZE is true, because the plugin may increase the build time. | ||
chain.plugin('rsdoctor').use(RsdoctorWebpackPlugin, [ | ||
options // Details of the options are provided below. | ||
]); | ||
} | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
Next, when you execute the **build** command within the project and complete the build, Rsdoctor will automatically open the analysis page of the build results. | ||
|
||
- **Options Config** | ||
|
||
Please refer to [Options Configuration](../../config/options/index) for Options configuration items. | ||
|
||
|
||
### Rsbuild Framework | ||
|
||
We need to initialize the RsdoctorWebpackPlugin in the [tools.bundlerChain](https://rsbuild.dev/guide/basic/configure-rspack#toolsbundlerchain) of `rsbuild.config.ts`, referring to the following code: | ||
|
||
|
||
```js | ||
import { RsdoctorWebpackPlugin } from "@rsdoctor/webpack-plugin"; | ||
|
||
module.exports = { | ||
// ... | ||
tools: { | ||
bundlerChain: (chain) => { | ||
if (process.env.ANALYZE) { // It is recommended to execute the analysis plugin when ANALYZE is true, because the plugin may increase the build time. | ||
chain.plugin('rsdoctor').use(RsdoctorWebpackPlugin, [ | ||
options // Details of the options are provided below. | ||
]); | ||
} | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
Next, when you execute the **build** command within the project and complete the build, Rsdoctor will automatically open the analysis page of the build results. | ||
|
||
- **Options Config** | ||
|
||
Please refer to [Options Configuration](../../config/options/index) for Options configuration items. |
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 |
---|---|---|
@@ -1,7 +1,12 @@ | ||
[ | ||
{ | ||
"text": "Guide", | ||
"text": "指南", | ||
"link": "/guide/start/intro", | ||
"activeMatch": "/guide/" | ||
}, | ||
{ | ||
"text": "配置", | ||
"link": "/config/options", | ||
"activeMatch": "/config/" | ||
} | ||
] |
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,7 @@ | ||
[ | ||
{ | ||
"type": "dir", | ||
"name": "options", | ||
"label": "options" | ||
} | ||
] |
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 @@ | ||
["index"] |
Oops, something went wrong.