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

package/docs/zh/api/dev.md

@@ -0,0 +1,33 @@
+# Dev
+本章描述了调试相关的配置
+## storybook
+
+Storybook 配置请查看：[Storybook 配置](https://storybook.js.org/docs/react/configure/overview)
+
+:::info
+使用 Storybook 进行调试需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式功能。
+:::
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  dev: {
+    storybook: {
+      addons: ['@storybook/addon-essentials'],
+      babel: async (options) => ({
+        // Update your babel configuration here
+        ...options,
+      }),
+      framework: '@storybook/react',
+      stories: ['../src/**/*.stories.@(js|mdx)'],
+      webpackFinal: async (config, { configType }) => {
+        // Make whatever fine-grained changes you need
+        // Return the altered config
+        return config;
+      },
+    }
+  }
+});
+
+```

package/docs/zh/api/index.md

@@ -0,0 +1,3 @@
+---
+pageType: 'api'
+---

package/docs/zh/api/plugins.md

@@ -0,0 +1,108 @@
+# Plugins
+本章介绍插件相关的 API，包括插件的基本用法，插件的钩子，插件的配置等。
+
+Modern.js的插件系统借鉴了[follow-pipeline](https://github.com/farrow-js/farrow/tree/master/packages/farrow-pipeline)，你可以通过hooks介入到各个流程中。
+
+## Basic Usage
+
+- type: `CliPlugin<ModuleToolsHooks>[]`
+- default: `[]`
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+import myPlugin from '.';
+
+export default defineConfig({
+  plugins: [myPlugin()]
+});
+```
+
+一个插件的基本结构如下：
+```ts myPlugin.ts
+export default (): CliPlugin<ModuleToolsHooks> => {
+  return {
+    name: 'dev-plugin-example',
+    setup: () => {
+      return {
+        registerDev() {
+          return {
+            name: 'plugin-example',
+            menuItem: {
+              name: 'dev-example',
+              value: 'dev-example',
+            },
+            action() {
+              console.info('running dev-example');
+            },
+          };
+        },
+      };
+    },
+  };
+};
+```
+
+
+## Hooks
+
+### Types
+Module tools主要使用到了两种类型的钩子，分别是 `ParallelWorkflow` 和 `AsyncPipeline` 。
+- `ParallelWorkflow` 是一个并行的钩子，可以同时执行多个钩子，但是不会等待钩子执行完毕，而是立即返回。
+- `AsyncPipeline` 是一个串行的钩子，会等待上一个钩子执行完毕后再执行下一个钩子。
+创建钩子时，需要指定钩子的输入和输出类型，例如 `createParallelWorkflow<void, void>` ，表明这个钩子没有输入，也没有输出。
+
+### Dev Hooks
+
+#### registerDev
+- type: `ParallelWorkflow<void, DevToolData>`
+- 注册dev任务,storybook 就是通过这个hooks注册的
+
+#### beforeDev
+- type: `ParallelWorkflow<DevToolData[], void>`
+- 在dev任务执行之前执行
+
+#### afterDev
+- type: `ParallelWorkflow<void, void>`
+- 在dev任务执行之后执行
+
+#### beforeDevMenu
+- type: `ParallelWorkflow<QuestionCollection, QuestionCollection | void>`
+- 在选择dev任务菜单执行之前执行
+
+#### afterDevMenu
+- type: `ParallelWorkflow<{ result: PromptResult; devTools: DevToolData[] }, void>`
+- 在选择dev任务菜单执行之后执行
+
+#### beforeDevTask
+- type: `ParallelWorkflow<DevToolData, void>`
+- 在执行每一项dev任务前执行
+
+### BuildHooks
+
+#### beforeBuild
+- type: `ParallelWorkflow<{ config: BuildConfig; options: BuildCommandOptions }, BuildConfig>`
+- 在所有的构建任务执行之前执行
+
+#### afterBuild
+- type: `ParallelWorkflow<BuildResult, void>`
+- 在所有的构建任务执行完后执行
+
+#### beforeBuildTask
+- type: `ParallelWorkflow<{ config: BaseBuildConfig; options: BuildCommandOptions }, BaseBuildConfig>`
+- 在每一项构建任务执行之前执行,
+
+#### afterBuildTask
+- type: `ParallelWorkflow<BuildTaskResult, void>`
+- 在每一项构建任务执行完后执行
+
+#### registerBuildPlatform
+- type: `ParallelWorkflow<void, RegisterBuildPlatformResult>`
+- 注册构建平台, storybook 的构建就是通过这个hooks注册的
+
+#### beforeBuildPlatform
+- type: `ParallelWorkflow<RegisterBuildPlatformResult[], void>`
+- 在构建平台之前执行
+
+#### afterBuildPlatform
+- type: `ParallelWorkflow<void, BuildPlatformResult>`
+- 在构建平台完后执行

package/docs/zh/api/testing.md

@@ -0,0 +1,52 @@
+# Testing
+本章描述了测试相关的配置
+:::tips
+需要先通过 `pnpm run new` 启用 单元测试 功能。
+:::
+
+
+## jest
+* 类型： `Object | Function`
+* 默认值：`{}`
+
+对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `Object` 类型时，可以配置 Jest 所支持的所有底层配置 。
+
+```js title=modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  testing: {
+    jest: {
+      testTimeout: 10000
+    }
+  }
+});
+```
+
+值为 `Function` 类型时，默认配置作为第一个参数传入，需要返回新的 Jest 配置对象。
+
+```js title=modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  testing: {
+    jest: options => {
+      return {
+        ...options,
+        testTimeout: 10000
+      }
+    }
+  }
+});
+```
+
+## transformer
+
+- 类型：`'babel-jest' | 'ts-jest'`
+- 默认值：`babel-jest`
+
+配置执行测试的时候对于源码的编译工具： [babel-jest](https://www.npmjs.com/package/babel-jest) 或 [ts-jest](https://github.com/kulshekhar/ts-jest)。默认使用 `babel-jest`。
+
+:::info
+`babel-jest` 也可以编译 TS 文件，但不会类型报错，如果你需要跑测试的时候对 TS 类型进行校验，那么请使用 `ts-jest`。
+:::

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

@@ -0,0 +1,132 @@
+# 处理静态资源文件
+
+模块工程会对代码中使用的静态资源进行处理。如果需要配置，则可以使用 [`buildConfig.asset`](/zh/api/build-config#asset) API。
+
+## 默认行为
+
+默认情况下，模块工程对于以下静态资源会进行处理：
+
+* `'.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/)。
+
+让我们看下面的例子：
+
+<CH.Spotlight>
+
+``` ts ./src/asset.ts
+import img from './bg.png';
+//...
+```
+
+---
+项目源代码。
+
+``` ts ./src/asset.ts
+import img from './bg.png';
+//...
+```
+---
+如果 `bg.png` 的大小小于 10 kb，则此时产物目录结构和产物内容为。
+
+<CH.Code>
+
+``` bash
+./dist
+└── asset.js
+```
+---
+
+``` js ./dist/asset.js
+var bg_default = "data:image/png;base64,";
+console.info(bg_default);
+```
+</CH.Code>
+---
+
+如果 `bg.png` 的大小大于 10 kb，则此时产物目录结构和产物内容为。
+
+<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>
+
+当想要修改默认行为的时候，可以使用以下 API：
+
+* `asset.path`：修改静态资源文件输出路径。
+* `asset.limit`：修改内联静态资源文件的阈值。
+
+## 设置 CDN 前缀
+
+如果项目运行的环境是在浏览器下，我们有可能需要静态资源托管至 CDN，然后在生产环境使用。
+
+那么此时默认生成的构建产物中，我们需要在静态资源文件的路径前面增加 CDN 的基础路径。还是看一个例子：
+
+<CH.Spotlight>
+
+``` ts ./src/asset.ts
+import img from './bg.png';
+//...
+```
+
+---
+项目源代码。
+
+``` ts ./src/asset.ts
+```
+---
+
+`modern.config` 配置为。
+
+``` ts ./modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    asset: {
+      publicPath: 'https://cdn/',
+    },
+  },
+});
+```
+
+---
+
+如果 `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);
+});
+```
+
+</CH.Spotlight>
+
+## SVGR
+
+WIP

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

@@ -0,0 +1,232 @@
+# 构建 umd 产物
+
+umd 全称为 **Universal Module Definition**，这种格式的 JS 文件可以运行在多个运行环境：
+
+* 浏览器环境：基于 AMD 规范进行模块加载
+* Node.js 环境：基于 CommonJS 进行模块加载
+* 其他情况：将模块挂载在全局对象上。
+
+因此我们可以通过下面的方式，将项目的构建产物指定为 umd 产物：
+
+``` 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 来控制项目是否对第三方依赖打包。
+因此在构建 umd 产物的过程中，我们也可以这样使用：
+
+<CH.Spotlight>
+
+```json package.json
+{
+  "dependencies": {
+    "react": "^17"
+    //...other dependencies
+  }
+}
+```
+
+---
+
+如果项目依赖了 `react`。
+
+```json package.json
+{
+  "dependencies": {
+    "react": "^17"
+    //...other dependencies
+  }
+}
+```
+
+---
+
+`modern.config.ts` 配置。
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    autoExternal: false,
+    externals: ['react'],
+  }
+});
+```
+
+---
+
+当源码中使用了 `react` 依赖。
+
+``` tsx src/index.ts
+import React from "react";
+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
+        };
+    }
+    console.info(_react.default);
+});
+```
+
+</CH.Spotlight>
+
+通过上面的例子我们知道，当使用 `autoExternal` 和 `externals` API 后：
+
+* 在 Node.js 环境下，可以通过 `require('react')` 获取 react 依赖。
+* 在 浏览器环境下，可以通过 `global.react` 获取 react 依赖。
+
+然而在浏览器环境下，获取第三方依赖的时候，**全局变量名称不一定与依赖名称完全相同**，此时就要使用 [`buildConfig.umdGlobals`](/zh/api/build-config#umdglobals) API。
+
+还是使用之前的例子，当 `react` 依赖以 `windows.React` 或者 `global.React` 全局变量的形式存在于浏览器环境下，那么此时：
+
+
+<CH.Spotlight>
+
+```json package.json
+{
+  "devDependencies": {
+    "react": "^17"
+  }
+}
+```
+
+---
+
+如果项目依赖了 `react`。
+
+```json package.json
+{
+  "devDependencies": {
+    "react": "^17"
+  }
+}
+```
+
+---
+
+`modern.config.ts` 配置。
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'umd',
+    umdGlobals: {
+      react: 'React',
+    },
+  }
+});
+```
+
+---
+
+当源码中使用了 `react` 依赖。
+
+``` tsx src/index.ts
+import React from "react";
+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);
+});
+```
+
+</CH.Spotlight>
+
+此时项目就可以运行在浏览器中，并使用存在于全局对象上的 `React` 变量了。
+
+## 更改项目的全局变量名称
+
+当我们将下面的代码打包成 umd 产物并运行在浏览器的时候，我们可以通过 `window.index` 来使用该模块。
+
+``` 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) {
+  //...
+});
+```
+
+如果需要修改它，则需要使用 [`buildConfig.umdModuleName`](/zh/api/build-config#umdmodulename) API。
+
+当使用该 API 后：
+
+``` 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) {
+  //...
+});
+```