@modern-js/module-tools-docs 2.25.2 → 2.27.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @modern-js/module-tools-docs
 
+## 2.27.0
+
+### Patch Changes
+
+- @modern-js/doc-tools@2.27.0
+- @modern-js/doc-plugin-auto-sidebar@2.27.0
+
+## 2.26.0
+
+### Patch Changes
+
+- @modern-js/doc-tools@2.26.0
+- @modern-js/doc-plugin-auto-sidebar@2.26.0
+
 ## 2.25.2
 
 ### Patch Changes

package/docs/en/api/config/{build-config.md → build-config.mdx}

@@ -36,7 +36,7 @@ export default {
 };
 ```
 
-After the above configuration is done, if `@common/Foo.tsx` is referenced in the code, it will map to the `<root>/src/common/Foo.tsx` path.
+After the above configuration is done, if `@common/Foo.tsx` is referenced in the code, it will map to the `<project>/src/common/Foo.tsx` path.
 
 When the value of `alias` is defined as a function, you can accept the pre-defined alias object and modify it.
 
@@ -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`.
 

package/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.

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

@@ -4,7 +4,7 @@
 
 import BuildProductFAQ from '@site-docs-en/components/faq-build-product';
 
-<BuildProductFAQ/>
+<BuildProductFAQ />
 
 ### Initialization of Class Fields
 
@@ -12,7 +12,7 @@ TypeSript provides the `useDefineForClassFields` configuration to control the co
 
 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)
-

package/docs/zh/api/config/{build-config.md → build-config.mdx}

@@ -36,7 +36,7 @@ export default defineConfig({
 });
 ```
 
-以上配置完成后，如果在代码中引用 `@common/Foo.tsx`, 则会映射到 `<root>/src/common/Foo.tsx` 路径上。
+以上配置完成后，如果在代码中引用 `@common/Foo.tsx`, 则会映射到 `<project>/src/common/Foo.tsx` 路径上。
 
 `alias` 的值定义为函数时，可以接受预设的 alias 对象，并对其进行修改。
 
@@ -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` 合并。
 

package/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 插件介入到整个构建流程中去的，因此需要将自定义插件优先注册。

package/docs/zh/guide/faq/build.mdx

@@ -4,7 +4,7 @@
 
 import BuildProductFAQ from '@site-docs/components/faq-build-product';
 
-<BuildProductFAQ/>
+<BuildProductFAQ />
 
 ### Class Fields 的初始化处理
 
@@ -12,7 +12,7 @@ TypeSript 提供了 `useDefineForClassFields` 配置用于控制对于 `public c
 
 如果有一段代码：
 
-``` ts
+```ts
 class C {
   foo = 100;
   bar: string;
@@ -21,7 +21,7 @@ class C {
 
 当 `useDefineForClassFields` 为 `false` 的时候，则编译后的代码会变为：
 
-``` ts
+```ts
 class C {
   constructor() {
     this.foo = 100;
@@ -31,16 +31,16 @@ class C {
 
 当 `useDefineForClassFields` 为 `true` 的时候，则编译后的代码会变为：
 
-``` 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 @@ Modern.js Module 目前会根据下面的逻辑进行处理：
 
 当使用类似下面的方式的时候，会出现这个问题：
 
-``` ts
+```ts
 import * as Lodash from 'lodash';
 
 export const libs = {
   _: Lodash,
-}
+};
 ```
 
 目前在 `babel-plugin-lodash` Github 上的相关 Issue：
@@ -82,7 +82,7 @@ export const libs = {
 
 类似的情况在 `babel-plugin-import` 上也可能会出现。比如有类似如下的代码：
 
-``` ts
+```ts
 import * as Comps from 'components';
 
 export const libs = {
@@ -104,7 +104,7 @@ import BuildExceptionFAQ from '@site-docs/components/faq-build-exception';
 
 当构建的产物配置中产物格式为 ES modules 的时候：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     format: 'esm',
@@ -121,11 +121,11 @@ export default defineConfig({
 1. **首先需要找到是哪个第三方包引起的问题**。例如报错信息中指向了 `react` 这个包，那么就要寻找在哪个第三方包里存在 `require('react')` 这样的代码。比如 [`react-draggable`](https://www.npmjs.com/package/react-draggable) ，这个包仅包含 `cjs` 产物，那么问题定位到 `react-draggable` 这个包。
 2. 然后我们需要将这个包通过下面的配置进行排除，即**不打包存在问题的第三方包**。
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     externals: ['react-draggable'],
-  }
+  },
 });
 ```
 
@@ -133,7 +133,6 @@ export default defineConfig({
 
 - [When using esbuild with external react I get Dynamic require of "react" is not supported](https://stackoverflow.com/questions/68423950/when-using-esbuild-with-external-react-i-get-dynamic-require-of-react-is-not-s)
 
-
 ### 编译过程中，因为某个组件库的 less 文件报错：`'Operation on an invalid type'`
 
 可能是因为该组件库依赖的 Less 版本是 v3，而 Modern.js Module 默认是 v4。v3 与 v4 在 `math` 配置上存在有 Break Change，可以查看这个[链接](https://stackoverflow.com/questions/73298187/less-error-operation-on-an-invalid-type-in-antd-dependency) 了解详情。
@@ -142,7 +141,7 @@ export default defineConfig({
 
 在构建配置中使用了 `buildPreset` 的情况下，按照下面进行修改：
 
-``` js
+```js
 module.exports = {
   buildPreset({ extendPreset }) {
     return extendPreset('your-build-preset', {
@@ -155,12 +154,12 @@ module.exports = {
       },
     });
   },
-}
+};
 ```
 
 或者使用了自定义的 `buildConfig` 的情况下，按照下面进行修改：
 
-``` js
+```js
 module.exports = {
   buildConfig: {
     style: {
@@ -170,7 +169,7 @@ module.exports = {
         },
       },
     },
-  }
+  },
 };
 ```
 
@@ -194,7 +193,7 @@ module.exports = {
       },
     },
   },
-}
+};
 ```
 
 ### Bundle DTS failed
@@ -227,19 +226,9 @@ Modern.js Module 基于 esbuild 实现，因此如果有特殊需求或者想要
 
 Modern.js Module 提供了 [`esbuildOptions`](/api/config/build-config.html#esbuildoptions) 配置允许修改 Modern.js Module 内部的 esbuild 配置，因此可以通过该配置来增加自定义的 esbuild 插件：
 
-``` js
-export default defineConfig({
-  buildConfig: {
-    esbuildOptions: options => {
-      options.plugins = [
-        ...options.plugins,
-        yourEsbuildPlugin,
-      ];
-      return option;
-    },
-  },
-});
-```
+import RegisterEsbuildPlugin from '@site-docs/components/register-esbuild-plugin';
+
+<RegisterEsbuildPlugin />
 
 ### 支持生成 CSS Modules 的 TypeScript 声明文件
 

package/package.json

@@ -9,15 +9,15 @@
     "directory": "packages/document/module-doc"
   },
   "license": "MIT",
-  "version": "2.25.2",
+  "version": "2.27.0",
   "main": "index.js",
   "dependencies": {
     "@code-hike/mdx": "^0.7.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "shiki": "^0.11.1",
-    "@modern-js/doc-tools": "2.25.2",
-    "@modern-js/doc-plugin-auto-sidebar": "2.25.2"
+    "@modern-js/doc-tools": "2.27.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.27.0"
   },
   "scripts": {
     "dev": "modern dev",