@modern-js/module-tools-docs 2.0.0-beta.4 → 2.0.2

package/docs/zh/guide/advance/asset.mdx

@@ -1,79 +1,89 @@
+---
+sidebar_position: 7
+---
+
 # 处理静态资源文件
 
-模块工程会对代码中使用的静态资源进行处理。如果需要配置，则可以使用 [`buildConfig.asset`](/zh/api/build-config#asset) API。
+模块工程会对代码中使用的静态资源进行处理。如果需要配置，则可以使用 [`buildConfig.asset`](/api/config/build-config#asset) API。
 
 ## 默认行为
 
 默认情况下，模块工程对于以下静态资源会进行处理：
 
-* `'.svg'`、`'.png'`、`'.jpg'`、`'.jpeg'`、`'.gif'`、`'.webp'`
-* `'.ttf'`、`'.otf'`、`'.woff'`、`'.woff2'`、`'.eot'`
-* `'.mp3'`、`'.mp4'`、`'.webm'`、`'.ogg'`、`'.wav'`、`'.flac'`、`'.aac'`、`'.mov'`
+- `'.svg'`、`'.png'`、`'.jpg'`、`'.jpeg'`、`'.gif'`、`'.webp'`
+- `'.ttf'`、`'.otf'`、`'.woff'`、`'.woff2'`、`'.eot'`
+- `'.mp3'`、`'.mp4'`、`'.webm'`、`'.ogg'`、`'.wav'`、`'.flac'`、`'.aac'`、`'.mov'`
 
 对于静态文件的处理，模块工程目前支持的功能有：
 
-* 设置静态资源路径为 `./assets`。
-* 对于超过 **10kb** 的文件会内联到代码中。
-* 对于 `.svg` 后缀的文件使用 [SVGR](https://react-svgr.com/)。
+- 设置静态资源路径为 `./assets`。
+- 对于超过 **10kb** 的文件会内联到代码中。
+- 对于 `.svg` 后缀的文件使用 [SVGR](https://react-svgr.com/)。
 
 让我们看下面的例子：
 
 <CH.Spotlight>
 
-``` ts ./src/asset.ts
+```ts ./src/asset.ts
 import img from './bg.png';
 //...
 ```
 
 ---
+
 项目源代码。
 
-``` ts ./src/asset.ts
+```ts ./src/asset.ts
 import img from './bg.png';
 //...
 ```
+
 ---
+
 如果 `bg.png` 的大小小于 10 kb，则此时产物目录结构和产物内容为。
 
 <CH.Code>
 
-``` bash
+```bash
 ./dist
 └── asset.js
 ```
+
 ---
 
-``` js ./dist/asset.js
-var bg_default = "data:image/png;base64,";
+```js ./dist/asset.js
+var bg_default = 'data:image/png;base64,';
 console.info(bg_default);
 ```
+
 </CH.Code>
----
 
 如果 `bg.png` 的大小大于 10 kb，则此时产物目录结构和产物内容为。
 
 <CH.Code>
 
-``` bash
+```bash
 ./dist
 ├── asset.js
 └── assets
     └── bg.13e2aba2.png
 ```
+
 ---
 
-``` js ./dist/asset.js
-var bg_default = "assets/bg.13e2aba2.png";
+```js ./dist/asset.js
+var bg_default = 'assets/bg.13e2aba2.png';
 console.info(bg_default);
 ```
+
 </CH.Code>
 
 </CH.Spotlight>
 
 当想要修改默认行为的时候，可以使用以下 API：
 
-* `asset.path`：修改静态资源文件输出路径。
-* `asset.limit`：修改内联静态资源文件的阈值。
+- `asset.path`：修改静态资源文件输出路径。
+- `asset.limit`：修改内联静态资源文件的阈值。
 
 ## 设置 CDN 前缀
 
@@ -83,21 +93,24 @@ console.info(bg_default);
 
 <CH.Spotlight>
 
-``` ts ./src/asset.ts
+```ts ./src/asset.ts
 import img from './bg.png';
 //...
 ```
 
 ---
+
 项目源代码。
 
-``` ts ./src/asset.ts
+```ts ./src/asset.ts
+
 ```
+
 ---
 
 `modern.config` 配置为。
 
-``` ts ./modern.config.ts
+```ts ./modern.config.ts
 export default defineConfig({
   buildConfig: {
     format: 'umd',
@@ -112,16 +125,20 @@ export default defineConfig({
 
 如果 `bg.png` 的大小大于 10 kb，则此时产物内容为。
 
-``` js ./dist/asset.js focus=7:7
-(function(global, factory) {
-    if (typeof module === "object" && typeof module.exports === "object") factory();
-    else if (typeof define === "function" && define.amd) define([], factory);
-    else if (global = typeof globalThis !== "undefined" ? globalThis : global || self) factory();
-})(this, function() {
-    "use strict";
-    var bg_default = "http://cdn/assets/bg.13e2aba2.png";
-    // src/asset.tsx
-    console.info(bg_default);
+```js ./dist/asset.js focus=7:7
+(function (global, factory) {
+  if (typeof module === 'object' && typeof module.exports === 'object')
+    factory();
+  else if (typeof define === 'function' && define.amd) define([], factory);
+  else if (
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
+  )
+    factory();
+})(this, function () {
+  'use strict';
+  var bg_default = 'http://cdn/assets/bg.13e2aba2.png';
+  // src/asset.tsx
+  console.info(bg_default);
 });
 ```
 

package/docs/zh/guide/advance/build-umd.mdx

@@ -1,24 +1,28 @@
+---
+sidebar_position: 5
+---
+
 # 构建 umd 产物
 
 umd 全称为 **Universal Module Definition**，这种格式的 JS 文件可以运行在多个运行环境：
 
-* 浏览器环境：基于 AMD 规范进行模块加载
-* Node.js 环境：基于 CommonJS 进行模块加载
-* 其他情况：将模块挂载在全局对象上。
+- 浏览器环境：基于 AMD 规范进行模块加载
+- Node.js 环境：基于 CommonJS 进行模块加载
+- 其他情况：将模块挂载在全局对象上。
 
 因此我们可以通过下面的方式，将项目的构建产物指定为 umd 产物：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     format: 'umd',
-  }
+  },
 });
 ```
 
 ## umd 产物的第三方依赖处理
 
-在 [【如何处理第三方依赖】](/zh/guide/advance/external-dependency) 章节中，我们知道可以通过 [`autoExternals`](/zh/api/build-config#autoexternal) 和 [`externals`](/zh/api/build-config#externals) API 来控制项目是否对第三方依赖打包。
+在 [【如何处理第三方依赖】](/guide/advance/external-dependency) 章节中，我们知道可以通过 [`autoExternals`](/api/config/build-config#autoexternal) 和 [`externals`](/api/config/build-config#externals) API 来控制项目是否对第三方依赖打包。
 因此在构建 umd 产物的过程中，我们也可以这样使用：
 
 <CH.Spotlight>
@@ -49,13 +53,13 @@ export default defineConfig({
 
 `modern.config.ts` 配置。
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     format: 'umd',
     autoExternal: false,
     externals: ['react'],
-  }
+  },
 });
 ```
 
@@ -63,8 +67,8 @@ export default defineConfig({
 
 当源码中使用了 `react` 依赖。
 
-``` tsx src/index.ts
-import React from "react";
+```tsx src/index.ts
+import React from 'react';
 console.info(React);
 ```
 
@@ -72,26 +76,30 @@ console.info(React);
 
 此时产物中不会将 `react` 代码打包到产物中。
 
-``` js dist/index.js focus=1:7
-(function(global, factory) {
-    if (typeof module === "object" && typeof module.exports === "object") factory(exports, require("react"));
-    else if (typeof define === "function" && define.amd) define([
-        "exports",
-        "react"
-    ], factory);
-    else if (global = typeof globalThis !== "undefined" ? globalThis : global || self) factory(global.index = {}, global.react);
-})(this, function(exports, _react) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", {
-        value: true
-    });
-    _react = /*#__PURE__*/ _interopRequireDefault(_react);
-    function _interopRequireDefault(obj) {
-        return obj && obj.__esModule ? obj : {
-            default: obj
+```js dist/index.js focus=1:7
+(function (global, factory) {
+  if (typeof module === 'object' && typeof module.exports === 'object')
+    factory(exports, require('react'));
+  else if (typeof define === 'function' && define.amd)
+    define(['exports', 'react'], factory);
+  else if (
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
+  )
+    factory((global.index = {}), global.react);
+})(this, function (exports, _react) {
+  'use strict';
+  Object.defineProperty(exports, '__esModule', {
+    value: true,
+  });
+  _react = /*#__PURE__*/ _interopRequireDefault(_react);
+  function _interopRequireDefault(obj) {
+    return obj && obj.__esModule
+      ? obj
+      : {
+          default: obj,
         };
-    }
-    console.info(_react.default);
+  }
+  console.info(_react.default);
 });
 ```
 
@@ -99,14 +107,13 @@ console.info(React);
 
 通过上面的例子我们知道，当使用 `autoExternal` 和 `externals` API 后：
 
-* 在 Node.js 环境下，可以通过 `require('react')` 获取 react 依赖。
-* 在 浏览器环境下，可以通过 `global.react` 获取 react 依赖。
+- 在 Node.js 环境下，可以通过 `require('react')` 获取 react 依赖。
+- 在 浏览器环境下，可以通过 `global.react` 获取 react 依赖。
 
-然而在浏览器环境下，获取第三方依赖的时候，**全局变量名称不一定与依赖名称完全相同**，此时就要使用 [`buildConfig.umdGlobals`](/zh/api/build-config#umdglobals) API。
+然而在浏览器环境下，获取第三方依赖的时候，**全局变量名称不一定与依赖名称完全相同**，此时就要使用 [`buildConfig.umdGlobals`](/api/config/build-config#umdglobals) API。
 
 还是使用之前的例子，当 `react` 依赖以 `windows.React` 或者 `global.React` 全局变量的形式存在于浏览器环境下，那么此时：
 
-
 <CH.Spotlight>
 
 ```json package.json
@@ -133,14 +140,14 @@ console.info(React);
 
 `modern.config.ts` 配置。
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     format: 'umd',
     umdGlobals: {
       react: 'React',
     },
-  }
+  },
 });
 ```
 
@@ -148,8 +155,8 @@ export default defineConfig({
 
 当源码中使用了 `react` 依赖。
 
-``` tsx src/index.ts
-import React from "react";
+```tsx src/index.ts
+import React from 'react';
 console.info(React);
 ```
 
@@ -157,22 +164,26 @@ console.info(React);
 
 此时我们会看到这样的产物代码。
 
-``` js dist/index.js focus=7:12
-(function(global, factory) {
-    if (typeof module === "object" && typeof module.exports === "object") factory();
-    else if (typeof define === "function" && define.amd) define([], factory);
-    else if (global = typeof globalThis !== "undefined" ? globalThis : global || self) factory();
-})(this, function() {
-    // ...
-    // libuild:globals:react
-    var require_react = __commonJS({
-        "libuild:globals:react" (exports, module1) {
-            module1.exports = Function("return this")()["React"];
-        }
-    });
-    // src/index.ts
-    var import_react = __toESM(require_react());
-    console.info(import_react.default);
+```js dist/index.js focus=7:12
+(function (global, factory) {
+  if (typeof module === 'object' && typeof module.exports === 'object')
+    factory();
+  else if (typeof define === 'function' && define.amd) define([], factory);
+  else if (
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
+  )
+    factory();
+})(this, function () {
+  // ...
+  // libuild:globals:react
+  var require_react = __commonJS({
+    'libuild:globals:react'(exports, module1) {
+      module1.exports = Function('return this')()['React'];
+    },
+  });
+  // src/index.ts
+  var import_react = __toESM(require_react());
+  console.info(import_react.default);
 });
 ```
 
@@ -184,49 +195,55 @@ console.info(React);
 
 当我们将下面的代码打包成 umd 产物并运行在浏览器的时候，我们可以通过 `window.index` 来使用该模块。
 
-``` ts ./src/index.ts
+```ts ./src/index.ts
 export default () => {
   console.info('hello world');
-}
+};
 ```
 
 **默认情况下，以源码文件名称作为该模块在浏览器里全局变量的名称**。对于上面的例子，其产物内容如下：
 
-``` js ./dist/index.js focus=6:6
-(function(global, factory) {
-    if (typeof module === "object" && typeof module.exports === "object") factory(exports);
-    else if (typeof define === "function" && define.amd) define([
-        "exports"
-    ], factory);
-    else if (global = typeof globalThis !== "undefined" ? globalThis : global || self) factory(global.index = {});
-})(this, function(exports) {
+```js ./dist/index.js focus=6:6
+(function (global, factory) {
+  if (typeof module === 'object' && typeof module.exports === 'object')
+    factory(exports);
+  else if (typeof define === 'function' && define.amd)
+    define(['exports'], factory);
+  else if (
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
+  )
+    factory((global.index = {}));
+})(this, function (exports) {
   //...
 });
 ```
 
-如果需要修改它，则需要使用 [`buildConfig.umdModuleName`](/zh/api/build-config#umdmodulename) API。
+如果需要修改它，则需要使用 [`buildConfig.umdModuleName`](/api/config/build-config#umdmodulename) API。
 
 当使用该 API 后：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     format: 'umd',
     umdModuleName: 'myLib',
-  }
+  },
 });
 ```
 
 此时构建产物的内容为：
 
-``` js ./dist/index.js focus=6:6
-(function(global, factory) {
-    if (typeof module === "object" && typeof module.exports === "object") factory(exports);
-    else if (typeof define === "function" && define.amd) define([
-        "exports"
-    ], factory);
-    else if (global = typeof globalThis !== "undefined" ? globalThis : global || self) factory(global.myLib = {});
-})(this, function(exports) {
+```js ./dist/index.js focus=6:6
+(function (global, factory) {
+  if (typeof module === 'object' && typeof module.exports === 'object')
+    factory(exports);
+  else if (typeof define === 'function' && define.amd)
+    define(['exports'], factory);
+  else if (
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
+  )
+    factory((global.myLib = {}));
+})(this, function (exports) {
   //...
 });
 ```

package/docs/zh/guide/advance/copy.md

@@ -1,13 +1,17 @@
+---
+sidebar_position: 3
+---
+
 # 使用 Copy 工具
 
 模块工程提供了 Copy 工具用于将已经存在的单个文件或整个目录复制到产物目录中。接下来我们学习如何使用它。
 
 ## 了解 Copy API
 
-我们可以通过 [`buildConfig.copy`](/zh/api/build-config#copy) API 来使用 Copy 工具，它包含以下两个主要配置：
+我们可以通过 [`buildConfig.copy`](/api/config/build-config#copy) API 来使用 Copy 工具，它包含以下两个主要配置：
 
-* [`patterns`](/zh/api/build-config#copypatterns)
-* [`options`](/zh/api/build-config#copyoptions)
+- [`patterns`](/api/config/build-config#copypatterns)
+- [`options`](/api/config/build-config#copyoptions)
 
 在开始学习之前可以先花一些时间了解它们。
 
@@ -17,23 +21,24 @@
 
 其中 `patterns.from` 用于指定要复制的文件或者目录。它接收 Glob 形式字符串或具体路径。Glob 形式字符串是指 [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax)。因此我们可以按照如下两种方式使用它：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     copy: {
       patterns: [
-        { from: './index.html', to: ''},
-        { from: './*.html', to: ''},
-      ]
-    }
-  }
+        { from: './index.html', to: '' },
+        { from: './*.html', to: '' },
+      ],
+    },
+  },
 });
 ```
 
-`patterns.context` 一般和 `patterns.from` 配合使用，默认情况下它的值与 [`buildConfig.sourceDir`](/zh/api/build-config#sourcedir) 相同，因此我们可以按照如下方式指定 `src/data.json` 文件为要复制的文件：
+`patterns.context` 一般和 `patterns.from` 配合使用，默认情况下它的值与 [`buildConfig.sourceDir`](/api/config/build-config#sourcedir) 相同，因此我们可以按照如下方式指定 `src/data.json` 文件为要复制的文件：
+
 > 默认情况下，`buildConfig.sourceDir` 为 `src`
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     copy: {
@@ -65,15 +70,13 @@ export default defineConfig({
 });
 ```
 
-`patterns.to` 用于指定复制文件的输出路径，默认情况下它的值为 [`buildConfig.outdir`](zh/api/build-config#outdir)对应的值。因此我们按照如下方式将 `src/index.html` 复制到 `dist` 目录下：
+`patterns.to` 用于指定复制文件的输出路径，默认情况下它的值为 [`buildConfig.outDir`](/api/config/build-config#outDir)对应的值。因此我们按照如下方式将 `src/index.html` 复制到 `dist` 目录下：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     copy: {
-      patterns: [
-        { from: './index.html', }
-      ],
+      patterns: [{ from: './index.html' }],
     },
   },
 });
@@ -81,22 +84,22 @@ export default defineConfig({
 
 当我们配置了 `patterns.to` 的时候：
 
-* 如果是相对路径，则该路径会相对于 `buildConfig.outdir` 计算出复制文件输出的绝对路径。
-* 如果是绝对路径，则会直接使用该值。
+- 如果是相对路径，则该路径会相对于 `buildConfig.outDir` 计算出复制文件输出的绝对路径。
+- 如果是绝对路径，则会直接使用该值。
 
 最后 `patterns.globOptions` 用于配置寻找复制文件 [globby](https://github.com/sindresorhus/globby) 对象，其配置可参考：
 
-* [globby.options](https://github.com/sindresorhus/globby#options)
+- [globby.options](https://github.com/sindresorhus/globby#options)
 
 ## 不同场景使用示例
 
 ### 将文件复制文件
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: [
     {
-      outdir: 'dist',
+      outDir: 'dist',
       copy: {
         patterns: [
           /**
@@ -110,17 +113,17 @@ export default defineConfig({
         ],
       },
     },
-  ]
+  ],
 });
 ```
 
 ### 将文件复制到目录
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: [
     {
-      outdir: 'dist',
+      outDir: 'dist',
       copy: {
         patterns: [
           /**
@@ -140,11 +143,11 @@ export default defineConfig({
 
 ### 从目录复制到目录
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: [
     {
-      outdir: 'dist',
+      outDir: 'dist',
       copy: {
         patterns: [
           /**
@@ -167,11 +170,11 @@ export default defineConfig({
 
 ### 从目录到文件
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: [
     {
-      outdir: 'dist',
+      outDir: 'dist',
       copy: {
         patterns: [
           /**
@@ -194,11 +197,11 @@ export default defineConfig({
 
 ### 使用 Glob
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: [
     {
-      outdir: 'dist',
+      outDir: 'dist',
       copy: {
         patterns: [
           /**