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

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

@@ -1,11 +1,15 @@
+---
+sidebar_position: 4
+---
+
 # 如何处理第三方依赖
 
 一般来说，项目所需要的第三方依赖可以通过包管理器的 `install` 命令安装，在安装第三方依赖成功后，这些第三方依赖一般会出现在项目 `package.json` 的 `dependencies` 和 `devDependencies` 下。
 
-``` json pacakge.json
+```json pacakge.json
 {
-    "dependencies": {},
-    "devDependencies": {}
+  "dependencies": {},
+  "devDependencies": {}
 }
 ```
 
@@ -21,13 +25,13 @@
 
 ```json ./v1/package.json
 {
-    "dependencies": {
-        "react": "^17"
-    },
-    // or
-    "peerDependencies": {
-        "react": "^17"
-    }
+  "dependencies": {
+    "react": "^17"
+  },
+  // or
+  "peerDependencies": {
+    "react": "^17"
+  }
 }
 ```
 
@@ -42,7 +46,7 @@
   },
   // or
   "peerDependencies": {
-      "react": "^17"
+    "react": "^17"
   }
 }
 ```
@@ -51,8 +55,8 @@
 
 当源码中使用了 `react` 依赖。
 
-``` tsx src/index.ts
-import React from "react";
+```tsx src/index.ts
+import React from 'react';
 console.info(React);
 ```
 
@@ -60,8 +64,8 @@ console.info(React);
 
 此时产物中不会将 `react` 代码打包到产物中。
 
-``` js dist/index.js
-import React from "react";
+```js dist/index.js
+import React from 'react';
 console.info(React);
 ```
 
@@ -77,45 +81,45 @@ console.info(React);
 
 在构建配置中提供了以下 API 来处理第三方依赖：
 
-* [`buildConfig.autoExternal`](/zh/api/build-config#autoexternal)
-* [`buildConfig.externals`](/zh/api/build-config#externals)
+- [`buildConfig.autoExternal`](/zh/api/build-config#autoexternal)
+- [`buildConfig.externals`](/zh/api/build-config#externals)
 
 ### 关闭默认行为
 
 当我们希望关闭对于第三方依赖的默认处理行为时候，可以通过以下方式来实现：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     autoExternal: false,
-  }
+  },
 });
 ```
 
 这样对于 `"dependencies"` 和 `"peerDependencies"` 下面的依赖都会进行打包处理。如果只想要关闭其中某个下面的依赖处理，则可以使用
 `buildConfig.autoExternal` 的对象形式：
 
-``` ts
+```ts
 export default defineConfig({
   buildConfig: {
     autoExternal: {
       dependencies: false,
       peerDependencies: false,
     },
-  }
+  },
 });
 ```
 
 ### 排除指定第三方依赖
 
-而除了 `buildConfig.autoExternal` API以外，`buildConfig.externals` 也可以控制哪些第三方依赖要进行处理。我们可以组合这两个
+而除了 `buildConfig.autoExternal` API 以外，`buildConfig.externals` 也可以控制哪些第三方依赖要进行处理。我们可以组合这两个
 API 对项目的依赖进行更细微的处理。
 
 例如当我们需要仅对某些依赖不进行打包处理的时候，可以按照如下方式进行配置：
 
 > 一般这种情况，可能是某些依赖不适合进行打包处理。如果遇到这种情况，则可以按照下面的方式进行处理。
 
-``` ts
+```ts
 epxort default defineConfig({
   buildConfig: {
     autoExternal: false,

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

@@ -1,3 +1,7 @@
+---
+sidebar_position: 1
+---
+
 # 深入理解构建
 
 在【基础使用】的部分，我们已经知道可以通过 `buildConfig` 配置对项目的输出产物进行修改。`buildConfig` 不仅描述了产物的一些特性，同时还为构建产物提供了一些功能。
@@ -5,8 +9,8 @@
 :::tip{title=注意}
 如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
 
-* 【[修改输出产物](/zh/guide/modify-output-product)】
-:::
+- 【[修改输出产物](/zh/guide/modify-output-product)】
+  :::
 
 而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
 
@@ -26,9 +30,9 @@
 
 [`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?` 这个名称规则的文件，并将其作为入口文件。
+- 当 `buildType: 'bundle'` 的时候，`input` 默认值为 `['src/index.ts']`
+- 当 `buildType: 'bundleless'` 的时候，`input` 默认值为 `['src']`
+  > 实际上，在 `buildType: 'bundle'` 的时候，构建工具会检测是否存在符合 `src/index.(j|t)sx?` 这个名称规则的文件，并将其作为入口文件。
 
 :::warn{title=注意}
 建议不要在 Bundleless 构建过程中指定多个源码文件目录，可能出现不符合预期的结果。目前多个源码目录的 Bundleless 构建还处于不稳定阶段。
@@ -40,16 +44,16 @@
 
 在 Bundle 构建过程中，除了将 `input` 设置为一个数组，也可以将它设置为一个对象。**通过使用对象的形式，我们可以修改构建产物输出的文件名称**。那么对于下面的例子，`./src/index.ts` 对应的构建产物文件路径为 `./dist/main.js`。
 
-``` tsx modern.config.ts
+```tsx modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
-    buildConfig: {
-        input: {
-            main: ['./src/index.ts'],
-        },
-        outdir: './dist',
+  buildConfig: {
+    input: {
+      main: ['./src/index.ts'],
     },
+    outDir: './dist',
+  },
 });
 ```
 
@@ -59,13 +63,13 @@ export default defineConfig({
 
 [`sourceDir`](/zh/api/build-config#sourcedir) 用于指定源码目录，它主要与以下两个内容有关系：
 
-* 类型文件生成
-* 指定构建过程中的 [`outbase`](https://esbuild.github.io/api/#outbase)
+- 类型文件生成
+- 指定构建过程中的 [`outbase`](https://esbuild.github.io/api/#outbase)
 
 一般来说：
 
-* **在 Bundleless 构建过程中，`sourceDir` 与 `input` 的值要保持一致，它们的默认值都是 `src`**。
-* 在 Bundle 构建过程中，很少需要使用 `sourceDir`。
+- **在 Bundleless 构建过程中，`sourceDir` 与 `input` 的值要保持一致，它们的默认值都是 `src`**。
+- 在 Bundle 构建过程中，很少需要使用 `sourceDir`。
 
 ### 类型文件
 
@@ -80,8 +84,8 @@ import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   buildConfig: {
-    dts: false
-  }
+    dts: false,
+  },
 });
 ```
 
@@ -95,8 +99,8 @@ export default defineConfig({
 
 **模块工程解决方案同时还支持对类型文件进行打包**，不过使用该功能的时候需要注意：
 
-* 一些第三方依赖存在错误的语法会导致打包过程失败。因此对于这种情况，需要手动通过 [`buildConfig.externals`](/zh/api/build-config#externals) 将这类第三方包排除。
-* 对于第三方依赖的类型文件指向的是一个 `.ts` 文件的情况，目前无法处理。比如第三方依赖的 `package.json` 中存在这样的内容： `{"types": "./src/index.ts"}`。
+- 一些第三方依赖存在错误的语法会导致打包过程失败。因此对于这种情况，需要手动通过 [`buildConfig.externals`](/zh/api/build-config#externals) 将这类第三方包排除。
+- 对于第三方依赖的类型文件指向的是一个 `.ts` 文件的情况，目前无法处理。比如第三方依赖的 `package.json` 中存在这样的内容： `{"types": "./src/index.ts"}`。
 
 #### 别名转换
 
@@ -108,18 +112,18 @@ import utils from '@common/utils';
 
 正常来说，使用 `tsc` 生成的产物类型文件也会包含这些别名。不过 Module Tools 会对 `tsc` 生成的类型文件里的别名进行转换处理：
 
-* 对于类似 `import '@common/utils'` 或者 `import utils from '@common/utils'` 这样形式的代码可以进行别名转换。
-* 对于类似 `export { utils } from '@common/utils'` 这样形式的代码可以进行别名转换。
+- 对于类似 `import '@common/utils'` 或者 `import utils from '@common/utils'` 这样形式的代码可以进行别名转换。
+- 对于类似 `export { utils } from '@common/utils'` 这样形式的代码可以进行别名转换。
 
 然而也存在一些情况，目前还无法处理：
 
-* 对于类似 `Promise<import('@common/utils')>` 这样形式的输出类型目前无法进行转换。
+- 对于类似 `Promise<import('@common/utils')>` 这样形式的输出类型目前无法进行转换。
 
 #### 一些 `dts` 的使用示例
 
 一般使用方式：
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -130,14 +134,14 @@ export default defineConfig({
       tsconfigPath: './other-tsconfig.json',
       distPath: './types',
     },
-    outdir: './dist',
-  }
+    outDir: './dist',
+  },
 });
 ```
 
 使用 `dts.only` 的情况：
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -146,16 +150,16 @@ export default defineConfig({
     {
       buildType: 'bundle',
       dts: false,
-      outdir: './dist',
+      outDir: './dist',
     },
     {
       buildType: 'bundleless',
       dts: {
         only: true,
       },
-      outdir: './dist/types',
-    }
-  ]
+      outDir: './dist/types',
+    },
+  ],
 });
 ```
 
@@ -165,14 +169,14 @@ export default defineConfig({
 
 #### 环境变量替换
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 export default defineConfig({
   buildConfig: {
     define: {
-      'process.env.VERSION': JSON.stringify(process.env.VERSION || '0.0.0')
-    }
-  }
+      'process.env.VERSION': JSON.stringify(process.env.VERSION || '0.0.0'),
+    },
+  },
 });
 ```
 
@@ -192,14 +196,14 @@ console.log('1.0.0');
 
 #### 全局变量替换
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 export default defineConfig({
   buildConfig: {
     define: {
-      'VERSION': JSON.stringify(require('./package.json').version || '0.0.0')
-    }
-  }
+      VERSION: JSON.stringify(require('./package.json').version || '0.0.0'),
+    },
+  },
 });
 ```
 
@@ -218,28 +222,29 @@ console.log('1.0.0');
 ```
 
 不过要注意：如果项目是一个 TypeScript 项目，那么你可能需要在项目源代码目录下的 `.d.ts` 文件里增加以下内容：
+
 > 如果不存在 `d.ts` 文件，则可以手动创建。
 
-``` ts env.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 任务。
+- 根据 `buildConfig.outDir` 清理产物目录。
+- 编译 `js/ts` 源代码生成 Bundle/Bundleless 的 JS 构建产物。
+- 使用 `tsc` 生成 Bundle/Bundleless 的类型文件。
+- 处理 Copy 任务。
 
 ## 构建报错
 
 当发生构建报错的时候，基于以上了解到的信息，可以很容易的明白在终端出现的报错内容：
 
 **js 或者 ts 构建的报错：**
-``` bash
+
+```bash
 error  ModuleBuildError:
 
 ╭───────────────────────╮
@@ -253,7 +258,7 @@ Detailed Information:
 
 **类型文件生成过程的报错：**
 
-``` bash
+```bash
 error   ModuleBuildError:
 
 bundle DTS failed:
@@ -261,7 +266,7 @@ bundle DTS failed:
 
 对于 `js/ts` 构建错误，我们可以从报错信息中知道：
 
-* 通过 `'bundle failed:'` 来判断报错的是 Bundle 构建还是 Bundleless 构建？
-* 构建过程的 `format` 是什么？
-* 构建过程的 `target` 是什么？
-* 具体的报错信息。
+- 通过 `'bundle failed:'` 来判断报错的是 Bundle 构建还是 Bundleless 构建？
+- 构建过程的 `format` 是什么？
+- 构建过程的 `target` 是什么？
+- 具体的报错信息。

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

@@ -1,12 +1,16 @@
-# 深入理解构建
+---
+sidebar_position: 2
+---
+
+# 深入理解 dev 命令
 
 在【基础使用】的部分，我们已经知道可以通过 `buildConfig` 配置对项目的输出产物进行修改。`buildConfig` 不仅描述了产物的一些特性，同时还为构建产物提供了一些功能。
 
 :::tip{title=注意}
 如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
 
-* 【[修改输出产物](/zh/guide/modify-output-product)】
-:::
+- 【[修改输出产物](/zh/guide/modify-output-product)】
+  :::
 
 而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
 
@@ -23,4 +27,3 @@
 ### input 与 sourceDir 的关系
 
 ## 构建过程
-

package/docs/zh/guide/advance/theme-config.mdx

@@ -0,0 +1,78 @@
+---
+sidebar_position: 6
+---
+
+# 主题配置
+
+模块工程通过 [`designSystem`](/zh/api/design-system) API，提供了配置主题的能力。
+
+## 动机和原理
+
+主题配置有些类似组件库中的定制主题功能，主要用于样式开发中使用。我们可以通过 `designSystem` 配置在不同的样式开发环境下使用由它生成的 `designToken`。
+
+所谓 `designToken` 在不同的样式开发环境下对应不同的东西：
+
+- tailwindcss: 以 `designSystem` 作为 tailwindcss 的 `theme` 配置。因此可以使用：
+  - tailwindcss 支持的 HTML 类名。
+  - 在 css/less/sass 下通过 `@apply` 自定义指令使用与 tailwindcss 支持的 HTML 类名同名的字符串。
+- css/less/scss: 通过 `designSystem` 生成全局的样式变量。
+
+`designSystem` API 的数据结构借鉴了 `tailwindcss` 配置对象中的 [theme API](https://tailwindcss.com/docs/theme)，因此存在默认的一套 `designToken`。关于默认值，可以查看 [`designSystem` API](/zh/api/design-system)。
+
+:::info
+目前暂时还未支持 css/less/sass 全局变量。
+:::
+
+## 使用示例
+
+### tailwindcss
+
+在使用 tailwindcss 的时候，可以通过 `designSystem` 来设置它的 [`theme`](https://v2.tailwindcss.com/docs/theme#extending-the-default-theme) 配置。
+
+例如在下面的配置中扩展了原有的颜色配置:
+
+```ts ./modern.config.ts
+export default {
+  designSystem: {
+    extend: {
+      colors: {
+        primary: '#1677ff',
+      },
+    },
+  },
+};
+```
+
+我们可以在代码中有两种使用 tailwindcss 的方式。
+
+#### HTML 类名。
+
+```tsx ./src/index.tsx
+import 'tailwindcss/utilities.css';
+
+export default () => {
+  return <div className="bg-primary"></div>;
+};
+```
+
+#### `@apply` 指令
+
+关于 [`@apply`](https://tailwindcss.com/docs/functions-and-directives#apply)。
+
+<CH.Code>
+
+```tsx ./src/index.tsx
+import './index.css';
+
+export default () => {
+  return <div className="btn-primary"></div>;
+};
+```
+
+```css ./src/index.css
+.btn-primary {
+  @apply bg-primary;
+}
+```
+
+</CH.Code>

package/docs/zh/guide/basic/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "基础使用",
+  "sidebar_position": 2
+}

package/docs/zh/guide/basic/before-getting-started.md

@@ -1,8 +1,13 @@
+---
+sidebar_position: 1
+---
+
 # 开始之前
 
 ## 环境准备
 
 为了使用 Modern.js 模块工程解决方案，首先需要 [NodeJS](https://nodejs.org/zh/)，我们推荐最新的[长期维护版本](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 **14.17.6**。因为非稳定的 NodeJS 时常有一些 Bug，你可以使用 [nvm-windows](https://github.com/coreybutler/nvm-windows) 和 [nvm](https://github.com/nvm-sh/nvm)（Mac/linux）安装，这样你就可以方便地切换到不同的 NodeJS 版本，这些版本可能会用于不同的项目。
+
 ## 初识 npm
 
 当 NodeJS 被安装后，你不仅可以在命令行中访问 `node` 可执行程序，同时你也可以执行 `npm` 命令。
@@ -15,7 +20,7 @@ npm 是 NodeJS 的标准软件包管理器。它一开始的用途是用于下
 
 那么什么是 npm 包类型的项目呢？当我们在一个空的项目目录下执行 `npm init` 命令的时候，它会在当前目录下面创建一个文件名为 `package.json` 的 JSON 文件。在创建过程中，我们需要填写包括但不限于 npm 包的名称、版本号、描述等等内容，这些填写的内容都会在生成的 `package.json` 文件中找到：
 
-``` json
+```json
 {
   "name": "npm-demo",
   "version": "1.0.0",
@@ -41,27 +46,27 @@ npm Registry 是一个 [npm 包存储的地方](https://docs.npmjs.com/about-the
 
 - `"dependencies"`：一种是你的应用程序在生产环境中需要的软件包。
 - `"devDependencies"`：另一种是仅在本地开发和测试中需要的软件包。
-> 软件包可以理解为是第三方的 npm 包。
+  > 软件包可以理解为是第三方的 npm 包。
 
 你可以通过执行 `npm install npm-package-name` 或者 `npm add npm-package-name` 的方式来安装在**生产环境中需要的软件包**，或者也可以在 `package.json` 文件中手动的将需要安装的包和对应的[语义化版本](https://docs.npmjs.com/about-semantic-versioning)写在 `"dependencies"` 里，并执行 `npm install` 命令：
 
-``` json
+```json
 {
-    "name": "your-npm-project",
-    "dependencies": {
-      "npm-package-name": "0.1.0"
-    },
+  "name": "your-npm-project",
+  "dependencies": {
+    "npm-package-name": "0.1.0"
+  }
 }
 ```
 
 同理，你也可以执行 `npm install npm-package-name --save-dev` 或 `npm add npm-package-name --save-dev` 的方式来安装**仅在本地开发和测试中需要的软件包**，或者也可以在 `package.json` 文件中手动的将需要安装的包和对应的[语义化版本](https://docs.npmjs.com/about-semantic-versioning)写在 `"devDependencies"` 里，并执行 `npm install` 命令：
 
-``` json
+```json
 {
-    "name": "your-npm-project",
-    "devDependencies": {
-      "npm-package-name": "0.1.0"
-    },
+  "name": "your-npm-project",
+  "devDependencies": {
+    "npm-package-name": "0.1.0"
+  }
 }
 ```
 
@@ -92,13 +97,13 @@ npm Registry 是一个 [npm 包存储的地方](https://docs.npmjs.com/about-the
 
 名称匹配的[前置命令和后置命令](https://docs.npmjs.com/cli/v9/using-npm/scripts#pre--post-scripts)也会被运行（例如 `premyscript`、`myscript`、`postmyscript`）。
 
-``` json
+```json
 {
-    "scripts": {
-        "premyscript": "",
-        "myscript": "",
-        "postmyscript": "",
-    }
+  "scripts": {
+    "premyscript": "",
+    "myscript": "",
+    "postmyscript": ""
+  }
 }
 ```
 
@@ -160,14 +165,14 @@ npm install -g pnpm
 
 初始化的配置文件的内容如下：
 
-``` typescript
+```typescript
 // modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({});
 ```
 
-``` js
+```js
 // modern.config.js
 const { defineConfig } = require('@modern-js/module-tools');
 
@@ -176,12 +181,12 @@ module.exports = defineConfig({});
 
 **我们推荐使用 `defineConfig` 函数**，不过并不强制使用它。因此你也可以在配置文件中直接返回一个对象：
 
-``` typescript
+```typescript
 // modern.config.ts
 export default {};
 ```
 
-``` js
+```js
 // modern.config.js
 module.exports = {};
 ```