@modern-js/module-tools-docs 2.30.0 → 2.31.0

package/docs/en/plugins/guide/getting-started.mdx

@@ -8,9 +8,9 @@ Module engineering solution not only provides a rich set of features, but also s
 
 We can quickly see how to write a Module Tools plugin by using the following example.
 
-<CH.Spotlight>
+1. First we create `. /plugins/example.ts` file under the initialized project.
 
-```md . /project
+```md title=". /project"
 . /project .
 ├── plugins
 │ └── example.ts
@@ -18,17 +18,7 @@ We can quickly see how to write a Module Tools plugin by using the following exa
 └── modern.config.ts
 ```
 
----
-
-First we create `. /plugins/example.ts` file under the initialized project.
-
-```md . /project
-
-```
-
----
-
-Next add the code for the plugin to the `example.ts` file.
+2. Next add the code for the plugin to the `example.ts` file.
 
 ```ts
 import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
@@ -42,36 +32,30 @@ export const ExamplePlugin = (): CliPlugin<ModuleTools> => {
         // use hooks
         afterBuild() {
           console.info('build over');
-        }
+        },
       };
     },
   };
 };
 ```
 
----
-
-Then we register the plugin we just wrote via the [`plugins`](/en/api/config/plugins) API.
+3. Then we register the plugin we just wrote via the [`plugins`](/en/api/config/plugins) API.
 
-```ts . /modern.config.ts
+```ts title=". /modern.config.ts"
 import { examplePlugin } from '. /plugins/example';
 export default defineConfig({
   plugins: [examplePlugin()],
 });
 ```
 
----
-
-Finally, run `modern build` and you will see.
+4. Finally, run `modern build` and you will see:
 
-```bash terminal
+```bash title="terminal"
 This is example plugin
 Build succeed: 510.684ms
 build over
 ```
 
-</CH.Spotlight>
-
 With the above example, we learned the following things.
 
 - The recommended plugin directory structure

package/docs/en/plugins/guide/plugin-object.mdx

@@ -11,9 +11,7 @@ The Module Tools plugin is an object, and the object contains the following prop
 
 For example, in the following plugin code example, the `beforeBuild` function is triggered before the project starts the build task and the `build start` log is printed.
 
-<CH.Code>
-
-```ts . /plugins/demo.tsx
+```ts title=". /plugins/demo.tsx"
 import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
 
 const myPlugin: CliPlugin<ModuleTools> = {
@@ -30,17 +28,13 @@ const myPlugin: CliPlugin<ModuleTools> = {
 };
 ```
 
----
-
-```ts . /modern.config.ts
+```ts title="modern.config.ts"
 import { myPlugin } from '. /plugins/demo';
 export default {
   plugins: [myPlugin()],
 };
 ```
 
-</CH.Code>
-
 ## Plugin type definitions
 
 When using TypeScript, you can introduce the built-in `CliPlugin` and `ModuleTools` types to provide the correct type derivation for plugins: ``

package/docs/en/plugins/official-list/plugin-import.mdx

@@ -92,79 +92,36 @@ Some configurations can accept functions, such as `customName`, `customStyleName
 
 Simple function logic can be replaced by template language. Therefore, for configurations such as `customName`, `customStyleName`, etc., instead of passing functions, you can also pass a string as a template to replace the function, improving performance.
 
-<CH.Spotlight>
+We will use the following code as example:
 
 ```ts
 import { MyButton as Btn } from 'foo';
 ```
 
----
-
-We will use this piece of code for illustration.
-
-```ts
-import { MyButton as Btn } from 'foo';
-```
-
----
-
 Add the following configuration on the right-hand side:
 
 ```ts
-import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  plugins: [
-    moduleTools(),
-    modulePluginImport({
-      pluginImport: [
-        {
-          libraryName: 'foo',
-          customName: 'foo/es/{{ member }}',
-        },
-      ],
-    }),
+modulePluginImport({
+  pluginImport: [
+    {
+      libraryName: 'foo',
+      customName: 'foo/es/{{ member }}',
+    },
   ],
 });
 ```
 
----
-
-The `{{ member }}` in it will be replaced with the corresponding import member.
-
-```ts focus=8:8
-import { modulePluginImport } from '@modern-js/plugin-module-import';
-
-export default defineConfig({
-  plugins: [
-    modulePluginImport({
-      pluginImport: [
-        {
-          libraryName: 'foo',
-          customName: 'foo/es/{{ member }}',
-        },
-      ],
-    }),
-  ],
-});
-```
-
----
-
-After transformation:
+The `{{ member }}` in it will be replaced with the corresponding import member. After transformation:
 
 ```ts
 import Btn from 'foo/es/MyButton';
 ```
 
-</CH.Spotlight>
-
 Template `customName: 'foo/es/{{ member }}'` is the same as `` customName: (member) => `foo/es/${member}` ``, but template value has no performance overhead of Node-API.
 
 The template used here is [handlebars](https://handlebarsjs.com). There are some useful builtin tools, Take the above import statement as an example:
 
-```ts focus=8:8
+```ts
 import { modulePluginImport } from '@modern-js/plugin-module-import';
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 

package/docs/en/plugins/official-list/plugin-node-polyfill.md

@@ -52,7 +52,7 @@ type NodePolyfillOptions = {
 
 Exclude the Node Polyfill to be injected.
 
-``` ts focus=7:9
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
 
@@ -70,7 +70,7 @@ export default defineConfig({
 
 Override the built-in Node Polyfill.
 
-``` ts focus=7:9
+```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
 

package/docs/zh/api/config/build-config.mdx

@@ -26,7 +26,7 @@ sidebar_position: 1
 对于 TypeScript 项目，只需要在 `tsconfig.json` 中配置 [compilerOptions.paths](https://www.typescriptlang.org/tsconfig#paths), Module Tools 会自动识别 `tsconfig.json` 里的别名，因此不需要额外配置 `alias` 字段。
 :::
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     alias: {
@@ -40,7 +40,7 @@ export default defineConfig({
 
 `alias` 的值定义为函数时，可以接受预设的 alias 对象，并对其进行修改。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     alias: alias => {
@@ -52,7 +52,7 @@ export default defineConfig({
 
 也可以在函数中返回一个新对象作为最终结果，新对象会覆盖预设的 alias 对象。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     alias: alias => {
@@ -88,7 +88,7 @@ Module Tools 在进行打包时，默认会内联体积小于 10KB 的图片、
 
 例如，将 `limit` 设置为 `0` 来避免资源内联：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     asset: {
@@ -105,7 +105,7 @@ export default defineConfig({
 - 类型： `string`
 - 默认值： `undefined`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     asset: {
@@ -126,7 +126,7 @@ export default defineConfig({
 
 开启 svgr 功能后，可以使用默认导出的方式将 SVG 当做组件使用。
 
-```js index.ts
+```js title="index.ts"
 // true
 import Logo from './logo.svg';
 
@@ -137,7 +137,7 @@ export default () => <Logo />;
 
 目前不支持下面的用法：
 
-```js index.ts
+```js title="index.ts"
 import { ReactComponent } from './logo.svg';
 ```
 
@@ -145,7 +145,7 @@ import { ReactComponent } from './logo.svg';
 
 当开启功能后，可以通过在 `modern-app-env.d.ts` 文件中增加类型定义，修改使用 SVG 的类型：
 
-```ts modern-app-env.d.ts focus=1:3
+```ts title="modern-app-env.d.ts"
 declare module '*.svg' {
   const src: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
   export default src;
@@ -177,7 +177,7 @@ declare module '*.svg' {
 
 当我们希望关闭对于第三方依赖的默认处理行为时候，可以通过以下方式来实现：
 
-```ts modern.config.ts
+```ts title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     autoExternal: false,
@@ -188,7 +188,7 @@ export default defineConfig({
 这样对于 `"dependencies"` 和 `"peerDependencies"` 下面的依赖都会进行打包处理。如果只想要关闭其中某个下面的依赖处理，则可以使用
 `buildConfig.autoExternal` 的对象形式：
 
-```ts modern.config.ts
+```ts title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     autoExternal: {
@@ -226,7 +226,7 @@ export default defineConfig({
 
 - 类型： `object`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     copy: {
@@ -275,7 +275,7 @@ type Options = {
 
 由于 `define` 功能是由全局文本替换实现的，所以需要保证全局变量值为字符串，更为安全的做法是将每个全局变量的值转化为字符串，使用 `JSON.stringify` 进行转换，如下所示：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     define: {
@@ -327,7 +327,7 @@ export default defineConfig({
 
 **默认情况下，在出现类型错误的时候会导致构建失败**。将 `abortOnError` 设置为 `false` 后，即使代码中出现了类型问题，构建依然会成功：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     dts: {
@@ -350,7 +350,7 @@ export default defineConfig({
 
 比如输出到 `outDir` 下面的 `types` 目录：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     dts: {
@@ -367,7 +367,7 @@ export default defineConfig({
 - 类型： `boolean`
 - 默认值： `false`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     dts: {
@@ -386,7 +386,7 @@ export default defineConfig({
 - 类型： `boolean`
 - 默认值： `true`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     dts: {
@@ -403,7 +403,7 @@ TypeScript 配置文件的路径。
 - 类型： `string`
 - 默认值： `./tsconfig.json`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     dts: {
@@ -422,12 +422,12 @@ export default defineConfig({
 
 例如，我们需要修改生成文件的后缀：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     esbuildOptions: options => {
       options.outExtension = { '.js': '.mjs' };
-      return option;
+      return options;
     },
   },
 });
@@ -460,7 +460,7 @@ import RegisterEsbuildPlugin from '@site-docs/components/register-esbuild-plugin
 
 开启前：
 
-```js ./dist/index.js
+```js title="./dist/index.js"
 // 辅助函数
 function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
   // ...
@@ -481,7 +481,7 @@ export var yourCode = function () {
 
 开启后：
 
-```js ./dist/index.js
+```js title="./dist/index.js"
 // 从 @swc/helpers 导入的辅助函数
 import { _ as _async_to_generator } from '@swc/helpers/_/_async_to_generator';
 
@@ -505,7 +505,7 @@ type Externals = (string | RegExp)[];
 - 构建类型：`仅支持 buildType: 'bundle'`
 - 示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     // 避免打包 React
@@ -527,7 +527,7 @@ esm 代表 "ECMAScript 模块"，它需要运行环境支持 import 和 export
 
 - 示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'esm',
@@ -541,7 +541,7 @@ cjs 代表 "CommonJS"，它需要运行环境支持 exports、require 和 module
 
 - 示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'cjs',
@@ -555,7 +555,7 @@ iife 代表 "立即调用函数表达式"，它将代码包裹在函数表达式
 
 - 示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'iife',
@@ -569,7 +569,7 @@ umd 代表 "Universal Module Definition"，用于在不同环境（浏览器、N
 
 - 示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'umd',
@@ -595,7 +595,7 @@ type Input =
 
 **数组用法：**
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     input: ['src/index.ts', 'src/index2.ts'],
@@ -609,7 +609,7 @@ export default defineConfig({
 
 **对象的 Key 是产物的文件名称，Value 是源码的文件路径。**
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'esm',
@@ -629,7 +629,7 @@ export default defineConfig({
 
 如果你需要支持 React 16，则可以设置 `jsx` 为 `transform`：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     jsx: 'transform',
@@ -655,7 +655,7 @@ export default defineConfig({
 
 开启 `metafile` 生成：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     buildType: 'bundle',
@@ -673,7 +673,7 @@ export default defineConfig({
 - 类型： `'terser' | 'esbuild' | false | object`
 - 默认值： `false`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     minify: {
@@ -692,7 +692,7 @@ export default defineConfig({
 - 类型： `string`
 - 默认值： `./dist`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     outDir: './dist/esm',
@@ -707,7 +707,7 @@ export default defineConfig({
 - 类型： `'browser' | 'node'`
 - 默认值： `'node'`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     platform: 'browser',
@@ -724,7 +724,7 @@ export default defineConfig({
 
 在某些场景下，你可能不需要这些功能，那么可以通过此配置关闭它，关闭后，其引用路径将不会发生改变。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default {
   buildConfig: {
     redirect: {
@@ -752,7 +752,7 @@ import 'other-package/dist/index.css';
 
 但是这个三方包的 package.json 里并没有将样式文件配置到 `"sideEffects"` 里。
 
-```json other-package/package.json
+```json title="other-package/package.json"
 {
   "sideEffects": ["dist/index.js"]
 }
@@ -766,7 +766,7 @@ import 'other-package/dist/index.css';
 
 这时候就可以使用这个配置项，手动配置模块的`"sideEffects"`，配置支持正则和函数形式。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     sideEffects: [/\.css$/],
@@ -830,7 +830,7 @@ less 相关配置。
 - 类型： `string`
 - 默认值： `undefined`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -851,7 +851,7 @@ export default defineConfig({
 
 设置 `object` 类型时，可以指定 `Less` 的实现库。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -865,7 +865,7 @@ export default defineConfig({
 
 `string` 类型时，指定 `Less` 的实现库的路径
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -895,7 +895,7 @@ Sass 相关配置。
 - 类型： `string | Function`
 - 默认值： `undefined`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -917,7 +917,7 @@ export default defineConfig({
 
 设置为 `object` 类型时，可以指定 `Sass` 的实现库。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -931,7 +931,7 @@ export default defineConfig({
 
 `string` 类型时，指定 `Sass` 的实现库的路径
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -978,7 +978,7 @@ const defaultConfig = {
 
 - 示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -999,7 +999,7 @@ export default defineConfig({
 
 将 `inject` 设置为 `true` 来开启此功能：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     inject: true,
@@ -1011,7 +1011,7 @@ export default defineConfig({
 
 例如，你在源码里写了 `import './index.scss'`，那么在产物中你会看到以下代码：
 
-```js dist/index.js
+```js title="dist/index.js"
 // node_modules/style-inject/dist/style-inject.es.js
 function styleInject(css, ref) {
   // ...
@@ -1060,7 +1060,7 @@ CSS Modules 配置。
 
 一个常用的配置是 `localsConvention`，它可以改变 CSS Modules 的类名生成规则。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -1094,7 +1094,7 @@ Tailwind CSS 相关配置。
 <details>
   <summary>Tailwind CSS 配置详情</summary>
 
-```js modern.config.ts
+```js title="modern.config.ts"
 const tailwind = {
   content: [
     './config/html/**/*.html',
@@ -1144,7 +1144,7 @@ type Target =
 
 例如，将代码编译到 `es5` 语法：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     target: 'es5',
@@ -1163,7 +1163,7 @@ export default defineConfig({
 
 使用示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     transformImport: [
@@ -1188,7 +1188,7 @@ export default defineConfig({
 - 类型： `Record<string, string>`
 - 默认值： `{}`
 
-```ts modern.config.ts
+```ts title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     umdGlobals: {
@@ -1208,7 +1208,7 @@ export default defineConfig({
 - 类型： `string | Function`
 - 默认值： `name => name`
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'umd',
@@ -1228,7 +1228,7 @@ export default defineConfig({
 
 同时函数形式可以接收一个参数，为当前打包文件的输出路径
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'umd',