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

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

@@ -0,0 +1,235 @@
+# 使用 Copy 工具
+
+模块工程提供了 Copy 工具用于将已经存在的单个文件或整个目录复制到产物目录中。接下来我们学习如何使用它。
+
+## 了解 Copy API
+
+我们可以通过 [`buildConfig.copy`](/zh/api/build-config#copy) API 来使用 Copy 工具，它包含以下两个主要配置：
+
+* [`patterns`](/zh/api/build-config#copypatterns)
+* [`options`](/zh/api/build-config#copyoptions)
+
+在开始学习之前可以先花一些时间了解它们。
+
+## API 详解
+
+`copy.patterns` 用于寻找复制的文件以及配置输出的路径。
+
+其中 `patterns.from` 用于指定要复制的文件或者目录。它接收 Glob 形式字符串或具体路径。Glob 形式字符串是指 [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax)。因此我们可以按照如下两种方式使用它：
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    copy: {
+      patterns: [
+        { from: './index.html', to: ''},
+        { from: './*.html', to: ''},
+      ]
+    }
+  }
+});
+```
+
+`patterns.context` 一般和 `patterns.from` 配合使用，默认情况下它的值与 [`buildConfig.sourceDir`](/zh/api/build-config#sourcedir) 相同，因此我们可以按照如下方式指定 `src/data.json` 文件为要复制的文件：
+> 默认情况下，`buildConfig.sourceDir` 为 `src`
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    copy: {
+      patterns: [
+        { from: './data.json' to: ''},
+      ],
+    },
+  },
+});
+```
+
+当指定的文件不在源码目录的时候，可以修改 `context` 配置。例如指定项目目录下的 `temp/index.html` 为要复制的文件：
+
+```ts
+import path from 'path';
+
+export default defineConfig({
+  buildConfig: {
+    copy: {
+      patterns: [
+        {
+          from: './index.html',
+          context: path.join(__dirname, './temp')
+          to: '',
+        }
+      ],
+    },
+  },
+});
+```
+
+`patterns.to` 用于指定复制文件的输出路径，默认情况下它的值为 [`buildConfig.outdir`](zh/api/build-config#outdir)对应的值。因此我们按照如下方式将 `src/index.html` 复制到 `dist` 目录下：
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    copy: {
+      patterns: [
+        { from: './index.html', }
+      ],
+    },
+  },
+});
+```
+
+当我们配置了 `patterns.to` 的时候：
+
+* 如果是相对路径，则该路径会相对于 `buildConfig.outdir` 计算出复制文件输出的绝对路径。
+* 如果是绝对路径，则会直接使用该值。
+
+最后 `patterns.globOptions` 用于配置寻找复制文件 [globby](https://github.com/sindresorhus/globby) 对象，其配置可参考：
+
+* [globby.options](https://github.com/sindresorhus/globby#options)
+
+## 不同场景使用示例
+
+### 将文件复制文件
+
+``` ts
+export default defineConfig({
+  buildConfig: [
+    {
+      outdir: 'dist',
+      copy: {
+        patterns: [
+          /**
+           * copy file to file
+           */
+          {
+            from: './temp-1/a.png',
+            context: __dirname,
+            to: './temp-1/b.png',
+          },
+        ],
+      },
+    },
+  ]
+});
+```
+
+### 将文件复制到目录
+
+``` ts
+export default defineConfig({
+  buildConfig: [
+    {
+      outdir: 'dist',
+      copy: {
+        patterns: [
+          /**
+           * copy file to dir
+           */
+          {
+            from: './temp-2/a.png',
+            context: __dirname,
+            to: './temp-2',
+          },
+        ],
+      },
+    },
+  ],
+});
+```
+
+### 从目录复制到目录
+
+``` ts
+export default defineConfig({
+  buildConfig: [
+    {
+      outdir: 'dist',
+      copy: {
+        patterns: [
+          /**
+           * copy dir to dir
+           */
+          {
+            from: './temp-3/',
+            to: './temp-3',
+            context: __dirname,
+          },
+        ],
+        options: {
+          enableCopySync: true,
+        },
+      },
+    },
+  ],
+});
+```
+
+### 从目录到文件
+
+``` ts
+export default defineConfig({
+  buildConfig: [
+    {
+      outdir: 'dist',
+      copy: {
+        patterns: [
+          /**
+           * copy dir to file
+           */
+          {
+            from: './temp-4/',
+            context: __dirname,
+            to: './temp-4/_index.html',
+          },
+        ],
+        options: {
+          enableCopySync: true,
+        },
+      },
+    },
+  ],
+});
+```
+
+### 使用 Glob
+
+``` ts
+export default defineConfig({
+  buildConfig: [
+    {
+      outdir: 'dist',
+      copy: {
+        patterns: [
+          /**
+           * copy glob to dir
+           */
+          {
+            from: './*.html',
+            to: './temp-5',
+          },
+        ],
+        options: {
+          enableCopySync: true,
+        },
+      },
+    },
+    {
+      copy: {
+        patterns: [
+          /**
+           * copy glob to file
+           */
+          {
+            from: './*.html',
+            to: './temp-6/index.html',
+          },
+        ],
+        options: {
+          enableCopySync: true,
+        },
+      },
+    },
+  ],
+});
+```

package/docs/zh/guide/advance/external-dependency.mdx

@@ -0,0 +1,125 @@
+# 如何处理第三方依赖
+
+一般来说，项目所需要的第三方依赖可以通过包管理器的 `install` 命令安装，在安装第三方依赖成功后，这些第三方依赖一般会出现在项目 `package.json` 的 `dependencies` 和 `devDependencies` 下。
+
+``` json pacakge.json
+{
+    "dependencies": {},
+    "devDependencies": {}
+}
+```
+
+而 `"dependencies"` 下的依赖通常来说是和项目代码以及构建相关的，如果这些第三方依赖声明在 `"devDependencies"` 下，那么在生产环境下就会出现缺失依赖的问题。
+
+除了 `"dependencies"` 以外，[`"peerDependencies"`](/zh/guide/basic/before-getting-started#peerdependencies) 也可以声明在生产环境下需要的依赖，不过它更强调项目在运行环境下存在 `"peerDependencies"` 声明的这些依赖，这类似于插件这样的机制。
+
+## 第三方依赖的默认处理
+
+在模块工程里，**默认情况下不会对`"dependencies"` 以及 `"peerDependencies"` 下的第三方依赖进行打包处理**，因此：
+
+<CH.Spotlight>
+
+```json ./v1/package.json
+{
+    "dependencies": {
+        "react": "^17"
+    },
+    // or
+    "peerDependencies": {
+        "react": "^17"
+    }
+}
+```
+
+---
+
+如果项目依赖了 `react`。
+
+```json ./v1/package.json
+{
+  "dependencies": {
+    "react": "^17"
+  },
+  // or
+  "peerDependencies": {
+      "react": "^17"
+  }
+}
+```
+
+---
+
+当源码中使用了 `react` 依赖。
+
+``` tsx src/index.ts
+import React from "react";
+console.info(React);
+```
+
+---
+
+此时产物中不会将 `react` 代码打包到产物中。
+
+``` js dist/index.js
+import React from "react";
+console.info(React);
+```
+
+</CH.Spotlight>
+
+## 打包第三方依赖
+
+不过也有一些情况希望将这些第三方依赖打包到产物。将第三方依赖打包到产物的好处是：**减少下载第三方依赖所花费的时间**。
+
+这种处理第三方依赖的方式一般在开发命令行工具中比较常见，这可以提升命令行工具的加载速度，给使用者带来更好的使用体验。
+
+那么如何在模块工程中开启对于第三方依赖的打包处理呢？
+
+在构建配置中提供了以下 API 来处理第三方依赖：
+
+* [`buildConfig.autoExternal`](/zh/api/build-config#autoexternal)
+* [`buildConfig.externals`](/zh/api/build-config#externals)
+
+### 关闭默认行为
+
+当我们希望关闭对于第三方依赖的默认处理行为时候，可以通过以下方式来实现：
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    autoExternal: false,
+  }
+});
+```
+
+这样对于 `"dependencies"` 和 `"peerDependencies"` 下面的依赖都会进行打包处理。如果只想要关闭其中某个下面的依赖处理，则可以使用
+`buildConfig.autoExternal` 的对象形式：
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    autoExternal: {
+      dependencies: false,
+      peerDependencies: false,
+    },
+  }
+});
+```
+
+### 排除指定第三方依赖
+
+而除了 `buildConfig.autoExternal` API以外，`buildConfig.externals` 也可以控制哪些第三方依赖要进行处理。我们可以组合这两个
+API 对项目的依赖进行更细微的处理。
+
+例如当我们需要仅对某些依赖不进行打包处理的时候，可以按照如下方式进行配置：
+
+> 一般这种情况，可能是某些依赖不适合进行打包处理。如果遇到这种情况，则可以按照下面的方式进行处理。
+
+``` ts
+epxort default defineConfig({
+  buildConfig: {
+    autoExternal: false,
+    externals: ['pkg-1', /pkg-2/],
+  }
+});
+```

package/docs/zh/guide/advance/in-depth-about-build.md

@@ -0,0 +1,267 @@
+# 深入理解构建
+
+在【基础使用】的部分，我们已经知道可以通过 `buildConfig` 配置对项目的输出产物进行修改。`buildConfig` 不仅描述了产物的一些特性，同时还为构建产物提供了一些功能。
+
+:::tip{title=注意}
+如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
+
+* 【[修改输出产物](/zh/guide/modify-output-product)】
+:::
+
+而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
+
+## 深入理解 `buildConfig`
+
+### Bundle 和 Bundleless
+
+那么首先我们来了解一下 Bundle 和 Bundleless。
+
+所谓 Bundle 是指对构建产物进行打包，构建产物可能是一个文件，也有可能是基于一定的[代码拆分策略](https://esbuild.github.io/api/#splitting)得到的多个文件。
+
+而 Bundleless 则是指对每个源文件单独进行编译构建，但是并不将它们打包在一起。每一个产物文件都可以找到与之相对应的源码文件。**Bundleless 构建的过程，也可以理解为仅对源文件进行代码转换的过程**。
+
+在 `buildConfig` 中可以通过 [`buildConfig.buildType`](/zh/api/build-config#buildtype) 来指定当前构建任务是 Bundle 还是 Bundleless。
+
+### `input` 与 `sourceDir` 的关系
+
+[`buildConfig.input`](/zh/api/build-config#input) 用于指定读取源码的文件路径或者目录路径，其默认值在 Bundle 和 Bundleless 构建过程中有所不同：
+
+* 当 `buildType: 'bundle'` 的时候，`input` 默认值为 `['src/index.ts']`
+* 当 `buildType: 'bundleless'` 的时候，`input` 默认值为 `['src']`
+> 实际上，在 `buildType: 'bundle'` 的时候，构建工具会检测是否存在符合 `src/index.(j|t)sx?` 这个名称规则的文件，并将其作为入口文件。
+
+:::warn{title=注意}
+建议不要在 Bundleless 构建过程中指定多个源码文件目录，可能出现不符合预期的结果。目前多个源码目录的 Bundleless 构建还处于不稳定阶段。
+:::
+
+从默认值上我们可以知道：**Bundle 构建一般可以指定文件路径作为构建的入口，而 Bundleless 构建则更期望使用目录路径寻找源文件**。
+
+#### `input` 的对象模式
+
+在 Bundle 构建过程中，除了将 `input` 设置为一个数组，也可以将它设置为一个对象。**通过使用对象的形式，我们可以修改构建产物输出的文件名称**。那么对于下面的例子，`./src/index.ts` 对应的构建产物文件路径为 `./dist/main.js`。
+
+``` tsx modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+    buildConfig: {
+        input: {
+            main: ['./src/index.ts'],
+        },
+        outdir: './dist',
+    },
+});
+```
+
+而在 Bundleless 构建过程中，虽然同样支持这样的使用方式，但是并不推荐。
+
+#### `sourceDir`
+
+[`sourceDir`](/zh/api/build-config#sourcedir) 用于指定源码目录，它主要与以下两个内容有关系：
+
+* 类型文件生成
+* 指定构建过程中的 [`outbase`](https://esbuild.github.io/api/#outbase)
+
+一般来说：
+
+* **在 Bundleless 构建过程中，`sourceDir` 与 `input` 的值要保持一致，它们的默认值都是 `src`**。
+* 在 Bundle 构建过程中，很少需要使用 `sourceDir`。
+
+### 类型文件
+
+[`buildConfig.dts`](/zh/api/build-config#dts) 配置主要用于类型文件的生成。
+
+#### 关闭类型生成
+
+默认情况下类型生成功能是开启的，如果需要关闭的话，可以按照如下配置：
+
+```ts ./modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildConfig: {
+    dts: false
+  }
+});
+```
+
+:::tip
+关闭类型文件后，一般来说构建速度会有所提升。
+:::
+
+#### 打包类型文件
+
+在 `buildType: 'bundleless'` 的时候，类型文件的生成是使用项目的 `tsc` 命令来完成生产。
+
+**模块工程解决方案同时还支持对类型文件进行打包**，不过使用该功能的时候需要注意：
+
+* 一些第三方依赖存在错误的语法会导致打包过程失败。因此对于这种情况，需要手动通过 [`buildConfig.externals`](/zh/api/build-config#externals) 将这类第三方包排除。
+* 对于第三方依赖的类型文件指向的是一个 `.ts` 文件的情况，目前无法处理。比如第三方依赖的 `package.json` 中存在这样的内容： `{"types": "./src/index.ts"}`。
+
+#### 别名转换
+
+在 Bundleless 构建过程中，如果源代码中出现了别名，例如：
+
+```ts ./src/index.ts
+import utils from '@common/utils';
+```
+
+正常来说，使用 `tsc` 生成的产物类型文件也会包含这些别名。不过 Module Tools 会对 `tsc` 生成的类型文件里的别名进行转换处理：
+
+* 对于类似 `import '@common/utils'` 或者 `import utils from '@common/utils'` 这样形式的代码可以进行别名转换。
+* 对于类似 `export { utils } from '@common/utils'` 这样形式的代码可以进行别名转换。
+
+然而也存在一些情况，目前还无法处理：
+
+* 对于类似 `Promise<import('@common/utils')>` 这样形式的输出类型目前无法进行转换。
+
+#### 一些 `dts` 的使用示例
+
+一般使用方式：
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  // 此时打包的类型文件输出路径为 `./dist/types`
+  buildConfig: {
+    buildType: 'bundle',
+    dts: {
+      tsconfigPath: './other-tsconfig.json',
+      distPath: './types',
+    },
+    outdir: './dist',
+  }
+});
+```
+
+使用 `dts.only` 的情况：
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  // 此时类型文件没有进行打包，输出路径为 `./dist/types`
+  buildConfig: [
+    {
+      buildType: 'bundle',
+      dts: false,
+      outdir: './dist',
+    },
+    {
+      buildType: 'bundleless',
+      dts: {
+        only: true,
+      },
+      outdir: './dist/types',
+    }
+  ]
+});
+```
+
+### `buildConfig.define` 不同场景的使用方式
+
+[`buildConfig.define`](/zh/api/build-config#define) 功能有些类似 [`webpack.DefinePlugin`](https://webpack.js.org/plugins/define-plugin/)。这里介绍几个使用场景：
+
+#### 环境变量替换
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  buildConfig: {
+    define: {
+      'process.env.VERSION': JSON.stringify(process.env.VERSION || '0.0.0')
+    }
+  }
+});
+```
+
+通过上面的配置，我们就可以将下面这段代码：
+
+```
+// 编译前代码
+console.log(process.env.VERSION);
+```
+
+在执行 `VERSION=1.0.0 modern build` 的时候，转换为：
+
+```
+// 编译后代码
+console.log('1.0.0');
+```
+
+#### 全局变量替换
+
+``` ts
+import { defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  buildConfig: {
+    define: {
+      'VERSION': JSON.stringify(require('./package.json').version || '0.0.0')
+    }
+  }
+});
+```
+
+通过上面的配置，我们就可以将下面这段代码：
+
+```
+// 编译前代码
+console.log(VERSION);
+```
+
+转换为：
+
+```
+// 编译后代码
+console.log('1.0.0');
+```
+
+不过要注意：如果项目是一个 TypeScript 项目，那么你可能需要在项目源代码目录下的 `.d.ts` 文件里增加以下内容：
+> 如果不存在 `d.ts` 文件，则可以手动创建。
+
+``` ts env.d.ts
+declare const YOUR_ADD_GLOBAL_VAR;
+```
+
+
+## 构建过程
+
+当执行 `modern build` 命令的时候，会发生
+
+* 根据 `buildConfig.outdir` 清理产物目录。
+* 编译 `js/ts` 源代码生成 Bundle/Bundleless 的 JS 构建产物。
+* 使用 `tsc` 生成 Bundle/Bundleless 的类型文件。
+* 处理 Copy 任务。
+
+## 构建报错
+
+当发生构建报错的时候，基于以上了解到的信息，可以很容易的明白在终端出现的报错内容：
+
+**js 或者 ts 构建的报错：**
+``` bash
+error  ModuleBuildError:
+
+╭───────────────────────╮
+│ bundle failed:        │
+│  - format is "cjs"    │
+│  - target is "esnext" │
+╰───────────────────────╯
+
+Detailed Information:
+```
+
+**类型文件生成过程的报错：**
+
+``` bash
+error   ModuleBuildError:
+
+bundle DTS failed:
+```
+
+对于 `js/ts` 构建错误，我们可以从报错信息中知道：
+
+* 通过 `'bundle failed:'` 来判断报错的是 Bundle 构建还是 Bundleless 构建？
+* 构建过程的 `format` 是什么？
+* 构建过程的 `target` 是什么？
+* 具体的报错信息。

package/docs/zh/guide/advance/in-depth-about-dev-command.md

@@ -0,0 +1,26 @@
+# 深入理解构建
+
+在【基础使用】的部分，我们已经知道可以通过 `buildConfig` 配置对项目的输出产物进行修改。`buildConfig` 不仅描述了产物的一些特性，同时还为构建产物提供了一些功能。
+
+:::tip{title=注意}
+如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
+
+* 【[修改输出产物](/zh/guide/modify-output-product)】
+:::
+
+而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
+
+## 深入理解 `buildConfig`
+
+### Bundle 和 Bundleless
+
+那么首先我们来理解一下 Bundle 和 Bundleless。
+
+所谓 Bundle 是指对构建产物进行打包，构建产物可能是一个文件，也有可能是基于一定的[代码拆分策略](https://esbuild.github.io/api/#splitting)得到的多个文件。
+
+而 Bundleless 则是指对每个源文件进行编译构建，但是并不将它们打包在一起。每一个产物文件都可以找到与之相对应的源码文件。
+
+### input 与 sourceDir 的关系
+
+## 构建过程
+