docs(module): add custom esbuild plugin example (#4228)

* docs(module): add custom esbuild plugin example

* docs: update

packages/document/builder-doc/docs/en/config/source/define.md

@@ -10,7 +10,7 @@ Each key passed into options is an identifier or multiple identifiers joined wit
 - If the value is an object all keys are defined the same way.
 - If you prefix typeof to the key, it's only defined for typeof calls.
 
-For more information please visit [https://webpack.js.org/plugins/define-plugin/](https://webpack.js.org/plugins/define-plugin/).
+For more information please visit [webpack - DefinePlugin](https://webpack.js.org/plugins/define-plugin/).
 
 :::tip
 When using Rspack as the bundler, the supported types can be found in [Rspack.builtins.define](https://www.rspack.dev/config/builtins.html#builtinsdefine).

packages/document/builder-doc/docs/zh/config/source/define.md

@@ -10,7 +10,7 @@
 - 嵌套对象的父子键名之间会用 `.` 连接作为需要替换的变量名。
 - 以 typeof 开头的键名会用来替换 typeof 调用。
 
-更多细节参考 [https://webpack.js.org/plugins/define-plugin/](https://webpack.js.org/plugins/define-plugin/)。
+更多细节参考 [webpack - DefinePlugin](https://webpack.js.org/plugins/define-plugin/)。
 
 :::tip
 在使用 Rspack 作为打包工具时，支持的类型可参考 [Rspack.builtins.define](https://www.rspack.dev/zh/config/builtins.html#builtinsdefine)

packages/document/module-doc/docs/en/api/config/build-config.md → packages/document/module-doc/docs/en/api/config/build-config.mdx

@@ -293,14 +293,14 @@ To prevent excessive global replacement substitution, it is recommended that the
 
 :::
 
-<!-- ## disableSwcTransform
+{/* ## disableSwcTransform
 
 Starting with version 2.16.0, SWC Transform is enabled by default for code transformation. If you want to disable this feature, you can use this configuration. Only esbuild Transform is used in this case.
 
 The use of SWC Transform can reduce the impact of auxiliary functions on the volume of the constructed product.
 
 * **Type**: `boolean`
-* **Default**: `false` -->
+* **Default**: `false` */}
 
 ## dts
 
@@ -374,7 +374,7 @@ Path to the tsconfig file
 
 ## esbuildOptions
 
-Directly modify [esbuild configuration](https://esbuild.github.io/api/)
+Used to modify the [esbuild configuration](https://esbuild.github.io/api/).
 
 - **Type**: `Function`
 - **Default**: `c => c`
@@ -392,12 +392,17 @@ export default defineConfig({
 });
 ```
 
+For example, register an esbuild plugin:
+
+import RegisterEsbuildPlugin from '@site-docs-en/components/register-esbuild-plugin';
+
+<RegisterEsbuildPlugin />
+
 :::tip
 We have done many extensions based on the original esbuild build. Therefore, when using this configuration, pay attention to the following:
 
-1. Prefer to use the configuration we provide. For example, esbuild does not support target: 'es5', but we support this scenario internally using swc. Setting target: 'es5' through esbuildOptions will result in an error.
+1. Prefer to use the configuration that Modern.js Module provides. For example, esbuild does not support `target: 'es5'`, but we support this scenario internally using SWC. Setting `target: 'es5'` through esbuildOptions will result in an error.
 2. Currently, we use enhanced-resolve internally to replace esbuild's resolve algorithm, so modifying esbuild resolve-related configurations is invalid. We plan to switch back in the future.
-3. When using esbuild plugins, you need to add the plugins to the beginning of the plugins array because we also intervene in the entire build process through an esbuild plugin internally. Therefore, custom plugins need to be registered first.
 
 :::
 
@@ -1016,6 +1021,7 @@ const tailwind = {
   ],
 };
 ```
+</details>
 
 When the value is of type `object`, it is merged with the default configuration via `Object.assign`.
 

packages/document/module-doc/docs/en/components/register-esbuild-plugin.mdx

@@ -0,0 +1,14 @@
+```js modern.config.ts
+import { myEsbuildPlugin } from './myEsbuildPlugin';
+
+export default defineConfig({
+  buildConfig: {
+    esbuildOptions: options => {
+      options.plugins = [myEsbuildPlugin, ...options.plugins];
+      return option;
+    },
+  },
+});
+```
+
+When adding an esbuild plugin, please note that you need to add the plugin at the beginning of the plugins array. This is because the Modern.js Module is also integrated into the entire build process through an esbuild plugin. Therefore, custom plugins need to be registered with higher priority.

packages/document/module-doc/docs/en/guide/faq/build.mdx

@@ -4,15 +4,15 @@
 
 import BuildProductFAQ from '@site-docs-en/components/faq-build-product';
 
-<BuildProductFAQ/>
+<BuildProductFAQ />
 
 ### Initialization of Class Fields
 
 TypeSript provides the `useDefineForClassFields` configuration to control the conversion handling for `public class fields`.
 
 If we have a piece of code:
 
-``` ts
+```ts
 class C {
   foo = 100;
   bar: string;
@@ -21,7 +21,7 @@ class C {
 
 When `useDefineForClassFields` is `false`, then the compiled code will look like:
 
-``` ts
+```ts
 class C {
   constructor() {
     this.foo = 100;
@@ -31,16 +31,16 @@ class C {
 
 When `useDefineForClassFields` is `true`, then the compiled code will look like:
 
-``` ts
+```ts
 class C {
   constructor() {
-    Object.defineProperty(this, "foo", {
+    Object.defineProperty(this, 'foo', {
       enumerable: true,
       configurable: true,
       writable: true,
       value: 100,
     });
-    Object.defineProperty(this, "bar", {
+    Object.defineProperty(this, 'bar', {
       enumerable: true,
       configurable: true,
       writable: true,
@@ -66,12 +66,12 @@ The Modern.js Module will currently process according to the following logic:
 
 This problem occurs when using something like the following:
 
-``` ts
+```ts
 import * as Lodash from 'lodash';
 
 export const libs = {
   _: Lodash,
-}
+};
 ```
 
 Current related issues on the `babel-plugin-lodash` Github:
@@ -82,7 +82,7 @@ The solution to this problem is to remove `babel-plugin-lodash`, since the plugi
 
 A similar situation occurs with `babel-plugin-import`. If there is code like the following:
 
-``` ts
+```ts
 import * as Comps from 'components';
 
 export const libs = {
@@ -104,7 +104,7 @@ import BuildExceptionFAQ from '@site-docs-en/components/faq-build-exception';
 
 When the product format in the product configuration of the build is ES modules.
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     format: 'esm',
@@ -121,11 +121,11 @@ If you import a cjs product from a third-party npm package, the resulting produc
 1. **First you need to find which third-party package is causing the problem**. For example, if the error message points to the `react` package, then look for a third-party package that has code like `require('react')` in it. For example [`react-draggable`](https://www.npmjs.com/package/react-draggable), which only contains `cjs` products, then the problem is localized to the `react-draggable` package.
 2. Then we need to exclude this package with the following configuration, i.e. **not package problematic third-party packages**.
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     externals: ['react-draggable'],
-  }
+  },
 });
 ```
 
@@ -141,7 +141,7 @@ Therefore, if a component library like this is used in the source code:
 
 `buildPreset` is used in the build configuration, make the following changes:
 
-``` js
+```js
 module.exports = {
   buildPreset({ extendPreset }) {
     return extendPreset('your-build-preset', {
@@ -154,12 +154,12 @@ module.exports = {
       },
     });
   },
-}
+};
 ```
 
 Or, if a custom `buildConfig` is used, modify it as follows:
 
-``` js
+```js
 module.exports = {
   buildConfig: {
     style: {
@@ -169,7 +169,7 @@ module.exports = {
         },
       },
     },
-  }
+  },
 };
 ```
 
@@ -193,7 +193,7 @@ module.exports = {
       },
     },
   },
-}
+};
 ```
 
 ### Bundle DTS failed
@@ -206,7 +206,7 @@ So when you encounter a `Bundle DTS failed` error message during the Modern.js M
 
 ### Error reported for `defineConfig` function type: `If there is no reference to "..." then the inferred type of "default" cannot be named`
 
-Check if the [`include`](https://www.typescriptlang.org/tsconfig#include)  configuration exists in the project's tsconfig.json file, and if not, try adding the following:
+Check if the [`include`](https://www.typescriptlang.org/tsconfig#include) configuration exists in the project's tsconfig.json file, and if not, try adding the following:
 
 ```json
 {
@@ -226,22 +226,11 @@ The Modern.js Module is based on the esbuild implementation, so if you have spec
 
 The Modern.js Module provides [`esbuildOptions`](/api/config/build-config.html#esbuildoptions) configuration to allow modification of Modern.js's internal esbuild configuration, so that custom esbuild plugins can be added via this configuration:
 
-``` js
-export default defineConfig({
-  buildConfig: {
-    esbuildOptions: options => {
-      options.plugins = [
-        ...options.plugins,
-        yourEsbuildPlugin,
-      ];
-      return option;
-    },
-  },
-});
-```
+import RegisterEsbuildPlugin from '@site-docs-en/components/register-esbuild-plugin';
+
+<RegisterEsbuildPlugin />
 
 ### Support for generating TypeScript declaration files for CSS Modules
 
 - First Solution: [typed-css-modules](https://github.com/Quramy/typed-css-modules)
 - Second Solution: [postcss-modules-dts](https://www.npmjs.com/package/@guanghechen/postcss-modules-dts)
-

packages/document/module-doc/docs/zh/api/config/build-config.md → packages/document/module-doc/docs/zh/api/config/build-config.mdx

@@ -293,14 +293,14 @@ export default defineConfig({
 
 :::
 
-<!-- ## disableSwcTransform
+{/* ## disableSwcTransform
 
 从 2.16.0 版本开始，默认开启 SWC Transform 进行代码转换。如果想要关闭该功能，可以使用该配置。此时仅使用 esbuild Transform。
 
 使用 SWC Transform 可以减小辅助函数对构建产物体积的影响。
 
 * 类型：`boolean`
-* 默认值：`false` -->
+* 默认值：`false` */}
 
 ## dts
 
@@ -373,12 +373,12 @@ TypeScript 配置文件的路径。
 
 ## esbuildOptions
 
-直接修改[esbuild 配置](https://esbuild.github.io/api/)
+用于修改底层的 [esbuild 配置](https://esbuild.github.io/api/)。
 
 - 类型: `Function`
 - 默认值: `c => c`
 
-例如我们需要修改生成文件的后缀：
+例如，我们需要修改生成文件的后缀：
 
 ```js modern.config.ts
 export default defineConfig({
@@ -391,12 +391,17 @@ export default defineConfig({
 });
 ```
 
+例如，注册一个 esbuild 插件：
+
+import RegisterEsbuildPlugin from '@site-docs/components/register-esbuild-plugin';
+
+<RegisterEsbuildPlugin />
+
 :::tip
 我们在原本 esbuild 构建的基础上做了许多扩展，因此使用此配置需要注意以下几点：
 
-1. 优先使用我们提供的配置，例如 esbuild 并不支持`target: 'es5'`，但我们内部使用 swc 支持了此场景，此时通过`esbuildOptions`设置`target: 'es5'`会报错。
-2. 目前我们内部使用`enhanced-resolve`替代了 esbuild 的 resolve 解析算法，所以修改 esbuild resolve 相关配置无效，计划在未来会切换回来。
-3. 使用 esbuild 插件时需要将插件加在 plugins 数组的头部，因为我们内部也是通过一个 esbuild 插件介入到整个构建流程中去的，因此需要将自定义插件优先注册。
+1. 优先使用 Modern.js Module 提供的配置，例如 esbuild 并不支持 `target: 'es5'`，但我们内部使用 SWC 支持了此场景，此时通过 `esbuildOptions` 设置`target: 'es5'`会报错。
+2. 目前我们内部使用 `enhanced-resolve` 替代了 esbuild 的 resolve 解析算法，所以修改 esbuild resolve 相关配置无效，计划在未来会切换回来。
 
 :::
 
@@ -1019,6 +1024,7 @@ const tailwind = {
   ],
 };
 ```
+</details>
 
 值为 `object` 类型时，与默认配置通过 `Object.assign` 合并。
 

packages/document/module-doc/docs/zh/components/register-esbuild-plugin.mdx

@@ -0,0 +1,14 @@
+```js modern.config.ts
+import { myEsbuildPlugin } from './myEsbuildPlugin';
+
+export default defineConfig({
+  buildConfig: {
+    esbuildOptions: options => {
+      options.plugins = [myEsbuildPlugin, ...options.plugins];
+      return option;
+    },
+  },
+});
+```
+
+在增加 esbuild 插件时，请注意你需要将插件加在 plugins 数组的头部，因为 Modern.js Module 内部也是通过一个 esbuild 插件介入到整个构建流程中去的，因此需要将自定义插件优先注册。