@modern-js/main-doc 2.0.0-beta.1 → 2.0.0-beta.3

package/zh/guides/get-started/quick-start.md

@@ -1,4 +1,202 @@
 ---
 title: 快速上手
-sidebar_position: 2
+sidebar_position: 1
 ---
+
+## 环境准备
+
+### Node.js
+
+需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 14.17.6。
+
+Modern.js 推荐在开发环境里先安装 [nvm](https://github.com/nvm-sh/nvm#install--update-script)，在 shell 里集成[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#deeper-shell-integration)。
+
+然后只要仓库根目录下有内容为 `lts/fermium` 或 `lts/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+:::
+
+## 安装
+
+Modern.js 提供了 `@modern-js/create` 生成器来创建项目，不要全局安装，使用 `npx` 按需运行。
+
+可以使用已有的空目录来创建项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+也可以直接用新目录创建项目：
+
+```bash
+npx @modern-js/create myapp
+```
+
+## 初始化项目
+
+Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+
+```bash
+? 请选择你想创建的工程类型 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
+
+```bash
+[INFO] 依赖自动安装成功
+[INFO] git 仓库初始化成功
+[INFO] 创建成功！
+可在新项目的目录下运行以下命令：
+pnpm run dev          # 按开发环境的要求，运行和调试项目
+pnpm run build        # 按产品环境的要求，构建项目
+pnpm run start        # 按产品环境的要求，运行项目
+pnpm run lint         # 检查和修复所有代码
+pnpm run new          # 继续创建更多项目要素，比如应用入口
+```
+
+:::note
+Modern.js 生成器除了在项目初始化时工作外，也能在后续研发中生成项目各种粒度的模块，并非一用即抛开。
+:::
+
+现在，项目结构如下：
+
+```
+.
+├── node_modules
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```
+
+## 启动项目
+
+在项目中执行 `pnpm run dev` 即可启动项目：
+
+```bash
+$ pnpm run dev
+
+> modern dev
+
+info    Starting dev server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.58.87:8080/
+  > Network:  http://10.254.68.105:8080/
+
+ Client ✔ done in 76.10ms
+```
+
+在浏览器中打开 `http://localhost:8000/`，能看到以下内容：
+
+![dev](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/dev.png)
+
+## 使用配置
+
+通过生成器创建的 Modern.js 项目中，存在 `modern.config.ts` 文件。
+
+可以通过配置文件来开启功能，或覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+});
+```
+
+重新执行 `pnpm run dev`，在浏览器 Network 菜单中，可以发现项目已经在服务端完成了页面渲染。
+
+## 构建项目
+
+在项目中执行 `pnpm run build` 即可构建项目生产环境产物：
+
+```bash
+$ pnpm run build
+
+> modern build
+
+info    Create a production build...
+
+info    File sizes after production build:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-corejs.ffeb7fb8.js     214.96 kB    67.23 kB
+  dist/static/js/lib-react.09721b5c.js      152.61 kB    49.02 kB
+  dist/static/js/218.102e2f39.js            85.45 kB     28.5 kB
+  dist/static/js/lib-babel.a7bba875.js      11.93 kB     3.95 kB
+  dist/html/main/index.html                 5.84 kB      2.57 kB
+  dist/static/js/main.3568a38e.js           3.57 kB      1.44 kB
+  dist/static/css/async/304.c3c481a5.css    2.62 kB      874 B
+  dist/asset-manifest.json                  1.48 kB      349 B
+  dist/static/js/async/304.c45706bc.js      1.4 kB       575 B
+  dist/static/js/async/509.fcb06e14.js      283 B        230 B
+
+ Client ✔ done in 3.57s
+ ```
+
+构建产物默认生成到 `dist/`，目录结构如下：
+
+```
+.
+├── asset-manifest.json
+├── html
+│   └── main
+├── loader-routes
+│   └── main
+├── modern.config.json
+├── route.json
+└── static
+    ├── css
+    └── js
+```
+
+## 本地验证
+
+在项目中执行 `pnpm run start` 即可在本地验证构建产物是否正常运行：
+
+```bash
+$ pnpm run start
+
+> modern start
+
+Starting the modern server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.58.87:8080/
+  > Network:  http://10.254.68.105:8080/
+```
+
+在浏览器中打开 `http://localhost:8000/`，内容应该和 `pnpm run dev` 时一致。
+
+## 部署
+
+本地验证完成后，可以将 `dist/` 下的产物整理成服务器需要的结构，进行部署。

package/zh/guides/get-started/upgrade.md

@@ -1,4 +1,78 @@
 ---
 title: 升级
-sidebar_position: 3
+sidebar_position: 2
 ---
+
+## 通过命令行升级
+
+Modern.js 提供了 `upgrade` 命令支持项目升级到最新的 Modern.js 版本。
+
+在项目中执行 `pnpm run upgrade`：
+
+```bash
+$ pnpm run upgrade
+
+> modern upgrade
+
+[INFO] [项目类型]: 应用
+[INFO] [Modern.js 最新版本]: 2.0.0
+[INFO] [当前项目 Modern.js 依赖已经为最新版本]: 2.0.0
+```
+
+可以看到项目 `package.json` 中的依赖已经更改到最新，执行 `pnpm install` 重新安装即可。
+
+## 指定版本升级
+
+Modern.js 所有的官方包目前都使用统一版本号进行发布。
+
+根据官网 Release Note，开发者也可以手动将项目升级到想要的版本。
+
+:::tip
+对所有 Modern.js 官方提供的包做统一升级，而不是升级单个依赖。
+:::
+
+## 锁定子依赖
+
+当项目某个子依赖出现问题，而 Modern.js 无法立即更新时，可以使用包管理器锁定子依赖版本。
+
+### Pnpm
+
+对于使用 Pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm i`：
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "package-name": "^1.0.0"
+    }
+  }
+}
+```
+
+### Yarn
+
+对于使用 Yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn i`：
+
+```json
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+### Npm
+
+对于使用 Npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm i`：
+
+```json
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+对于 Monorepo 仓库，只能在项目根目录的 `package.json` 中锁定依赖版本，并且会影响 Monorepo 中的所有 package。
+:::

package/zh/guides/topic-detail/framework-plugin/extend.md

@@ -1,10 +1,9 @@
 ---
-sidebar_position: 4
+title: 扩展插件 Hook
+sidebar_position: 5
 ---
 
-# 扩展插件 Hook
-
-本章节介绍如何通过动态注册 [Hook 模型](/docs/apis/app/runtime/plugin/hook#hook-模型) 的方式来扩展插件 Hook。
+本小节介绍如何通过动态注册 [Hook 模型](/docs/guides/topic-detail/framework-plugin/hook) 的方式来扩展插件 Hook。
 
 ## 示例
 

package/zh/{apis/app/runtime/plugin/hook-api.md → guides/topic-detail/framework-plugin/hook-list.md}

@@ -1,18 +1,13 @@
 ---
-sidebar_position: 5
+title: Hook 列表
+sidebar_position: 8
 ---
 
-# Hook API
+在 Modern.js 中暴露了三类插件：CLI、Runtime、Server。下面列举下各类中的 Hook：
 
-在 Modern.js 中主要构建了三套 Manager 模型：CLI、Runtime、Server，其中 CLI 是三套工程方案都有的，而 Runtime、Server 则是应用工程独有的，不同的工程方案中 Manager 模型的功能是不同的。
+## CLI
 
-## 基础
-
-这一部分的 Hook 模型是所有工程方案都有的，就是说在任意的工程方案中都可以在插件中添加实现对应的中间件函数。
-
-接下来对支持的所有基础 Hook 分别进行介绍。
-
-#### `config`
+### `config`
 
 - 功能：收集配置
 - 执行阶段：解析完 `modern.config.ts` 中的配置之后
@@ -38,7 +33,7 @@ export default (): CliPlugin => ({
 
 这里返回的配置信息，会被收集和统一处理合并。
 
-#### `validateSchema`
+### `validateSchema`
 
 - 功能：收集各个插件中配置的用来校验用户配置的 [JSON Schema](https://json-schema.org/)
 - 执行阶段：`config` Hook 运行完之后。
@@ -104,7 +99,7 @@ $ modern dev
     |   ^^^^^  Property foo is not expected to be here
 ```
 
-#### `prepare`
+### `prepare`
 
 - 功能：运行主流程的前置准备流程
 - 执行阶段：校验完配置之后
@@ -126,7 +121,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `commands`
+### `commands`
 
 - 功能：为 command 添加新的命令
 - 执行阶段：`prepare` Hook 运行完之后
@@ -168,7 +163,7 @@ $ modern foo
 foo
 ```
 
-#### `beforeExit`
+### `beforeExit`
 
 - 功能：在退出进程前，重置一些文件状态
 - 执行阶段：进程退出之前
@@ -190,17 +185,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-## 应用工程方案
-
-应用工程支持添加到项目中的插件主要有三种：CLI 插件、 Server 插件、Runtime 插件。他们是基于同一套插件系统实现的，但它们所支持的 Hook 不同、功能不同、运行的时机也不同。
-
-不同的 Manager 对应 Hook 模型和运行时机是不同的，所以接下来会对 CLI、Server、Runtime 的 Hook 模型分开讨论。
-
-### CLI
-
-应用工程中除了上面提到的基础的 CLI Hook 之外还有一些 MWA 场景下特定的 Hook。
-
-#### `beforeDev`
+### `beforeDev`
 
 - 功能：运行 dev 主流程的之前的任务
 - 执行阶段：`dev` 命令运行时，项目开始启动前执行
@@ -222,7 +207,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `afterDev`
+### `afterDev`
 
 - 功能：运行 dev 主流程的之后的任务
 - 执行阶段：`dev` 命令运行时，项目启动完成之后执行
@@ -244,7 +229,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `beforeCreateCompiler`
+### `beforeCreateCompiler`
 
 - 功能：在中间件函数中可以拿到创建 Webpack Compiler 的 Webpack 配置
 - 执行阶段：创建 Webpack Compiler 之前执行
@@ -266,7 +251,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `afterCreateCompiler`
+### `afterCreateCompiler`
 
 - 功能：在中间件函数中可以拿到创建的 Webpack Compiler
 - 执行阶段：创建 Webpack Compiler 之后执行
@@ -288,7 +273,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `beforePrintInstructions`
+### `beforePrintInstructions`
 
 - 功能：在中间件函数中可以拿到即将打印的日志信息，并对其进行修改
 - 执行阶段：打印日志信息之前执行
@@ -313,7 +298,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `beforeBuild`
+### `beforeBuild`
 
 - 功能：运行 build 主流程的之前的任务，可以拿到构建的 Webpack 配置
 - 执行阶段：`build` 命令运行时，项目构建启动前执行
@@ -335,7 +320,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `afterBuild`
+### `afterBuild`
 
 - 功能：运行 build 主流程的之后的任务
 - 执行阶段：`build` 命令运行时，项目构建完成之后执行
@@ -357,7 +342,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryImports`
+### `modifyEntryImports`
 
 - 功能：用于修改、添加生成入口文件中的 `import` 语句
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -389,7 +374,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryExport`
+### `modifyEntryExport`
 
 - 功能：用于修改生成入口文件中的 `export` 语句
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -416,7 +401,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryRuntimePlugins`
+### `modifyEntryRuntimePlugins`
 
 - 功能：用于添加、修改生成入口文件中的 [Runtime 插件](#Runtime)
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -451,7 +436,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyEntryRenderFunction`
+### `modifyEntryRenderFunction`
 
 - 功能：用于修改生成入口文件中 `render` 函数
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -477,7 +462,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyFileSystemRoutes`
+### `modifyFileSystemRoutes`
 
 - 功能：用于修改生成前端页面路由文件中的内容，内容都是需要可序列化的
 - 执行阶段：生成前端路由文件之前，[`prepare`](#prepare) 阶段触发
@@ -511,7 +496,7 @@ export default (): CliPlugin => ({
 
 这样就为前端新增了一个页面路由。
 
-#### `modifyServerRoutes`
+### `modifyServerRoutes`
 
 - 功能：用于修改生成服务器路由中的内容
 - 执行阶段：生成 Server 路由文件之前，[`prepare`](#prepare) 阶段触发
@@ -544,7 +529,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `modifyAsyncEntry`
+### `modifyAsyncEntry`
 
 - 功能：用于修改包裹入口文件的异步模块，参见 [source.enableAsyncEntry](/docs/configure/app/source/enable-async-entry)
 - 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
@@ -570,7 +555,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-#### `htmlPartials`
+### `htmlPartials`
 
 - 功能：用于定制生成的 HTML 页面模版
 - 执行阶段：[`prepare`](#prepare) 阶段触发
@@ -598,11 +583,15 @@ export default (): CliPlugin => ({
 
 这样就为 HTML 模版中新增了一个 Script 标签。
 
-### Server
+## Server
+
+:::note
+目前 Server 插件还未完全开放，API 不保证稳定，使用需谨慎。
+:::
 
 应用工程中的 Server 部分也支持了插件。其中的 Hook 将会提供一些特定阶段调用和特殊功能的 Hook。
 
-#### `create`
+### `create`
 
 - 功能：在中间件函数中会拿到 Server 初始化用到的指标测量工具配置 `measureOptions` 和日志工具配置 `loggerOptions`，并返回自定义的指标测量工具 `measure` 和日志工具配置 `logger`
 - 执行阶段：Server 初始化
@@ -624,7 +613,7 @@ export default (): ServerPlugin => ({
 });
 ```
 
-#### `prepareWebServer`
+### `prepareWebServer`
 
 - 功能：设置 Web 路由的处理函数，在中间件函数中可以拿到 Web Server 的前置中间件
 - 执行阶段：在请求到达的时候
@@ -650,7 +639,7 @@ export default (): ServerPlugin => ({
 });
 ```
 
-#### `prepareApiServer`
+### `prepareApiServer`
 
 - 功能：设置 API 路由的处理函数，在中间件函数中可以拿到 API Server 的前置中间件
 - 执行阶段：请求到达并且 match bff basename 之后执行
@@ -676,11 +665,15 @@ export default (): ServerPlugin => ({
 });
 ```
 
-### Runtime
+## Runtime
+
+:::note
+目前 Runtime 插件还未完全开放，API 不保证稳定，使用需谨慎。
+:::
 
 Runtime 插件主要用于开发者修改需要渲染的组件与 Element 和定制服务器端、客户端的渲染过程。
 
-#### `init`
+### `init`
 
 - 功能：执行 `App.init`
 - 执行阶段：渲染（SSR/CSR）
@@ -703,7 +696,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `hoc`
+### `hoc`
 
 - 功能：修改需要渲染的组件
 - 执行阶段：渲染（SSR/CSR）
@@ -735,7 +728,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `provide`
+### `provide`
 
 - 功能：修改需要渲染的 Element
 - 执行阶段：渲染（SSR/CSR）
@@ -758,7 +751,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `client`
+### `client`
 
 - 功能：定制客户端渲染流程
 - 执行阶段：在浏览器客户端渲染
@@ -784,7 +777,7 @@ export default (): Plugin => ({
 });
 ```
 
-#### `server`
+### `server`
 
 - 功能：定制服务器端渲染流程
 - 执行阶段：SSR
@@ -808,89 +801,3 @@ export default (): Plugin => ({
   },
 });
 ```
-
-## 模块工程方案
-
-模块工程方案用于开发可复用模块，主要提供编译构建的能力，插件方面则是主要提供了调整编译构建配置的 Hook。
-
-#### `moduleLessConfig`
-
-- 功能：用于设置 [Less](https://lesscss.org/) 文件的编译配置
-- 执行阶段：`build` 阶段
-- Hook 模型：AsyncPipeline
-- 类型：`AsyncPipeline<{ modernConfig: NormalizedConfig }, LessOption | undefined>`
-- 使用示例：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  setup(api) {
-    return {
-      moduleLessConfig: ({ modernConfig }) => {
-        // do something
-
-        return {
-          // LESS 配置
-        };
-      },
-    };
-  },
-});
-```
-
-#### `moduleSassConfig`
-
-- 功能：用于设置 [Sass](https://sass-lang.com/) 文件的编译配置
-- 执行阶段：`build` 阶段
-- Hook 模型：AsyncPipeline
-- 类型：`AsyncPipeline<{ modernConfig: NormalizedConfig }, SassOptions | undefined>`
-- 使用示例：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  setup(api) {
-    return {
-      moduleSassConfig: ({ modernConfig }) => {
-        // do something
-
-        return {
-          // SASS 配置
-        };
-      },
-    };
-  },
-});
-```
-
-#### `moduleTailwindConfig`
-
-- 功能：用于设置 [Tailwind CSS](https://tailwindcss.com/) 的相关配置
-- 执行阶段：`build` 阶段
-- Hook 模型：AsyncPipeline
-- 类型：`AsyncPipeline<{ modernConfig: NormalizedConfig }, any>`
-- 使用示例：
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export default (): CliPlugin => ({
-  setup(api) {
-    return {
-      moduleTailwindConfig: ({ modernConfig }) => {
-        // do something
-
-        return {
-          // Tailwind CSS 配置
-        };
-      },
-    };
-  },
-});
-```
-
-## Monorepo 工程方案
-
-Monorepo 工程方案中目前没有设置额外的插件 Hook，可以创建、添加拥有基础 Hook 的插件：[基础](#基础)。

package/zh/{apis/app/runtime/plugin → guides/topic-detail/framework-plugin}/hook.md

@@ -1,9 +1,8 @@
 ---
+title: Hook 模型
 sidebar_position: 2
 ---
 
-# Hook 模型
-
 首先介绍一下 Modern.js 的基础的插件系统中的一些内容，包括 Hook 模型的工作方式、各个 Hook 模型的运行模式、Manager 的工作模式。
 
 每种 Hook 模型都是独立的，可以独立管理运行函数。
@@ -167,4 +166,4 @@ workflow.run(5) // [6, 10]
 </div>
 </div>
 
-Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall ，但都较为麻烦，有许多隐形的约定，为了方便使用，提供了这两种变体来满足这种特殊场景。
+Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall，但都较为麻烦，有许多隐形的约定。为了方便使用，提供了这两种变体来满足这种特殊场景。