docs: improve plugin hooks document (#1437)

web-infra-dev · Jan 26, 2024 · 5fd5749 · 5fd5749
1 parent b660a4e
commit 5fd5749
Show file tree

Hide file tree

Showing 21 changed files with 110 additions and 98 deletions.
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ Rsbuild has the following features:
 
 - **Plugin Ecosystem**: Rsbuild has a lightweight plugin system and includes a range of high-quality official plugins. Furthermore, Rsbuild is compatible with most webpack plugins and all Rspack plugins, allowing users to leverage existing community or in-house plugins in Rsbuild without the need for rewriting code.
 
-- **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development environment and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.
+- **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.
 
 - **Framework Agnostic**: Rsbuild is not coupled with any front-end UI framework. It supports frameworks like React, Vue 3, Vue 2, Svelte, Solid, and Lit through plugins, and plans to support more UI frameworks from the community in the future.
 

diff --git a/packages/document/docs/en/community/releases/v0-1.mdx b/packages/document/docs/en/community/releases/v0-1.mdx
@@ -28,7 +28,7 @@ Rsbuild has the following features:
 
 - **Plugin Ecosystem**: Rsbuild has a lightweight plugin system and includes a range of high-quality official plugins. Furthermore, Rsbuild is compatible with most webpack plugins and all Rspack plugins, allowing users to leverage existing community or in-house plugins in Rsbuild without the need for rewriting code.
 
-- **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development environment and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.
+- **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.
 
 - **Framework Agnostic**: Rsbuild is not coupled with any front-end UI framework. It supports frameworks like React, Vue 3, Vue 2, Svelte, Solid and Lit through plugins, and plans to support more UI frameworks from the community in the future.
 

diff --git a/packages/document/docs/en/config/dev/asset-prefix.mdx b/packages/document/docs/en/config/dev/asset-prefix.mdx
@@ -3,11 +3,11 @@
 - **Type:** `boolean | string`
 - **Default:** `'/'`
 
-Set the URL prefix of static assets in the development environment.
+Set the URL prefix of static assets during development.
 
 `assetPrefix` will affect the URLs of most of the static assets, including JavaScript files, CSS files, images, videos, etc. If an incorrect value is specified, you'll receive 404 errors while loading these resources.
 
-This config is only used in the development environment. In the production environment, please use the `output.assetPrefix` to set the URL prefix.
+This config is only used during development. In the production environment, please use the `output.assetPrefix` to set the URL prefix.
 
 ### Boolean Type
 
@@ -56,6 +56,6 @@ The script URL will be:
 
 The differences from the native configuration are as follows:
 
-- `dev.assetPrefix` only takes effect in the development environment.
+- `dev.assetPrefix` only takes effect during development.
 - `dev.assetPrefix` automatically appends a trailing `/` by default.
 - The value of `dev.assetPrefix` is written to the `process.env.ASSET_PREFIX` environment variable (can only be accessed in client code).
diff --git a/packages/document/docs/en/config/output/asset-prefix.mdx b/packages/document/docs/en/config/output/asset-prefix.mdx
@@ -3,11 +3,11 @@
 - **Type:** `string`
 - **Default:** `'/'`
 
-When using CDN in the production environment, you can use this option to set the URL prefix of static assets.
+When using CDN in the production build, you can use this option to set the URL prefix of static assets.
 
 `assetPrefix` will affect the URLs of most of the static assets, including JavaScript files, CSS files, images, videos, etc. If an incorrect value is specified, you'll receive 404 errors while loading these resources.
 
-This config is only used in the production environment. In the development environment, please use the `dev.assetPrefix` to set the URL prefix.
+This config is only used in the production build. During development, please use the `dev.assetPrefix` to set the URL prefix.
 
 After setting, the URLs of JavaScript, CSS and other static files will be prefixed with `output.assetPrefix`:
 

diff --git a/packages/document/docs/en/config/output/filename.mdx b/packages/document/docs/en/config/output/filename.mdx
@@ -77,8 +77,8 @@ If you set the filename hash in the development mode, it may cause HMR to fail (
 
 When you import a module via dynamic import, the module will be bundled into a single file, and its default naming rules are as follows:
 
-- In the development environment, the filename will be generated based on the module path, such as `dist/static/js/async/src_add_ts.js`.
-- In the production environment, it will be a random numeric id, such as `dist/static/js/async/798.27e3083e.js`. This is to avoid leaking the source code path in the production environment, and the number of characters is also less.
+- In the development build, the filename will be generated based on the module path, such as `dist/static/js/async/src_add_ts.js`.
+- In the production build, it will be a random numeric id, such as `dist/static/js/async/798.27e3083e.js`. This is to avoid leaking the source code path in the production environment, and the number of characters is also less.
 
 ```js title="src/index.ts"
 const { add } = await import('./add.ts');

diff --git a/packages/document/docs/en/config/output/inject-styles.mdx b/packages/document/docs/en/config/output/inject-styles.mdx
@@ -23,7 +23,7 @@ When `output.injectStyles` is enabled, you can modify the options of `style-load
 
 ### Usage Scenario
 
-It is recommended to only enable the `injectStyles` option in the development environment.
+It is recommended to only enable the `injectStyles` option during development.
 
 For production builds, it is recommended to use the default behavior of Rsbuild, which extracts CSS into separate bundles to allow browsers to load CSS and JS assets in parallel.
 

diff --git a/packages/document/docs/en/guide/advanced/env-vars.md b/packages/document/docs/en/guide/advanced/env-vars.md
@@ -16,15 +16,15 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
-In the development environment, the above code will be compiled as:
+In the development build, the above code will be compiled as:
 
 ```js
 if (true) {
   console.log('this is a development log');
 }
 ```
 
-In the production environment, the above code will be compiled as:
+In the production build, the above code will be compiled as:
 
 ```js
 if (false) {
@@ -318,7 +318,7 @@ const App = () => {
 };
 ```
 
-Specifying the environment variable `REGION=sg` and then executing build will eliminate any dead code.
+Specifying the environment variable `REGION=sg` and then running build will eliminate any dead code.
 
 ```js
 const App = () => {

diff --git a/packages/document/docs/en/guide/basic/cli.mdx b/packages/document/docs/en/guide/basic/cli.mdx
@@ -33,7 +33,7 @@ Commands:
 
 ## rsbuild dev
 
-The `rsbuild dev` command is used to start a local development server and compile the source code in the development environment.
+The `rsbuild dev` command is used to start a local dev server and compile the source code for development.
 
 ```bash
 Usage: rsbuild dev [options]

diff --git a/packages/document/docs/en/guide/basic/output-files.md b/packages/document/docs/en/guide/basic/output-files.md
@@ -148,7 +148,7 @@ dist
 
 ## Writing Outputs to Disk
 
-By default, Rsbuild does not write the output files to disk in the development environment. Instead, the files are stored in the memory of the dev server to reduce the overhead of file operations.
+By default, Rsbuild does not write the output files to disk during development. Instead, the files are stored in the memory of the dev server to reduce the overhead of file operations.
 
 You can write the output files to disk, which is typically used for inspecting the contents of the build artifacts or configuring proxy rules for static assets.
 

diff --git a/packages/document/docs/en/guide/debug/debug-mode.md b/packages/document/docs/en/guide/debug/debug-mode.md
@@ -1,12 +1,12 @@
 # Debug Mode
 
-Rsbuild provides a debug mode to troubleshoot problems, you can add the `DEBUG=rsbuild` environment variable when executing a build to enable Rsbuild's debug mode.
+Rsbuild provides a debug mode to troubleshoot problems, you can add the `DEBUG=rsbuild` environment variable when building to enable Rsbuild's debug mode.
 
 ```bash
-# Debug development environment
+# Debug for development build
 DEBUG=rsbuild pnpm dev
 
-# Debug production environment
+# Debug for production build
 DEBUG=rsbuild pnpm build
 ```
 

diff --git a/packages/document/docs/en/guide/faq/hmr.md b/packages/document/docs/en/guide/faq/hmr.md
@@ -8,8 +8,8 @@ Before starting the troubleshooting process, it is helpful to have a basic under
 
 :::tip HMR Principle
 
-1. The browser establishes a WebSocket connection with the development server for real-time communication.
-2. Whenever the development server finishes recompiling, it sends a notification to the browser via the WebSocket. The browser then sends a `hot-update.xxx` request to the development server to load the newly compiled module.
+1. The browser establishes a WebSocket connection with the dev server for real-time communication.
+2. Whenever the dev server finishes recompiling, it sends a notification to the browser via the WebSocket. The browser then sends a `hot-update.xxx` request to the dev server to load the newly compiled module.
 3. After receiving the new module, if it is a React project, React Refresh, an official React tool, is used to update React components. Other frameworks have similar tools.
 
 :::
@@ -23,15 +23,15 @@ Open the browser console and check for the presence of the `[HMR] connected.` lo
 - If it is present, the WebSocket connection is working correctly. You can continue with the following steps.
 - If it is not present, open the Network panel in Chrome and check the status of the `ws://[host]:[port]/rsbuild-hmr` request. If the request is failed, this indicates that the HMR failed because the WebSocket connection was not successfully established.
 
-There can be various reasons why the WebSocket connection fails to establish, such as using a network proxy that prevents the WebSocket request from reaching the development server. You can check whether the WebSocket request address matches your development server address. If it does not match, you can configure the WebSocket request address using [dev.client](/config/dev/client).
+There can be various reasons why the WebSocket connection fails to establish, such as using a network proxy that prevents the WebSocket request from reaching the dev server. You can check whether the WebSocket request address matches your dev server address. If it does not match, you can configure the WebSocket request address using [dev.client](/config/dev/client).
 
 #### 2. Check the hot-update Requests
 
-When you modify the code of a module and trigger a recompilation, the browser sends several `hot-update.json` and `hot-update.js` requests to the development server to fetch the updated code.
+When you modify the code of a module and trigger a recompilation, the browser sends several `hot-update.json` and `hot-update.js` requests to the dev server to fetch the updated code.
 
 You can try modifying a module and inspect the content of the `hot-update.xxx` requests. If the content of the request is the latest code, it indicates that the hot update request is working correctly.
 
-If the content of the request is incorrect, it is likely due to a network proxy. Check whether the address of the `hot-update.xxx` request matches your development server address. If it does not match, you need to adjust the proxy rules to route the `hot-update.xxx` request to the development server address.
+If the content of the request is incorrect, it is likely due to a network proxy. Check whether the address of the `hot-update.xxx` request matches your dev server address. If it does not match, you need to adjust the proxy rules to route the `hot-update.xxx` request to the dev server address.
 
 #### 3. Check for Other Causes
 

diff --git a/packages/document/docs/en/guide/migration/modern-builder.mdx b/packages/document/docs/en/guide/migration/modern-builder.mdx
@@ -125,7 +125,7 @@ It is worth noting that, compared to Builder, **there are some differences in de
 
 ## Validating Results
 
-After completing the above steps, you have migrated from Modern.js Builder to Rsbuild. You can now try starting the development server by running the `npm run dev` command.
+After completing the above steps, you have migrated from Modern.js Builder to Rsbuild. You can now try starting the dev server by running the `npm run dev` command.
 
 If you encounter any issues during the build process, please debug according to the error logs.
 

diff --git a/packages/document/docs/en/guide/optimization/build-performance.mdx b/packages/document/docs/en/guide/optimization/build-performance.mdx
@@ -42,7 +42,7 @@ The following are strategies for improve build performance in development enviro
 
 ### Adjust Source Map format
 
-In order to provide a good debugging experience, Rsbuild uses the `cheap-module-source-map` format Source Map by default in the development environment, which is a high-quality Source Map format and will bring certain performance overhead.
+In order to provide a good debugging experience, Rsbuild uses the `cheap-module-source-map` format Source Map by default during development, which is a high-quality Source Map format and will bring certain performance overhead.
 
 You can improve build speed by adjusting the source map format of your development environment.
 
@@ -74,9 +74,9 @@ export default {
 
 ### Adjust Browserslist for development
 
-This strategy is similar to ["Adjust Browserslist"](/guide/optimization/optimize-bundle#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead in the development environment.
+This strategy is similar to ["Adjust Browserslist"](/guide/optimization/optimize-bundle#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead during development.
 
-For example, you can add the following config to `package.json`, which means that only the latest browsers are compatible in the development environment, and the actual browsers are compatible in the production environment:
+For example, you can add the following config to `package.json`, which means that only the latest browsers are compatible during development, and the actual browsers are compatible in the production environment:
 
 ```json
 {

diff --git a/packages/document/docs/en/guide/start/features.mdx b/packages/document/docs/en/guide/start/features.mdx
@@ -11,7 +11,7 @@ Here are all the main features supported by Rsbuild.
 | TS compilation       | TS files are compiled by SWC by default                                                                                        | <ul><li>[TypeScript compilation](/guide/basic/typescript#typescript-compilation)</li></ul>                                          |
 | JS minification      | JS minification is enabled by default in production build                                                                      | <ul><li>[output.disableMinimize](/config/output/disable-minimize)</li></ul>                                                         |
 | Polyfill injection   | core-js and other polyfills are injected by default                                                                            | <ul><li>[Browser Compatibility](/guide/advanced/browser-compatibility)</li><li>[output.polyfill](/config/output/polyfill)</li></ul> |
-| SourceMap generation | SourceMap is generated in the development environment by default                                                               | <ul><li>[output.sourceMap](/config/output/source-map)</li></ul>                                                                     |
+| SourceMap generation | Source maps are generated during development by default                                                                        | <ul><li>[output.sourceMap](/config/output/source-map)</li></ul>                                                                     |
 | Alias                | Optional feature, set import alias                                                                                             | <ul><li>[source.alias](/config/source/alias)</li></ul>                                                                              |
 | Babel compilation    | Optional feature, use Babel to transform JavaScript and TypeScript code                                                        | <ul><li>[Babel Plugin](/plugins/list/plugin-babel)</li></ul>                                                                        |
 | Node outputs         | Optional feature, support building bundles that run in Node.js environment                                                     | <ul><li>[Node Target](/config/output/targets#node-target)</li></ul>                                                                 |

diff --git a/packages/document/docs/en/guide/start/index.mdx b/packages/document/docs/en/guide/start/index.mdx
@@ -27,7 +27,7 @@ Rsbuild has the following features:
 
 - **Plugin Ecosystem**: Rsbuild has a lightweight plugin system and includes a range of high-quality official plugins. Furthermore, Rsbuild is compatible with most webpack plugins and all Rspack plugins, allowing users to leverage existing community or in-house plugins in Rsbuild without the need for rewriting code.
 
-- **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development environment and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.
+- **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.
 
 - **Framework Agnostic**: Rsbuild is not coupled with any front-end UI framework. It supports frameworks like React, Vue 3, Vue 2, Svelte, Solid, and Lit through plugins, and plans to support more UI frameworks from the community in the future.