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

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

@@ -0,0 +1,132 @@
+# Handle static resource files
+
+The module project will handle static resources used in the code. If configuration is required, then the [`buildConfig.asset`](/en/api/build-config#asset) API can be used.
+
+## Default behavior
+
+By default, module projects are processed for the following static resources:
+
+* `'.svg'`、`'.png'`、`'.jpg'`、`'.jpeg'`、`'.gif'`、`'.webp'`
+* `'.ttf'`、`'.otf'`、`'.woff'`、`'.woff2'`、`'.eot'`
+* `'.mp3'`、`'.mp4'`、`'.webm'`、`'.ogg'`、`'.wav'`、`'.flac'`、`'.aac'`、`'.mov'`
+
+For the handling of static files, the module project currently supports the following functions.
+
+* Set the static resource path to `. /assets`.
+* For files over **10kb** they are inlined into the code.
+* Use [SVGR](https://react-svgr.com/) for files with the `.svg` suffix.
+
+Let us look at the following example:
+
+<CH.Spotlight>
+
+``` ts ./src/asset.ts
+import img from './bg.png';
+//...
+```
+
+---
+Project source code.
+
+``` ts ./src/asset.ts
+import img from './bg.png';
+//...
+```
+---
+If the size of `bg.png` is less than 10 kb, then the product directory structure and product content are.
+
+<CH.Code>
+
+``` bash
+./dist
+└── asset.js
+```
+---
+
+``` js ./dist/asset.js
+var bg_default = "data:image/png;base64,";
+console.info(bg_default);
+```
+</CH.Code>
+---
+
+If the size of `bg.png` is larger than 10 kb, then the product directory structure and product content are.
+
+<CH.Code>
+
+``` bash
+./dist
+├── asset.js
+└── assets
+    └── bg.13e2aba2.png
+```
+---
+
+``` js ./dist/asset.js
+var bg_default = "assets/bg.13e2aba2.png";
+console.info(bg_default);
+```
+</CH.Code>
+
+</CH.Spotlight>
+
+When wanting to modify the default behavior, the following API can be used:
+
+* `asset.path`: modify the output path of the static resource file.
+* `asset.limit`: modify the threshold value for inline static resource files.
+
+## Setting CDN Prefix
+
+If the project is running in a browser environment, we may need to host static resources to a CDN and then use them in the production environment.
+
+Then we need to add the CDN base path in front of the path to the static resource file in the default generated build product. Again, see an example:
+
+<CH.Spotlight>
+
+``` ts ./src/asset.ts
+import img from './bg.png';
+//...
+```
+
+---
+Project source code.
+
+``` ts ./src/asset.ts
+```
+---
+
+`modern.config` config file。
+
+``` ts ./modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    asset: {
+      publicPath: 'https://cdn/',
+    },
+  },
+});
+```
+
+---
+
+If the size of `bg.png` is larger than 10 kb, then the product content will be.
+
+``` 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);
+});
+```
+
+</CH.Spotlight>
+
+## SVGR
+
+WIP

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

@@ -0,0 +1,241 @@
+# Build umd products
+
+The full name of umd is **Universal Module Definition**, and JS files in this format can run in multiple runtime environments: the
+
+* Browser environment: module loading based on AMD specification
+* Node.js environment: module loading based on CommonJS
+* Other cases: mount the module on a global object.
+
+We can therefore specify the build product of the project as an umd product in the following way:
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+  }
+});
+```
+
+## Third-party dependency handling for umd products
+
+In the [[How to handle third-party dependencies]](/en/guide/advance/external-dependency) chapter, we know that we can control whether or not the project packages third-party dependencies via the [`autoExternals`](/en/api/build-config#autoexternal) and [`externals`](/en/api/build-config#externals) APIs.
+So when building umd products, we can also use it like this:
+
+<CH.Spotlight>
+
+```json package.json
+{
+  "dependencies": {
+    "react": "^17"
+    //...other dependencies
+  }
+}
+```
+
+---
+
+If the project depends on `react`.
+
+```json package.json
+{
+  "dependencies": {
+    "react": "^17"
+    //...other dependencies
+  }
+}
+```
+
+---
+
+`modern.config.ts`.
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    autoExternal: false,
+    externals: ['react'],
+  }
+});
+```
+
+---
+
+When a `react` dependency is used in the source code.
+
+``` tsx src/index.ts
+import React from "react";
+console.info(React);
+```
+
+---
+
+The `react` code is not packaged into the product at this point.
+
+``` 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);
+});
+```
+
+</CH.Spotlight>
+
+We know from the above example that when using the `autoExternal` and `externals` APIs.
+
+* In a Node.js environment, you can get the react dependency with `require('react')`.
+* In a browser environment, you can get the react dependency via `global.react`.
+
+However, in the browser environment, when getting third-party dependencies, **global variable names are not necessarily identical to the dependency names**, so you have to use the [`buildConfig.umdGlobals`](/en/api/build-config#umdglobals) API.
+
+Again using the previous example, when the `react` dependency exists in the browser environment as a `windows.React` or `global.React` global variable, then:
+
+
+<CH.Spotlight>
+
+```json package.json
+{
+  "devDependencies": {
+    "react": "^17"
+  }
+}
+```
+
+---
+
+If the project depends on `react`.
+
+```json package.json
+{
+  "devDependencies": {
+    "react": "^17"
+  }
+}
+```
+
+---
+
+`modern.config.ts` config file。
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    umdGlobals: {
+      react: 'React',
+    },
+  }
+});
+```
+
+---
+
+When a `react` dependency is used in the source code.
+
+``` tsx src/index.ts
+import React from "react";
+console.info(React);
+```
+
+---
+
+At this point we will see the product code like this.
+
+``` 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);
+});
+```
+
+</CH.Spotlight>
+
+The project can then run in the browser and use the `React` variables that exist on the global object.
+
+
+## Changing the name of a global variable in a project
+
+When we package the following code into an umd product and run it in the browser, we can use the module via `window.index`.
+
+``` ts ./src/index.ts
+export default () => {
+  console.info('hello world');
+}
+```
+
+** By default, the name of the source file is used as the name of the module's global variable in the browser. **For the above example, the product would read as follows:
+
+``` 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) {
+  //...
+});
+```
+
+If you need to modify it, you need to use the [`buildConfig.umdModuleName`](/en/api/build-config#umdmodulename) API.
+
+When this API is used:
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    umdModuleName: 'myLib',
+  }
+});
+```
+
+The construction products at this point are:
+
+``` 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/en/guide/advance/copy.md

@@ -0,0 +1,235 @@
+# Use the Copy Tools
+
+The Module Project provides the Copy utility for copying already existing individual files or entire directories into the product directory. Next we learn how to use it.
+
+## Understanding the Copy API
+
+We can use the Copy tool via the [`buildConfig.copy`](/en/api/build-config#copy) API, which contains the following two main configurations.
+
+* [`patterns`](/en/api/build-config#copypatterns)
+* [`options`](/en/api/build-config#copyoptions)
+
+It is recommended to spend some time getting to know them before you start learning.
+
+## API Description
+
+`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,
+        },
+      },
+    },
+  ],
+});
+```