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

package/docs/zh/guide/basic/test-your-project.mdx

@@ -0,0 +1,158 @@
+# 测试项目
+
+本章将要介绍如何测试可复用模块。
+
+## 先决条件和约定
+
+想要使用项目的测试功能，需要确保项目中包含以下依赖：
+
+* `"@modern-js/plugin-testing"`
+
+在模块工程方案中，对于测试用例或者说编写测试的文件有如下约定：
+
+* 项目目录下的 `tests` 目录为测试用例和测试文件的目录，**不支持更改运行测试用例的目录**。
+* 默认会自动将后缀为 `.test.[tj]sx?` 的文件识别为测试文件。
+* 其他的 `.[tj]sx?` 后缀的文件被识别为普通的文件，可以用于测试的 `utils` 文件或者其他用途。
+
+
+## 运行测试
+
+当准备好了依赖以及了解了测试用例在哪里编写后，我们可以通过以下命令来执行测试：
+
+``` bash
+modern test
+
+// 更新 snapshot
+modern test --updateSnapshot
+```
+
+执行之后，会看到测试的结果：
+
+![test-result](/test-result.png)
+
+## 使用配置
+
+模块工程方案对测试提供了以下配置：
+
+* [`testing`](/zh/api/config-test)
+
+可以在 `modern.config.(j|t)s` 中增加它。
+
+## 测试示例
+
+### 普通模块
+
+对于普通的模块，我们可以按照如下方式使用测试功能：
+
+<CH.Spotlight>
+
+``` typescript ./src/index.ts
+export default function () {
+  return 'hello world';
+}
+```
+
+---
+
+首先是模块的代码。
+
+``` typescript ./src/index.ts
+export default function () {
+  return 'hello world';
+}
+```
+
+---
+
+然后在测试文件中，我们可以这样。
+
+其中 `@` 指向了源码目录，在初始化项目的 `tests/tsconfig.json` 中定义了。
+
+``` typescript ./tests/index.test.ts
+import main from '@/index';
+
+describe('默认值 cases', () => {
+  test('Have returns', () => {
+    const drink = jest.fn(main);
+    drink();
+    expect(drink).toHaveReturned();
+  });
+});
+```
+
+---
+
+最后我们可以执行 `modern test`。
+
+``` bash
+pnpm test
+## or
+yarn test
+## or
+npm run test
+```
+
+</CH.Spotlight>
+
+### 组件
+
+对于组件，Modern.js 的 [Runtime API](xxx) 提供了用于测试 UI 组件的功能，其功能由 `@modern-js/runtime/testing` 提供。
+
+:::tip
+如果需要使用 Runtime API，那么可以通过 [微生成器](/zh/guide/command-preview) 开启。
+:::
+
+<CH.Spotlight>
+
+``` tsx ./src/index.tsx
+export const default () {
+  return (
+    <div>This is a UI Component</div>
+  );
+}
+```
+
+---
+
+首先是组件的代码。
+
+``` tsx ./src/index.tsx
+export const default () {
+  return (
+    <div>This is a UI Component</div>
+  );
+}
+```
+
+---
+
+然后在测试文件中，我们可以这样。
+
+其中 `@` 指向了源码目录，在初始化项目的 `tests/tsconfig.json` 中定义了。
+
+``` tsx ./tests/index.test.tsx
+import { render, screen } from '@modern-js/runtime/testing';
+
+import Component from '@/index';
+
+describe('默认值 cases', () => {
+  test('Rendered', () => {
+    render(<Component />);
+    expect(screen.getByText('This is a UI Component')).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+最后我们可以执行 `modern test`。
+
+``` bash
+pnpm test
+## or
+yarn test
+## or
+npm run test
+```
+
+</CH.Spotlight>

package/docs/zh/guide/basic/use-micro-generator.md

@@ -0,0 +1,35 @@
+# 使用微生成器
+
+模块工程解决方案提供了微生成器工具，它可以为当前项目：
+
+* 新增目录和文件
+* 修改 `package.json` 文件内容
+* 执行命令
+
+因此通过这些能力，**微生成器可以为项目开启额外的特性功能**。
+
+可以通过 [`modern new`](/zh/guide/command-preview) 启动微生成器。目前模块工程方案支持的微生成器功能有：
+
+## Storybook 调试
+
+当我们想要对组件或者普通模块进行调试的时候，可以启用 **Storybook 调试功能**。启动该功能后，**会在项目目录下创建 `stories` 目录以及相关文件，在 package.json 中新增 `"@modern-js/plugin-storybook"` 依赖**。
+
+关于如何启动 Storybook 以及如何使用 Storybook，可以查看下面的链接：
+
+* [`modern dev`](/zh/guide/command-preview#modern-dev)
+* [使用 Storybook](/zh/guide/using-storybook)
+
+## Tailwind CSS 支持
+
+当我们想要为项目增加 [Tailwind CSS](https://v2.tailwindcss.com/) 支持的时候，可以启动这个功能。Tailwind CSS 是一个 CSS 库，提供开箱即用的样式。
+
+关于如何在模块工程里使用 Tailwind CSS，可以查看：
+
+* [使用 Tailwind CSS](xxx)
+
+
+## 启动 Modern.js Runtime API
+
+**Modern.js 提供了 [Runtime API](xxx) 能力，这些 API 只能在 Modern.js 的应用项目环境中使用**。如果你需要开发一个 Modern.js 应用环境中使用的组件，那么你可以开启该特性，微生成器会增加 `"@modern-js/runtime"`依赖。
+
+另外，Storybook 调试工具也会通过检测项目的依赖确定项目是否需要使用 Runtime API，并且提供与 Modern.js 应用项目一样的 Runtime API 运行环境。

package/docs/zh/guide/basic/using-storybook.mdx

@@ -0,0 +1,186 @@
+# 使用 Storybook
+
+首先如果没有看过以下内容的话，可以先花几分钟先了解一下：
+
+* [使用微生成器开启 Storybook 调试](/zh/guide/use-micro-generator#storybook-调试)
+* [`modern dev`](/zh/guide/command-preview#modern-dev)
+
+[Storybook](https://storybook.js.org/) 是一个专门用于组件调试的工具，围绕着组件开发提供了：
+
+* 丰富多样的调试能力
+* 可与一些测试工具结合使用
+* 可重复使用的文档内容
+* 可分享能力
+* 工作流程自动化
+
+因此它是一个复杂且功能强大的工具。
+
+模块工程解决方案集成了 Storybook，因此你几乎可以按照 Storybook 官方文档的内容进行使用。不过依然有一些地方需要注意，接下来讲解一下：
+
+## 调试代码
+
+在调试代码过程中需要引入组件代码，目前可以通过两种方式引入组件代码：
+
+* 引用组件产物
+* 引用组件源码
+
+我们更推荐使用第一种“**引用组件产物**”的方式。因为它几乎接近真实的使用场景，不仅可以对组件功能进行调试，同时也对构建产物的正确性进行了验证。
+
+接下来我们分别讲一下这两种方式具体如何使用。
+
+### 引用组件产物
+
+假如存在 TypeScript 项目 `foo`：
+
+<CH.Spotlight>
+
+```json package.json
+{
+    "name": "foo",
+    "main": "./dist/index.js",
+    "types": "./dist/types/index.d.ts"
+}
+```
+
+---
+
+确保 `package.json` 的 `main` 和 `types`
+的值为真实的路径。
+
+```json package.json
+{
+    "name": "foo",
+    "main": "./dist/index.js",
+    "types": "./dist/types/index.d.ts"
+}
+```
+
+---
+
+`foo` 项目的源码。
+
+```typescript src/index.ts
+export const content = 'hello world';
+```
+
+---
+
+确保在 `stories/tsconfig.json` 中设置了指向项目根目录的 `paths` 配置。
+`paths` 的 `key` 与项目名称相同。
+
+```json stories/tsconfig.json focus=7:9
+{
+  "extends": "../tsconfig.json",
+  "include": ["./"],
+  "compilerOptions": {
+    "jsx": "preserve",
+    "baseUrl": ".",
+    "paths": {
+      "foo": ["../"]
+    }
+  }
+}
+```
+
+---
+
+最后在 Story 代码中直接以项目名称的方式引用。
+
+```tsx stories/index.stories.tsx focus=1:1
+import { content } from 'foo';
+
+const Component = () => <div>this is a Story Component {content}</div>;
+
+export const YourStory = () => <Component />;
+
+export default {
+  title: 'Your Stories',
+};
+```
+
+</CH.Spotlight>
+
+如果在开发过程中，遇到无法实时获得类型定义的情况，此时：
+
+对于 `pnpm` 的项目，可以按照下面的内容对 `package.json` 进行修改：
+
+``` ts focus=4:7
+{
+    "name": "foo",
+    "main": "./dist/index.js",
+    "types": "./src/index.ts",
+    "publishConfig": {
+      "types": "./dist/index.d.ts",
+    }
+}
+```
+> 关于 pnpm 的 `publishConfig` 的使用，可以阅读下面这个[链接](https://pnpm.io/package_json#publishconfig)。
+
+而对于 npm 和 Yarn 的项目，则只能通过手动的方式在**开发阶段**和**发布阶段**对 `package.json` 的 `types` 的值进行修改。
+
+
+那么为什么可以直接引用产物呢？
+
+1. 在执行 `modern dev storybook` 命令之前，会自动执行 `modern build` 命令，保证项目构建产物的存在。
+2. 在 Storybook 内部增加了以项目名称作为别名的处理，保证能够**根据 `package.json` 解析出项目的产物路径**。
+
+
+### 引用组件源码
+
+引用组件的源码可以通过相对路径的方式：
+
+```ts ./stories/index.tsx
+import { content } from '../src';
+
+const Component = () => <div>this is a Story Component {content}</div>;
+
+export const YourStory = () => <Component />;
+
+export default {
+  title: 'Your Stories',
+};
+```
+
+那么为什么不推荐使用源码的方式呢？
+
+不仅仅是因为使用组件源码无法验证组件产物是否正确，**同时模块工程对于构建产物支持的一些配置无法完全转换为 Storybook
+内部的配置**。如果某些配置无法进行相互转换的话，就会在 Storybook 调试过程中出现不符合预期的结果。
+
+## 配置 Storybook
+
+### 配置文件
+
+Storybook 官方通过一个名为 `.storybook` 的文件夹来进行项目配置，其中包含各种配置文件。**在模块工程方案中，可以在项目的 `config/storybook` 目录下增加 Storybook 配置文件。**
+
+关于 Storybook 各种配置文件的使用方式，可以查看下面的链接：
+
+* [Configure Storybook](https://storybook.js.org/docs/react/configure/overview)
+
+**不过在模块项目里进行 Storybook 存在一些限制**：
+
+* 目前不能修改 Story 文件存放的位置，即无法在 `main.js` 文件里修改 `stories` 配置。
+* 目前不能修改 Webpack 和 Babel 相关的配置，即无法在 `main.js` 文件里修改 `webpackFinal` 和 `babel` 配置。
+
+在未来我们会考虑这些配置是否可以允许修改，不过目前为了减少不可预知的问题暂时限制使用这些配置。
+
+### `dev.storybook`
+
+除了配置文件以外，模块工程方案还在 `modern.config.(j|t)s` 项目配置文件里提供了 `dev.storybook` 配置项。
+
+目前可以通过该配置对 Storybook 的 webpack 配置进行修改。
+
+* [`dev.storybook.webpack`](xxx)
+
+### 构建 Storybook 产物
+
+除了可以对组件或者普通的模块进行 Storybook 调试，还可以通过下面的命令来执行 Storybook 的构建任务。
+
+``` bash
+modern build --platform storybook
+```
+
+关于 `modern build --platform` 命令可以查看：
+
+* [`modern build`](/zh/guide/command-preview#modern-build)
+
+构建完成后，可以在 `dist/storybook-static` 目录看到构建产物文件。

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

@@ -0,0 +1,78 @@
+# 快速开始
+
+## 三分钟快速上手
+
+想要实际体验 Module Tools？首先需要安装 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 **14.17.6**。
+
+然后在你的项目里安装以下依赖：
+
+- `@modern-js/module-tools`
+- `@modern-js/plugin-testing`
+
+> 如果是一个 TypeScript 项目，则需要增加 `"typescript"` 依赖。
+
+```bash
+npm install -D @modern-js/module-tools @modern-js/plugin-testing
+```
+
+> 对于使用 pnpm 或者 Yarn 包管理器的项目，只需要替换 npm 就可以了。**推荐使用 pnpm**。
+
+接着在项目的 `package.json` 文件里增加命令 `"build": "modern build"`：
+
+```json
+{
+    "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
+
+## 执行构建：
+pnpm build
+
+## 监听模式执行构建：
+pnpm build --watch
+
+## 启动 Storybook
+pnpm dev storybook
+
+## 测试
+pnpm test
+```
+> 上面的链接对应的内容待补充
+
+
+**如果你想要创建一个完整的模块工程项目，可以执行以下命令：**
+
+```bash
+npx @modern-js/create your-project-dir-name
+```
+
+接着在问题交互中，按照如下选择：
+
+```bash
+? 请选择你想创建的工程类型 模块
+? 请填写项目名称 library
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+> 项目名称为 `package.json` 中的 `"name"` 字段值。
+
+接着就会开始初始化项目的流程。在项目目录和文件生成以及依赖安装完毕后，此时就创建了一个完整的模块工程项目。
+
+我们可以直接执行 `pnpm build` 命令启动项目的构建，执行 `pnpm build --watch` 命令开启构建的观察模式。
+
+## 让我们开始吧
+
+选择适合你的教程：
+
+- 我是初学者，需要学习 Module Tools 的[基础使用](/zh/guide/before-getting-started)。
+- 我已经初步掌握了 Module Tools 的使用，可以学习 Module Tools 的[高级使用](/zh/guide/before-getting-started)。
+- 我是项目的维护者，需要学习如何开发 Module Tools 的插件以及了解更多关于 Module Tools 进阶的内容。

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

@@ -0,0 +1,14 @@
+# 欢迎使用
+
+Module Tools 是 Modern.js 的模块工程解决方案，同时也是核心依赖。它可以让开发者更轻松地构建、调试、发布模块类型的项目。模块类型的项目大多数情况可以认为是 npm 包类型的项目，它可能是一个组件、组件库或者工具库项目。
+
+如果你正打算开发一个 npm 包类型的项目，那么你就来对地方了！Modern.js 提供了专业的模块工程解决方案。它带来了：
+
+- **简单的项目初始化**：仅需执行 `npx @modern-js/create project-dir` 命令，然后进行几个交互问题，就可以创建一个完整的模块类型项目。创建的项目还支持选择 [**pnpm**](https://pnpm.io/)、[**Yarn**](https://classic.yarnpkg.com/) 两种包管理器。
+- **代码格式化**：在模块工程项目中，你可以执行 `modern lint` 来对代码进行格式化。同时初始化的模块工程项目里包含了 Modern.js 的 [ESLint](https://eslint.org/docs/latest/user-guide/core-concepts#what-is-eslint) 规则集，可以满足大部分场景下的需求。
+- **全面的构建能力和更快的构建速度**：Module Tools 基于 [esbuild](https://esbuild.github.io/getting-started/) 和 [SWC](https://swc.rs/) 提供了高性能的构建能力，并且为不同构建模块的场景提供了丰富的配置。
+- **Storybook 调试工具**：Module Tools 为调试模块项目提供了 [Storybook](https://storybook.js.org/) 调试工具。在安装了 Module Tools 的 Storybook 插件后，你可以使用 `modern dev storybook` 命令来启动它。你不仅可以使用 Storybook 对组件进行调试，也可以使用在其他类型的模块上。
+- **集成 Jest 的测试能力**：在需要对模块测试的时候，可以使用 Module Tools 的 `modern test` 命令。Module Tools 不仅集成了 [Jest](https://jestjs.io/)，同时也提供了配置 [Jest](https://jestjs.io/docs/configuration) 的 API。
+- **基于 Changesets 实现的版本管理**：当需要对项目记录变更内容的时候，可以使用 `modern change` 命令生成包含变更内容的 Markdown 文件；当需要对项目进行版本升级的时候，可以使用 `modern bump` 命令通过 Markdown 文件分析并升级版本；当需要发布项目的时候，可以使用 `modern release` 命令对项目进行发布。Module Tools 基于 [Changesets](https://github.com/changesets/changesets) 实现了这些命令。
+- **可扩展性的插件机制**：想要为项目集成其他的调试工具？又或者是想要在构建过程中做一些额外处理？Module Tools 提供了插件机制和插件钩子，插件钩子覆盖了 `dev` 命令和 `build` 命令两个流程。你可以通过它们为项目进行能力的扩展。
+- **还有更多**：Module Tools 在未来还会不断的在构建、调试功能上进行优化。如果在模块项目构建上存在需要解决的重要问题，又或者是某个主流的模块项目调试工具、模式出现的时候，那么它们很可能成为 Module Tools 将要支持功能。

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

@@ -0,0 +1,17 @@
+# 为什么需要模块工程解决方案
+
+大家可能都经历过：从零开始开发一个组件库或者工具库的过程中，我们不仅要考虑项目本身的代码逻辑如何编写，还要考虑项目的构建、调试、测试、代码格式化等等和代码逻辑无关的事情。
+
+比如说，当我们考虑构建模块项目的代码是使用什么构建工具的时候，在之前我们可能会考虑使用 [webpack](https://webpack.js.org/) 还是 [Rollup](https://rollupjs.org/guide/en/)，然而现在的话，也许还会考虑是使用 [esbuild](https://esbuild.github.io/) 还是 [SWC](https://swc.rs/)。
+
+无论选择哪个构建工具，这对于没有熟练掌握这些构建工具使用方式的开发者来说，是需要一定的成本去学习的。即使想要快速使用，也会需要花费大量的时间和精力。
+
+而除了构建这件事情以外，像为项目提供调试工具、支持测试能力、增加代码格式校验等等，对于一个新手来说都有可能需要花费很长的时间和精力了解或者掌握它们，并且真正的服务于当前的项目中。
+
+而为了保证代码质量以及项目的完整性，我们往往是需要做这些与代码逻辑实现无关的事情。然而这些事情很有可能会影响整体的项目开发进度，降低开发者的开发体验，会让开发者感觉模块项目的开发门槛很高。
+
+如果说每次开发一个模块类型的项目都需要经历一遍这些工作准备的话，那么基本上刚开始开发的时间会大部分花费在这些与代码实现无关的事情上。如果能够提供一个模块工程解决方案，它能够帮助开发者解决项目工程上的事情，让开发者可以更专注于代码的实现上，那么这将会大大提升模块类型项目的开发体验。
+
+![没有使用工程方案对比使用工程方案](/why-module-solution.png)
+
+Modern.js 为了让开发模块类型的项目更简单，为了解决上述提到的问题提供了模块工程解决方案，并且使用 Module Tools 提供了主要的功能。**Module-tools 可以理解为是一个专门用于模块类型项目开发的工具**。

package/docs/zh/index.md

@@ -0,0 +1,29 @@
+---
+pageType: home
+
+hero:
+  name: Module tools
+  text: 模块工程解决方案
+  tagline: 简单、强大、高性能的现代化npm包开发方案
+  actions:
+    - theme: brand
+      text: 欢迎使用
+      link: /zh/guide/intro/welcome
+
+features:
+  - title: 'Esbuild: 高性能的JS Bundler'
+    details: 基于 Esbuild 构建，构建速度极快，带给你极致的开发体验。
+    icon: 🚀
+  - title: 'Storybook: 社区流行的UI开发工具'
+    details: 集成了Storybook，你可以使用它调试UI。
+    icon: 📦
+  - title: 'transform + bundle'
+    details: 支持bundle和bundleless两种构建模式。
+    icon: ✨
+  - title: '零配置'
+    details: 无需任何配置即可开发你的npm包，内置预设覆盖多种场景。
+    icon: 🛠️
+  - title: '扩展性强: 提供强大的插件机制'
+    details: 通过其插件扩展机制，你可以轻松的扩展Module tools的各项能力。
+    icon: 🎨
+---

package/package.json

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