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

package/zh/guides/basic-features/routes.md

@@ -2,3 +2,270 @@
 title: 路由
 sidebar_position: 1
 ---
+
+Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**部分**支持，并提供了多种类型的路由模式。根据不同[入口](/docs/guides/concept/entries)类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**配置式路由**。
+
+:::note
+本小节提到的路由，都是客户端路由，即 SPA 路由。
+:::
+
+## 约定式路由
+
+以 `routes/` 为约定的入口，Modern.js 会自动基于文件系统，生成对应的路由结构。
+
+Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
+
+```
+/user/johnny/profile                  /user/johnny/posts
++------------------+                  +-----------------+
+| User             |                  | User            |
+| +--------------+ |                  | +-------------+ |
+| | Profile      | |  +------------>  | | Posts       | |
+| |              | |                  | |             | |
+| +--------------+ |                  | +-------------+ |
++------------------+                  +-----------------+
+```
+
+### 路由文件约定
+
+`routes/` 目录下有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整个路由表的叶子节点。
+
+例如，这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用：
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+当路由为 `/` 时，会有以下 UI 布局：
+
+```tsx
+<Layout>
+  <Page />
+</Layout>
+```
+
+同样，`routes/user/layout.tsx` 会作为 `/user` 路由下所有组件的布局组件使用。当路由为 `/user` 时， 会有以下 UI 布局：
+
+```tsx
+<Layout>
+  <UserLayout>
+    <UserPage>
+  <UserLayout>
+</Layout>
+```
+
+#### Layout
+
+`<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件，它们表示对应路由片段的布局，使用 `<Outlet>` 表示子组件。
+
+:::note
+`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+:::
+
+为了方便介绍 `<Layout>` 与 `<Outlet>` 的关系，以下面的文件目录举例：
+
+```bash
+.
+└── routes
+    ├── blog
+    │   └── page.tsx
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+1. 当路由为 `/` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/page.tsx` 中导出的组件，生成以下 UI 结构：
+
+```tsx
+<Layout>
+  <Page />
+</Layout>
+```
+
+2. 当路由为 `/blog` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/blog/page.tsx` 中导出的组件，生成以下 UI 结构：
+```tsx
+<Layout>
+  <BlogPage />
+</Layout>
+```
+
+3. 当路由为 `/user` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/layout.tsx` 中导出的组件。`routes/user/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/page.tsx` 中导出的组件。生成以下 UI 结构：
+
+```tsx
+<Layout>
+  <UserLayout>
+    <UserPage>
+  <UserLayout>
+</Layout>
+```
+
+总结而言，如果子路由的文件目录下存在 `layout.tsx`，上一级 `layout.tsx` 中的 `<Outlet>` 即为子路由文件目录下的 `layout.tsx` ，否则为子路由文件目录下的 `page.tsx`。
+
+#### Page
+
+所有的路由，理论上都应该由 `<Page>` 组件结束。在 `page.tsx` 文件内，如果开发者引入 `<Outlet>` 组件，不会有任何效果。
+
+### 动态路由
+
+通过 `[]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
+
+在组件中，可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
+
+### 无路径布局
+
+当目录名以 __ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
+
+```
+.
+└── routes
+    ├── __auth
+    │   ├── layout.tsx
+    │   ├── login
+    │   │   └── page.tsx
+    │   └── signup
+    │       └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组件会作为 `login/page.tsx` 和 `signup/page.tsx` 的布局组件，但__auth 不会作为路由路径片段。
+
+当需要为某些类型的路由，做独立的布局，或是想要将路由做归类时，这一功能非常有用。
+
+### 无布局路径
+
+有些情况下，项目需要较为复杂的路由，但这些路由又不存在独立的 UI 布局，如果像普通文件目录那边创建路由会导致目录层级较深。
+
+因此 Modern.js 支持了通过 `.` 来分割路由片段，代替文件目录。例如，当需要 `/user/profile/2022/edit` 时，可以直接创建如下文件：
+
+```
+└── routes
+    ├── user.profile.[id].edit
+    │      └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+访问路由时，将得到如下 UI 布局：
+
+```tsx
+<RootLayout>
+   <UserProfileEdit />   // routes/user.profile.[id].edit/page.tsx
+</RootLayout>
+```
+
+### Loading
+
+`routes/` 下每一层目录中，开发者可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
+
+当路由目录下存在该组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为 JS Chunk 加载时的 Fallback UI。当该目录下未定义 `layout.tsx` 文件时，`<Loading>` 组件不会生效。例如以下文件目录：
+
+```bash
+.
+└── routes
+    ├── blog
+    │   ├── [id]
+    │   │   └── page.tsx
+    │   └── page.tsx
+    ├── layout.tsx
+    ├── loading.tsx
+    └── page.tsx
+```
+
+当路由从 `/` 跳转到 `/blog` 时，如果 `<Blog>` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。但从 `/blog` 跳转到 `/blog/20220101` 时，则不会展示。
+
+### 错误处理
+
+`routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。
+
+当有路由目录下存在该组件时，组件渲染出错会被 ErrorBoundary 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
+
+`<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
+
+<!-- Todo API 路由-->
+在 `<ErrorBoundary>` 组件内，可以使用 [useRouteError](/docs/apis/app/runtime/router/#useparams) 获取的错误的具体信息：
+
+```tsx
+import { useRouteError } from '@modern-js/runtime/router';
+export default const ErrorBoundary = () => {
+  const error = useRouteError();
+  return (
+    <div>
+        <h1>{error.status}</h1>
+        <h2>{error.message}</h2>
+    </div>
+  )
+}
+```
+
+## 自控式路由
+
+以 `routes/` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发。
+
+例如：
+
+```tsx
+import {
+  Route,
+  Routes,
+  BrowserRouter,
+  Outlet,
+} from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <div>
+      <BrowserRouter>
+        <Routes>
+          <Route index element={<div>index</div>} />
+          <Route
+            path="user"
+            element={
+              <div>
+                User Layout
+                <Outlet />
+              </div>
+            }
+          >
+            <Route index element={<div>user</div>} />
+            <Route path="profile" element={<div>profile</div>} />
+          </Route>
+          <Route path="about" element={<div>about</div>} />
+        </Routes>
+      </BrowserRouter>
+    </div>
+  );
+};
+```
+
+:::note
+在自控式路由下，开发者如果希望在 SSR 中使用 React Router 6 中 [Loader API](https://reactrouter.com/en/main/hooks/use-loader-data#useloaderdata) 的能力会相对复杂，推荐直接使用约定式路由。Modern.js 已经为你封装好了一切。
+
+<!-- Todo 嵌套路由带来的优化可以补充下文档-->
+如果项目只想升级到 React Router 6，而不希望使用嵌套路由带来的优化，那[useLoader](/docs/apis/app/runtime/core/use-loader) 在 SSR 下仍然可以工作。
+:::
+
+## 配置式路由
+
+:::note
+敬请期待
+:::

package/zh/guides/concept/entries.md

@@ -2,3 +2,115 @@
 title: 入口
 sidebar_position: 2
 ---
+
+入口是 Modern.js 默认的文件约定，项目的每一个入口是一张独立的页面，对应一条服务端路由。
+
+很多配置，如 HTML 模板、Meta 信息、是否开启 SSR、SSG、服务端路由规则都是以入口为维度划分的。
+
+## 单入口与多入口
+
+Modern.js 初始化的项目是单入口的，项目结构如下：
+
+```
+.
+├── node_modules
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── package.json
+├── modern.config.ts
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```
+
+Modern.js 可以很方便的将单入口切换成多入口。可以在项目下执行 `pnpm run new`，通过生成器创建入口：
+
+```bash
+? 请选择你想要的操作： 创建工程元素
+? 创建工程元素： 新建「应用入口」
+? 请填写入口名称： new-entry
+```
+
+执行后，`src/` 目录将会变成如下结构：
+
+```
+.
+├── modern-app-env.d.ts
+├── myapp
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── new-entry
+    └── routes
+        ├── index.css
+        ├── layout.tsx
+        └── page.tsx
+```
+
+原本的代码被移动到了和 `package.json` 中 `name` 同名的目录下，并创建了新的目录。
+
+执行 `pnpm run dev` 后，可以看到新增一条 `/new-entry` 的路由，并且被迁移的代码路由并未发生变化。
+
+:::note
+Modern.js 会将和 `package.json` 中 `name` 同名的目录作为主入口，默认路由为 `/`，其他入口默认路由为 `/{entryName}`。
+:::
+
+## 入口条件
+
+默认情况下，Modern.js 启动项目前会对 `src/` 下的文件进行扫描，识别入口，并生成对应的服务端路由。
+
+:::tip
+可以通过 [source.entriesDir](/docs/configure/app/source/entries-dir) 更改入口目录为其他目录。
+:::
+
+并非 `src/` 下所有的一级目录都会成为项目入口, 入口所在目录必须满足以下四个条件之一：
+
+1. 具有 `routes/` 目录
+2. 具有 `App.[jt]sx?` 文件
+3. 具有 `index.[jt]sx?` 文件
+2. 具有 `pages/` 目录（兼容旧版本）
+
+当 `src/` 目录满足入口特征时，Modern.js 会认为当前项目为单入口应用。
+
+:::tip
+单入口默认的入口名为 `main`。
+:::
+
+当项目不是单入口应用时，Modern.js 会进一步查看 `src/` 下的一级目录。
+
+## 入口的区别
+
+不同约定的入口具有不同的行为。
+
+### routes 入口
+
+如果入口为 `routes/` 约定，Modern.js 会在启动时扫描 `routes` 下的文件，基于文件约定，自动生成客户端路由（react-router）。
+
+详细内容可以参考[路由](/docs/guides/basic-features/routes).
+
+### App 入口
+
+如果入口为 `App.[jt]sx?` 约定，开发者可以在这个文件中自由的设置客户端路由，或者不设置客户端路由。
+
+详细内容可以参考[路由](/docs/guides/basic-features/routes).
+
+### Index 入口
+
+通常情况下，上面两种模式已经能满足需求，但当开发者需要自己接管 React 挂载逻辑，或完全接管 Webpack 入口时，可以使用 `index.[jt]sx?` 约定。
+
+如果入口为 `index.[jt]sx?` 约定，Modern.js 会根据该文件是否存在默认的组件导出，来决定构建行为。
+
+详细内容可以参考[自定义 App](/docs/guides/advanced-features/custom-app).
+
+## 配置入口
+
+在 Modern.js 中，除了使用文件约定生成入口外，还可以在 `modern.config.[jt]s` 中手动配置入口。
+
+:::tip
+详情可以查看 [source.entries](/docs/configure/app/source/entries).
+:::

package/zh/guides/concept/lifecycle.md

@@ -2,3 +2,13 @@
 title: 生命周期
 sidebar_position: 1
 ---
+
+Modern.js 应用具有完整的生命周期，包括 CLI、Server Side 和 Runtime 三个阶段。
+
+目前 Modern.js 大致的生命周期如下：
+
+:::note
+其中粉色框的矩形代表 Modern.js 提供的插件钩子，淡黄色底色椭圆代表与下一个阶段的连接点。
+:::
+
+![lifecycle](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/life-cycle.svg)

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/generator/codesmith/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "API",
+  "position": 5
+}