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

package/zh/guides/basic-features/env-vars.md

@@ -3,9 +3,99 @@ title: 环境变量
 sidebar_position: 7
 ---
 
+Modern.js 提供了对环境变量的支持，包含内置的环境变量和自定义的环境变量。
+
+## 内置的环境变量
+
+### NODE_ENV
+
+表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
+
+- `production`：执行 `modern build`、`modern preview` 命令时的默认值。
+- `test`：执行 `modern test` 命令时的默认值。
+- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+
+### MODERN_ENV
+
+手动设置当前的执行环境。除了上述 NODE_ENV 对应的值之外，这里支持自定义环境名称，例如 `staging`、`boe` 等。
+
+:::tip
+MODERN_ENV 的优先级高于 NODE_ENV。
+:::
+
+### MODERN_TARGET
+
+使用 `@modern-js/runtime` 时会自动注入，用于区分 SSR 与 CSR 环境。开发者可以自行在代码中判断，构建时会默认移除 dead code。
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  };
+};
+```
+
+开发环境打包后，可以看到 SSR 产物和 CSR 产物如下：
+
+```js title="dist/bundles/main.js"
+function App() {
+  if (false) {}
+}
+```
+
+```js title="dist/static/main.js"
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+:::note
+在生产环境，会将 dead code 移除，例如上述 `if` 语句。
+:::
+
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化。也能方便处理不同环境下，代码中的一些副作用，
+
+## 自定义环境变量
+
+环境变量支持通过 `shell` 和 `.env` 文件两种方式指定。
+
+### 通过 `shell` 指定
+
+在命令前添加自定义环境变量：
+
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+
+### 通过 `.env` 文件指定
+
+在项目根目录创建 `.env` 文件，并添加自定义环境变量，这些环境变量会默认添加到启动项目的 Node.js 进程中，例如：
+
+```env
+REACT_APP_FOO=123
+BAR=456
+```
+
+`.env` 文件遵循以下规则加载规则：
+
+* `.env`：默认加载。
+* `.env.{ MODERN_ENV | NODE_ENV }`：针对具体环境设置环境变量，会覆盖 `.env` 中的设置。
+
+当需要根据环境使用不同的配置时，可以把环境变量定义到对应环境名称的 `.env` 文件中，并在启动项目时手动设置执行环境。例如使用以下命令启动项目时，将会加载 `.env` 和 `.env.staging`:
+
+```shell
+MODERN_ENV=staging pnpm run dev
+```
+
 ## 使用环境变量
 
-默认情况下，在前端代码中可以直接使用 `NODE_ENV` 环境变量，如下:
+### 约定命名
+
+在前端代码中可以直接使用 `NODE_ENV` 环境变量。另外，以 `MODERN_` 开头的自定义环境变量，也可以在代码中直接使用。
+
+例如:
 
 ```js
 if (process.env.NODE_ENV === 'development') {
@@ -13,7 +103,7 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
-执行 `dev` 命令之后可以看到构建产物如下:
+执行 `pnpm run dev` 命令之后可以看到如下构建产物:
 
 ```js
 if (true) {
@@ -21,62 +111,53 @@ if (true) {
 }
 ```
 
-同样在自定义的 HTML 模板中，也可以直接使用环境变量。如 `config/html/head.html`:
+同样在自定义的 HTML 模板中，也可以直接使用这类环境变量。如 `config/html/head.html`:
 
 ```js
 <meta name="test" content="<process.env.NODE_ENV>">
 ```
 
-如果想在代码中使用除 `NODE_ENV` 以外的环境变量，可以在 [`source.define`](/docs/configure/app/source/define) 配置指定, 如下:
+### 任意命名
+
+如果需要在代码中使用任意名称的环境变量，可以在 [`source.globalVars`](/docs/configure/app/source/global-vars) 配置指定, 例如:
+
 ```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
-    envVars: ['VERSION']
-  }
-})
-```
-
-`VERSION` 环境变量需要在编译之前设置好, 可以在执行命令时添加:
-
-```bash
-// linux, macOS
-$ VERSION=1.0.0 npm run dev
-
-// windows
-$ set VERSION=1.0.0&&npm run dev
-```
-
-Modern.js 也支持在 `.env` 文件中定义环境变量：
-
-```js title=".env"
-VERSION=1.0.0
+    globalVars: {
+      'process.env.VERSION': process.env.VERSION,
+    }.
+  },
+});
 ```
 
-更多文件格式：
+此时，在代码中的 `process.env.VERSION`，将会被替换为环境变量中 `VERSION` 的值。
 
-* `.env`：默认加载。
-* `.env.development`、`.env.test`、`.env.production`：针对具体环境设置环境变量，会覆盖 `.env` 中的设置。
+:::note
+`source.globalVars` 也支持将其他表达式或字符串替换为指定的值，不仅限于环境变量。
+:::
 
+## 使用全局替换
 
-## 使用全局变量
+除了环境变量，Modern.js 也支持将代码中的变量替换成其它值或者表达式，可以用于在代码逻辑中区分开发环境与生产环境等场景。
 
-Modern.js 支持在编译时设置代码中使用到的全局变量:
+例如将代码中的 `TWO` 转换为 `1 + 1` 的表达式：
 
-```typescript title="modern.config.ts"
-export default defineConfig({
+```ts
+export default {
   source: {
-    globalVars: {
-      VERSION: '1.0.0'
-    }
-  }
-})
+    define: {
+      TWO: '1 + 1',
+    },
+  },
+};
 ```
 
-在代码中可以直接使用:
+```ts
+const foo = TWO;
 
-```ts title="App.tsx"
-/* TS 应用中，需要声明该变量 */
-declare const VERSION: string;
-
-const a = VERSION;
+// ⬇️ Turn into being...
+const foo = 1 + 1;
 ```
+
+在大多数情况下，`source.globalVars` 已经能满足替换变量的需求。但 `source.globalVars` 传入的值都会默认被 JSON 序列化，因此无法做出像上面例子中 `1 + 1` 的替换，此时就需要使用 [`source.define`](/docs/configure/app/source/define)。

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

@@ -2,3 +2,267 @@
 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>
+  )
+}
+```
+
+## 自控式路由
+
+以 `src/App.tsx` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发，例如：
+
+```tsx
+import { Route, Routes, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+export default () => {
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+:::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 下仍然可以工作。
+:::
+
+## 其他路由方案
+
+默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
+
+```js
+export default defineConfig({
+  runtime: {
+    router: true,
+  }
+})
+```
+
+Modern.js 从 `@modern-js/runtime/router` 命名空间暴露了 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
+
+```js
+export default defineConfig({
+  runtime: {
+    router: false,
+  }
+})
+```

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)