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

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: {
@@ -945,14 +945,40 @@ export default defineConfig({
 
 ## style.postcss
 
-- plugins
-- processOptions
+用于配置 PostCSS 的选项，传入的值会与默认配置通过 `Object.assign` 合并。注意 `Object.assign` 是浅拷贝，因此会完全覆盖内置的 plugins 数组。
 
-详细配置查看 [PostCSS](https://github.com/postcss/postcss#options)。
+详细配置请查看 [PostCSS](https://github.com/postcss/postcss#options)。
 
-**基础使用：**
+- 类型：
+
+```ts
+type PostcssOptions = {
+  processOptions?: ProcessOptions;
+  plugins?: AcceptedPlugin[];
+};
+```
+
+- 默认值：
 
-```js modern.config.ts
+```ts
+const defaultConfig = {
+  plugins: [
+    // 以下插件默认启用
+    require('postcss-flexbugs-fixes'),
+    require('postcss-media-minmax'),
+    require('postcss-nesting'),
+    // 以下插件仅在 target 为 `es5` 时启用
+    require('postcss-custom-properties'),
+    require('postcss-initial'),
+    require('postcss-page-break'),
+    require('postcss-font-variant'),
+  ],
+};
+```
+
+- 示例：
+
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -973,7 +999,7 @@ export default defineConfig({
 
 将 `inject` 设置为 `true` 来开启此功能：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     inject: true,
@@ -985,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) {
   // ...
@@ -1034,7 +1060,7 @@ CSS Modules 配置。
 
 一个常用的配置是 `localsConvention`，它可以改变 CSS Modules 的类名生成规则。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     style: {
@@ -1068,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',
@@ -1082,6 +1108,7 @@ const tailwind = {
   ],
 };
 ```
+
 </details>
 
 值为 `object` 类型时，与默认配置通过 `Object.assign` 合并。
@@ -1117,7 +1144,7 @@ type Target =
 
 例如，将代码编译到 `es5` 语法：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     target: 'es5',
@@ -1136,7 +1163,7 @@ export default defineConfig({
 
 使用示例：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     transformImport: [
@@ -1161,7 +1188,7 @@ export default defineConfig({
 - 类型： `Record<string, string>`
 - 默认值： `{}`
 
-```ts modern.config.ts
+```ts title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     umdGlobals: {
@@ -1181,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',
@@ -1201,7 +1228,7 @@ export default defineConfig({
 
 同时函数形式可以接收一个参数，为当前打包文件的输出路径
 
-```js modern.config.ts
+```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
     format: 'umd',

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

@@ -13,7 +13,7 @@ sidebar_position: 2
 
 字符串的形式可以让你直接使用内置的预设。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -34,7 +34,7 @@ export default defineConfig({
 
 :::
 
-```json package.json
+```json title="package.json"
 {
   "main": "./dist/lib/index.js",
   "module": "./dist/es/index.js",
@@ -72,7 +72,7 @@ export const buildConfig = [
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用，并且 Library 支持类似 [unpkg](https://unpkg.com/) 的模式。在预设 `'npm-library'` 的基础上，额外提供 `umd` 产物。
 
-```json package.json
+```json title="package.json"
 {
     "main": "./dist/lib/index.js",
     "module": "./dist/es/index.js",
@@ -120,7 +120,7 @@ export const buildConfig = [
 
 对于源码中包含的样式文件，产物中提供样式的编译产物和样式的源文件。
 
-```json package.json
+```json title="package.json"
 {
     "main": "./dist/lib/index.js", // bundleless type
     "module": "./dist/es/index.js", // bundleless type
@@ -158,7 +158,7 @@ export const buildConfig = [
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用的组件（库），同时支持类 [unpkg](https://unpkg.com/) 的模式。 在预设 `'npm-component'` 的基础上，额外提供 `umd` 产物。
 
-```json package.json
+```json title="package.json"
 {
     "main": "./dist/lib/index.js", // bundleless type
     "module": "./dist/es/index.js", // bundleless type
@@ -204,7 +204,7 @@ export const buildConfig = [
 
 例如希望 `'npm-library'` 预设支持 `'es2017'`，则可以按照如下方式配置：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -217,7 +217,7 @@ export default defineConfig({
 函数的配置方式，可以通过 `preset` 参数获取到预设值，然后对里面的构建配置进行修改来自定义你的构建配置。
 以下是一个函数的配置方式的例子，它配置了压缩构建产物的功能：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -248,10 +248,9 @@ export default defineConfig({
 
 包含了所有可用的构建预设对应的构建配置。可以通过 `buildPreset` 所支持的字符串来使用构建配置，也可以使用这些字符串的下划线命令的方式。下面是两种方式的使用示例：
 
+- 使用 `buildPreset` 所支持的字符串。
 
-<CH.Spotlight>
-
-```ts modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -260,25 +259,10 @@ export default defineConfig({
   },
 });
 ```
----
 
-使用 `buildPreset` 所支持的字符串。
+- 使用 `buildPreset` 所支持的字符串的下划线命名方式。
 
-```ts modern.config.ts
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset({ preset }) {
-    return preset['npm-library'];
-  },
-});
-```
-
----
-
-使用 `buildPreset` 所支持的字符串的下划线命名方式。
-
-```ts modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -288,8 +272,6 @@ export default defineConfig({
 });
 ```
 
-</CH.Spotlight>
-
 #### `extendPreset`
 
 类型：`Function`
@@ -300,7 +282,7 @@ export default defineConfig({
 
 例如在 `'npm-library'` 构建预设的基础上增加 `define` 配置：
 
-```ts modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({

package/docs/zh/api/config/design-system.md

@@ -969,7 +969,7 @@ const designSystem = {
 
 要覆盖默认配置中的选项，请在 `designSystem` 中添加要覆盖的属性：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -999,7 +999,7 @@ export default defineConfig({
 
 例如，如果您想添加一个额外的断点但保留现有的断点，则可以扩展 `screens` 属性：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -1018,7 +1018,7 @@ export default defineConfig({
 
 您当然可以覆盖默认主题的某些部分，并在同一配置中扩展默认主题的其他部分：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -1048,7 +1048,7 @@ export default defineConfig({
 
 例如，您可以在 `fill` 配置上通过引用 `theme('colors')` 为调色板中的每种颜色生成 `fill` utilities。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {
@@ -1069,7 +1069,7 @@ export default defineConfig({
 
 如果出于任何原因想要引用默认配置中的值，则可以从 `tailwindcss/defaultTheme` 导入它。一个有用的示例是，如果要将添加默认配置提供的字体中某一个字体：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const defaultTheme = require('tailwindcss/defaultTheme');
@@ -1134,7 +1134,7 @@ const designSystem = {
 
 另一个示例是在自定义插件中添加新的属性以进行引用。例如，如果您为项目编写了渐变插件，则可以向该插件引用的主题对象添加渐变属性：
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 const designSystem = {

package/docs/zh/api/config/plugins.md

@@ -25,7 +25,7 @@ sidebar_position: 4
 
 使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myPlugin } from 'my-plugin';
 
 export default defineConfig({
@@ -37,7 +37,7 @@ export default defineConfig({
 
 使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myPlugin } from './plugins/myPlugin';
 
 export default defineConfig({
@@ -49,7 +49,7 @@ export default defineConfig({
 
 如果插件提供了一些自定义的配置项，你可以通过插件函数的参数传入配置。
 
-```js modern.config.ts
+```js title="modern.config.ts"
 import { myPlugin } from 'my-plugin';
 
 export default defineConfig({