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

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

@@ -0,0 +1,4 @@
+{
+  "label": "介绍",
+  "sidebar_position": 1
+}

package/docs/zh/guide/intro/getting-started.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 3
+---
+
 # 快速开始
 
 ## 三分钟快速上手
@@ -21,15 +25,16 @@ npm install -D @modern-js/module-tools @modern-js/plugin-testing
 
 ```json
 {
-    "scripts": {
-        "build": "modern build"
-    }
+  "scripts": {
+    "build": "modern build"
+  }
 }
 ```
 
 如果你的项目存在 `src/index.(js|jsx)` 文件或者同时存在 `src/index.(ts|tsx)` 和 `tsconfig.json` 文件，那么恭喜你可以运行直接运行 `npm run build` 来使用 Module Tools 构建你的项目了。
 
 **如果你想要看看使用了模块工程方案的真实项目，可以执行以下命令**：
+
 ```bash
 git clone https://github.com/modern-js-dev/module-tools-examples
 cd module-tools-example
@@ -46,8 +51,8 @@ pnpm dev storybook
 ## 测试
 pnpm test
 ```
-> 上面的链接对应的内容待补充
 
+> 上面的链接对应的内容待补充
 
 **如果你想要创建一个完整的模块工程项目，可以执行以下命令：**
 
@@ -63,6 +68,7 @@ npx @modern-js/create your-project-dir-name
 ? 请选择开发语言 TS
 ? 请选择包管理工具 pnpm
 ```
+
 > 项目名称为 `package.json` 中的 `"name"` 字段值。
 
 接着就会开始初始化项目的流程。在项目目录和文件生成以及依赖安装完毕后，此时就创建了一个完整的模块工程项目。
@@ -73,6 +79,6 @@ npx @modern-js/create your-project-dir-name
 
 选择适合你的教程：
 
-- 我是初学者，需要学习 Module Tools 的[基础使用](/zh/guide/before-getting-started)。
-- 我已经初步掌握了 Module Tools 的使用，可以学习 Module Tools 的[高级使用](/zh/guide/before-getting-started)。
+- 我是初学者，需要学习 Module Tools 的[基础使用](/guide/basic/before-getting-started)。
+- 我已经初步掌握了 Module Tools 的使用，可以学习 Module Tools 的[高级使用](/guide/basic/before-getting-started)。
 - 我是项目的维护者，需要学习如何开发 Module Tools 的插件以及了解更多关于 Module Tools 进阶的内容。

package/docs/zh/guide/intro/welcome.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 1
+---
+
 # 欢迎使用
 
 Module Tools 是 Modern.js 的模块工程解决方案，同时也是核心依赖。它可以让开发者更轻松地构建、调试、发布模块类型的项目。模块类型的项目大多数情况可以认为是 npm 包类型的项目，它可能是一个组件、组件库或者工具库项目。

package/docs/zh/guide/intro/why-module-engineering-solution.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 2
+---
+
 # 为什么需要模块工程解决方案
 
 大家可能都经历过：从零开始开发一个组件库或者工具库的过程中，我们不仅要考虑项目本身的代码逻辑如何编写，还要考虑项目的构建、调试、测试、代码格式化等等和代码逻辑无关的事情。
@@ -12,6 +16,6 @@
 
 如果说每次开发一个模块类型的项目都需要经历一遍这些工作准备的话，那么基本上刚开始开发的时间会大部分花费在这些与代码实现无关的事情上。如果能够提供一个模块工程解决方案，它能够帮助开发者解决项目工程上的事情，让开发者可以更专注于代码的实现上，那么这将会大大提升模块类型项目的开发体验。
 
-![没有使用工程方案对比使用工程方案](/why-module-solution.png)
+![没有使用工程方案对比使用工程方案](https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/module-tools/why-module-solution.png)
 
 Modern.js 为了让开发模块类型的项目更简单，为了解决上述提到的问题提供了模块工程解决方案，并且使用 Module Tools 提供了主要的功能。**Module-tools 可以理解为是一个专门用于模块类型项目开发的工具**。

package/docs/zh/index.md

@@ -2,13 +2,13 @@
 pageType: home
 
 hero:
-  name: Module tools
+  name: Module Tools
   text: 模块工程解决方案
   tagline: 简单、强大、高性能的现代化npm包开发方案
   actions:
     - theme: brand
       text: 欢迎使用
-      link: /zh/guide/intro/welcome
+      link: /guide/intro/welcome
 
 features:
   - title: 'Esbuild: 高性能的JS Bundler'
@@ -27,3 +27,4 @@ features:
     details: 通过其插件扩展机制，你可以轻松的扩展Module tools的各项能力。
     icon: 🎨
 ---
+# index

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

@@ -0,0 +1,4 @@
+{
+  "label": "指南",
+  "sidebar_position": 1
+}

package/docs/zh/plugins/guide/getting-started.mdx

@@ -0,0 +1,84 @@
+---
+sidebar_position: 1
+---
+
+# 快速开始
+
+模块工程解决方案不仅提供了丰富的功能，同时也支持通过插件的方式为当前项目扩展能力。
+
+我们可以通过下面的例子来快速了解如果编写一个 module-tools 插件：
+
+<CH.Spotlight>
+
+```md ./project
+./
+├── plugins
+│ └── example.ts
+├── src/
+└── modern.config.ts
+```
+
+---
+
+首先我们在初始化的项目下创建 `./plugins/example.ts` 文件。
+
+```md ./project
+
+```
+
+---
+
+接着在 `example.ts` 文件中增加插件的代码。
+
+```ts
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+export const ExamplePlugin = (): CliPlugin<ModuleTools> => {
+  return {
+    name: 'example',
+    setup() {
+      console.info('this is example plugin');
+      return {
+        // use hooks
+        afterBuild() {
+          console.info('build over');
+        }
+      };
+    };
+  };
+};
+```
+
+---
+
+然后我们通过 [`plugins`](/api/config/plugins) API，将刚刚写好的插件进行注册。
+
+```ts ./modern.config.ts
+import { ExamplePlugin } from './plugins/example';
+export default defineConfig({
+  plugins: [ExamplePlugin()],
+});
+```
+
+---
+
+最后运行 `modern build`，就可以看到。
+
+```bash terminal
+this is example plugin
+Build succeed: 510.684ms
+build over
+```
+
+</CH.Spotlight>
+
+通过上面这个例子，我们了解到了下面几件事：
+
+- 推荐的插件目录结构
+- 插件的初始化代码
+- 插件的注册
+
+除了以上内容以外，我们还需要了解：
+
+- [插件对象、类型定义与推荐配置项](/plugins/guide/plugin-object)
+- [setup 函数、`api` 对象参数、生命周期钩子](/plugins/guide/setup-function)

package/docs/zh/plugins/guide/plugin-object.mdx

@@ -0,0 +1,85 @@
+---
+sidebar_position: 2
+---
+
+# 插件对象
+
+Module-tools 插件是一个对象，对象包含以下属性：
+
+- `name`：插件的名称，唯一标识符。
+- `setup`：插件初始化函数，只会执行一次。setup 函数可以返回一个 [Hooks 对象]()，module-tools 会在特定的时机执行 Hooks 对象上定义的 Hook 对应的函数。
+
+例如在下面的插件代码示例中，在项目开始执行构建任务之前会触发 `beforeBuild` 函数的执行，并打印 `build start` 的 log 内容。
+
+<CH.Code>
+
+```ts ./plugins/demo.tsx
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+const MyPlugin: CliPlugin<ModuleTools> = {
+  name: 'my-plugin',
+
+  setup() {
+    return {
+      // this is hook
+      beforeBuild: () => {
+        console.info('build start');
+      },
+    };
+  },
+};
+```
+
+---
+
+```ts ./modern.config.ts
+import { MyPlugin } from './plugins/demo';
+export default {
+  plugins: [MyPlugin()],
+};
+```
+
+</CH.Code>
+
+## 插件类型定义
+
+使用 TypeScript 时，可以引入内置的 `CliPlugin` 和 `ModuleTools` 类型，为插件提供正确的类型推导：
+
+```ts
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+const MyPlugin: CliPlugin<ModuleTools> = {
+  name: 'my-plugin',
+
+  setup() {
+    const foo = '1';
+
+    return {
+      // this is hook
+      afterBuild: () => {
+        //...
+      },
+    };
+  },
+};
+```
+
+## 插件配置项
+
+**建议将插件写成函数的形式**，使插件能通过函数入参来接收配置项：
+
+```ts
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+type MyPluginOptions = {
+  foo: string;
+};
+
+const MyPlugin = (options: MyPluginOptions): CliPlugin<ModuleTools> => ({
+  name: 'my-plugin',
+
+  setup() {
+    console.log(options.foo);
+  },
+});
+```

package/docs/zh/plugins/guide/setup-function.mdx

@@ -0,0 +1,117 @@
+---
+sidebar_position: 3
+---
+
+# Setup 函数
+
+在[【插件对象】](/plugins/guide/plugin-object) 部分我们知道插件对象包含了一个 `setup` 函数，该函数不仅包含了一个 `api` 对象参数，同时还可以返回一个 Hooks 对象。
+
+## 插件 API 对象
+
+插件的 `setup` 函数会提供一个 `api` 对象参数，你可以调用该对象上提供的一些方法来获取到配置、项目上下文等信息。
+
+```ts
+export default (): CliPlugin<ModuleTools> => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    // 获取应用原始配置
+    const config = api.useConfigContext();
+    // 获取应用运行上下文
+    const appContext = api.useAppContext();
+    // 获取解析之后的最终配置
+    const resolvedConfig = api.useResolvedConfigContext();
+  },
+});
+```
+
+### `api.useAppContext`
+
+用于获取项目上下文信息。
+
+```ts
+const useAppContext: () => IAppContext;
+
+interface IAppContext {
+  appDirectory: string;
+  configFile: string | false;
+  packageName: string;
+  nodeModulesDirectory: string;
+  internalDirectory: string;
+  plugins: {
+    cli?: any;
+    server?: any;
+  }[];
+}
+```
+
+:::info
+通过实际的类型文件我们可以看到还存在着其他的字段，不过目前对于模块工程有意义的字段只有以上内容。api 对象其他的方法也是如此。
+:::
+
+### `api.useResolvedConfigContext`
+
+用于获取解析之后的最终配置。
+
+:::info
+如果需要获取构建相关的最终配置，需要使用 [`beforeBuild`]() Hook。
+:::
+
+```ts
+const useResolvedConfigContext: () => NormalizedConfig;
+
+interface NormalizedConfig {
+  buildConfig: PartialBuildConfig;
+  buildPreset: BuildPreset;
+  designSystem?: Record<string, any>;
+  dev: Dev;
+  plugins: PluginConfig;
+  runtime: RuntimeConfig;
+  runtimeByEntries?: RuntimeByEntriesConfig;
+  _raw: UserConfig;
+}
+```
+
+### `api.useHookRunners`
+
+用于获取 Hooks 的执行器，并触发特定的 Hook 执行。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    const hookRunners = api.useHookRunners();
+    // 触发 afterBuild Hook
+    await hookRunners.afterBuild();
+  },
+});
+```
+
+## 异步 setup
+
+CLI 插件的 setup 可以是一个异步函数，在初始化过程中执行异步逻辑。
+
+```ts
+export default (): CliPlugin<ModuleTools> => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    await doSomething();
+  },
+});
+```
+
+## 生命周期钩子
+
+我们知道 `setup` 函数会返回一个 Hooks 对象，所谓 Hooks 对象也可以理解是具有 module-tools 生命周期钩子的对象。
+
+目前主要包含两类钩子：
+
+- 构建钩子：仅在执行 `build` 命令构建源码产物时触发。
+- `buildPlatform` 钩子：仅在执行 `build --platform` 命令生成其他构建产物时触发。
+- 调试钩子：运行 `dev` 命令时会触发的钩子。
+
+关于生命周期钩子的完整列表参考 [API 文档](/api/plugin-api/plugin-hooks)。

package/docs/zh/plugins/official-list/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "插件列表",
+  "sidebar_position": 2
+}

package/docs/zh/plugins/official-list/overview.md

@@ -0,0 +1,5 @@
+# 总览
+
+## 官方插件
+
+（建设中）

package/modern.config.ts

@@ -0,0 +1,119 @@
+import path from 'path';
+import { defineConfig } from '@modern-js/doc-tools';
+import { remarkCodeHike } from '@code-hike/mdx';
+import { pluginAutoSidebar } from '@modern-js/doc-plugin-auto-sidebar';
+
+const theme = require('shiki/themes/nord.json');
+const { version } = require('./package.json');
+
+const isDevCommand = process.env.NODE_ENV !== 'production';
+
+function getI18nHelper(lang: 'zh' | 'en') {
+  const cn = lang === 'zh';
+  const prefix = cn ? '' : '/en';
+  const getLink = (str: string) => `${prefix}${str}`;
+  const getText = (cnText: string, enText: string) => (cn ? cnText : enText);
+  return { getText, getLink };
+}
+
+function getNavbar(lang: 'zh' | 'en') {
+  const { getLink, getText } = getI18nHelper(lang);
+
+  return [
+    {
+      text: getText('指南', 'Guide'),
+      link: getLink('/guide/intro/welcome'),
+      activeMatch: '^/guide/',
+    },
+    {
+      text: getText('API', 'API'),
+      link: getLink('/api/'),
+      activeMatch: '^/api/',
+    },
+    {
+      text: getText('插件', 'Plugins'),
+      link: getLink('/plugins/guide/getting-started'),
+      activeMatch: '^/plugins/',
+    },
+    {
+      text: `v${version}`,
+      items: [
+        {
+          text: getText('更新日志', 'Changelog'),
+          link: 'https://github.com/modern-js-dev/modern.js/tree/main/packages/solutions/module-tools/CHANGELOG.md',
+        },
+        {
+          text: getText('贡献指南', 'Contributing'),
+          link: 'https://github.com/modern-js-dev/modern.js/tree/main/packages/solutions/module-tools/CHANGELOG.md',
+        },
+      ],
+    },
+  ];
+}
+
+export default defineConfig({
+  plugins: ['@modern-js/doc-tools'],
+  doc: {
+    root: path.join(__dirname, 'docs'),
+    lang: 'zh',
+    base: isDevCommand ? '' : '/module-tools/',
+    title: 'Module Tools',
+    // The plugins for doc tools.
+    plugins: [
+      pluginAutoSidebar({
+        root: path.join(__dirname, 'docs'),
+        categories: ['zh', 'en']
+          .map(lang =>
+            ['guide', 'api', 'plugins'].map(category => `${lang}/${category}`),
+          )
+          .flat(),
+        collapsed: false,
+      }),
+    ],
+    markdown: {
+      checkDeadLinks: true,
+      remarkPlugins: [
+        [
+          remarkCodeHike,
+          {
+            theme,
+            autoImport: true,
+            showCopyButton: true,
+          },
+        ],
+      ],
+    },
+    themeConfig: {
+      footer: {
+        message: 'Copyright © 2022 ByteDance.',
+      },
+      socialLinks: [
+        {
+          icon: 'github',
+          mode: 'link',
+          content:
+            'https://github.com/modern-js-dev/modern.js/tree/main/packages/solutions/module-tools',
+        },
+      ],
+      locales: [
+        {
+          lang: 'zh',
+          label: '简体中文',
+          nav: getNavbar('zh'),
+          title: 'Module Tools',
+          outlineTitle: '目录',
+          prevPageText: '上一页',
+          nextPageText: '下一页',
+          description: '模块工程解决方案',
+        },
+        {
+          lang: 'en',
+          label: 'English',
+          nav: getNavbar('en'),
+          title: 'Module Tools',
+          description: 'Module Engineering Solutions',
+        },
+      ],
+    },
+  },
+});

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@modern-js/module-tools-docs",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.2",
   "description": "docs",
   "main": "index.js",
   "keywords": [],
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "islandjs": "0.7.19",
     "@code-hike/mdx": "^0.7.4",
-    "shiki": "^0.11.1"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "shiki": "^0.11.1",
+    "@modern-js/doc-plugin-auto-sidebar": "2.0.2",
+    "@modern-js/doc-tools": "2.0.2"
   },
   "scripts": {
-    "dev": "island dev docs",
-    "build": "island build docs",
-    "preview": "island start docs"
+    "dev": "modern dev",
+    "build": "modern build"
   }
 }

package/{docs/.island/styles → theme}/index.css

@@ -1,4 +1,3 @@
-/* .island/styles/index.css */
 @import '@code-hike/mdx/dist/index.css';
 
 .ch-scrollycoding .header-anchor {

package/theme/index.ts

@@ -0,0 +1,4 @@
+import './index.css';
+
+export * from '@modern-js/doc-tools/theme';
+export { default } from '@modern-js/doc-tools/theme';

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "jsx": "preserve"
+  },
+  "include": ["./theme", "./modern.config.ts"]
+}