Skip to content

Commit

Permalink
chore(docs): add rsdoctor quick-start docs (#101)
Browse files Browse the repository at this point in the history
  • Loading branch information
easy1090 authored Jan 9, 2024
1 parent eeb5c59 commit 6204e5b
Show file tree
Hide file tree
Showing 15 changed files with 710 additions and 9 deletions.
5 changes: 5 additions & 0 deletions document/docs/en/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,10 @@
"text": "Guide",
"link": "/guide/start/intro",
"activeMatch": "/guide/"
},
{
"text": "Config",
"link": "/config/options/",
"activeMatch": "/config/"
}
]
7 changes: 7 additions & 0 deletions document/docs/en/config/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[
{
"type": "dir",
"name": "options",
"label": "Options"
}
]
1 change: 1 addition & 0 deletions document/docs/en/config/options/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
["index"]
137 changes: 137 additions & 0 deletions document/docs/en/config/options/index.mdx
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 />
176 changes: 173 additions & 3 deletions document/docs/en/guide/start/quick-start.mdx
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.
7 changes: 6 additions & 1 deletion document/docs/zh/_meta.json
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/"
}
]
7 changes: 7 additions & 0 deletions document/docs/zh/config/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[
{
"type": "dir",
"name": "options",
"label": "options"
}
]
1 change: 1 addition & 0 deletions document/docs/zh/config/options/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
["index"]
Loading

0 comments on commit 6204e5b

Please sign in to comment.