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

package/zh/guides/advanced-features/bff/index.md

@@ -0,0 +1,20 @@
+---
+title: BFF
+---
+
+在**前后端分离**概念出现后一段时间发展中，前端部分能够做的事越来越多，前端需要一些面向 UI 的数据接口，因此业界引入了 BFF（Backends for Frontends）这一概念。
+
+它主要为了解决的问题包括：
+
+* 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
+* 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
+* 根据已有接口快速开发新产品。
+* 与第三方系统对接，例如登陆鉴权。
+
+Modern.js 官方支持了 BFF，并提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
+
+* 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
+* 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
+* 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
+* 完善的 TypeScript 支持。
+* 满足用户使用偏好，支持多框架扩展写法。

package/zh/guides/advanced-features/bff/type.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+title: 函数写法 & 框架写法
+---
+
+运行时框架支持也是 **BFF** 中重要的一环。Modern.js 支持通过插件扩展 BFF 的运行时框架，并提供了一系列内置插件，开发者可以直接使用对应框架的约定和生态。
+
+插件中兼容了这些框架大部分的规范，每一种框架都需要提供两类扩展写法 BFF 函数的方式，分别是**函数写法**和**框架写法**。
+
+:::note
+当前 `api/` 目录结构是否为框架写法由对应的插件决定，Modern.js 并不关心。
+:::
+
+## 函数写法
+
+当插件认为当前为函数写法时，必须支持在 `api/_app.ts` 中编写中间件，用来扩展 BFF 函数。
+
+Modern.js 会收集 `api/_app.ts` 中的中间件，并传递给插件，由插件将中间件注入运行时，例如：
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(myMiddleware);
+});
+```
+
+:::note
+不同插件的中间件的写法不一定相同，详情可见[运行时框架](/docs/guides/advanced-features/bff/frameworks)。
+:::
+
+## 框架写法
+
+框架写法是一种使用框架结构来扩展 BFF 函数的方式。和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
+
+框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
+
+多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时，才需要使用框架写法。
+
+:::note
+不同插件框架写法的目录结构不一定相同，详情可见[运行时框架](/docs/guides/advanced-features/bff/frameworks)。
+:::
+

package/zh/guides/advanced-features/custom-app.md

@@ -1,4 +1,66 @@
 ---
-title: 自定义入口
+title: 自定义 App
 sidebar_position: 7
 ---
+
+在[入口](/docs/guides/concept/entries)概念中提到， Modern.js 提供了三种文件约定来标记入口。
+
+通常情况下，`routes/` 与 `App.[jt]sx` 两种模式已经能够满足需求。当开发者需要在根组件挂载前做些操作，或者完全接管 Webpack 入口时，可以在入口目录下放置 `index.[jt]sx` 文件，我们称为**自定义 App**。
+
+## 添加自定义行为
+
+当 `index` 文件默认导出**函数**是，Modern.js 还是会根据 `runtime.features` 的设置情况生成 `createApp` 包裹后的代码。在渲染过程中，将 `createApp` 包裹后的组件作为参数传递给 `index` 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+
+```js title=src/index.jsx
+import { bootstrap } from '@modern-js/runtime';
+
+export default App => {
+  // do something before bootstrap...
+  bootstrap(App, 'root');
+};
+```
+
+Modern.js 生成的文件内容如下：
+
+```js
+import customRender from '@/src/index.js';
+import { createApp, bootstrap } from '@modern-js/runtime';
+import React from 'react';
+import App from '@/src/App';
+
+const IS_BROWSER = typeof window !== 'undefined';
+const MOUNT_ID = 'root';
+
+let AppWrapper = null;
+
+const renderApp = () => {
+  AppWrapper = createApp({
+    // runtime 的插件参数...
+  })(App);
+  customRender(AppWrapper);
+};
+
+renderApp();
+
+export default AppWrapper;
+
+if (IS_BROWSER && module.hot) {
+  module.hot.accept('<path>/src/App', () => {
+    renderApp();
+  });
+}
+```
+
+## 完全接管 Webpack 入口
+
+当 `index.[jt]sx` 文件没有导出函数时，这时候该文件就是真正的 Webpack 入口文件。这里和 [Create React App](https://github.com/facebook/create-react-app) 类似，需要自己将组件挂载到 DOM 节点、添加热更新代码等。例如:
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```
+
+Modern.js **不推荐**使用这种方式，这种方式丧失了框架的一些能力，如 **`modern.config.js` 文件中的 `runtime` 配置将不会再生效**。

package/zh/guides/advanced-features/web-server.md

@@ -1,135 +1,46 @@
 ---
-title: 扩展 Web Server
+title: 自定义 Web Server
 sidebar_position: 2
 ---
 
-有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等，这时，可以通过对 Modern.js 内置的 Web Server 进行扩展实现相应需求。
+Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。
 
-## 创建定制 Web Server
+因此 Modern.js 提供了一种功能，让项目可以在给定的范围内扩展 Modern.js 内置的 Web Server，来实现相应的需求。
 
+## 创建自定义 Web Server
 
-在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「Server 自定义」功能：
-
+在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「自定义 Web Serve」功能：
 
 ```bash
 ? 请选择你想要的操作： 创建工程元素
-? 创建工程元素： 新建「Server 自定义」源码目录
-? 请选择运行时框架： Express/Koa/Egg/Nest
+? 创建工程元素： 新建「自定义 Web Server」源码目录
 ```
 
-目前 Modern.js 默认支持 4 种主流的 Node.js Server 框架：[Express](https://expressjs.com/)、[Koa](https://koajs.com/)、[Egg.js](https://eggjs.org/zh-cn/)、[Nest](https://nestjs.com/)，选择运行时框架时，可根据自身偏好进行选择。
-
 执行命令后，项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
 
-## 框架差异
+## 使用 API 扩展 Web Server
 
-由于不同框架 API 的差异性，自定义逻辑的写法也有所不同。假设有以下场景：当请求的 cookies 中包含 `login-token` 时，认为用户已登录，正常返回页面；否则返回 404 状态码。下面就以此场景为例，演示不同框架下如何实现定制 Web Server 逻辑。
+Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
 
-:::info 注
-目前 Modern.js 只支持前置中间件的扩展。
-:::
+### Hook
 
-### Express
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-import type { Request, Response, NextFunction } from 'express';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware((request: Request, response: Response, next: NextFunction) => {
-    if (request.headers.cookies['login-token']) {
-      return next();
-    } else {
-      response.status = 401;
-      response.end();
-    }
-  });
-});
-```
+Hook 可以控制 Web Server 对请求处理的内置逻辑，非 BFF 请求会经过 Hook 的处理。
 
-### Koa
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-import type { Context, Next } from 'koa';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx: Context, next: Next) => {
-    if (ctx.cookies['login-token']) {
-      await next();
-    } else {
-      ctx.status = 401;
-    }
-  });
-});
-```
+Hook 不可以使用运行时框架拓展。
 
-### Egg
+详细 API 可以查看 [Hook](/docs/apis/app/runtime/web-server/hook)。
 
-Egg 添加中间件的方式与 Koa 相同。
 
-```ts
-import { hook } from '@modern-js/runtime/server';
-import type { Context, Next } from 'koa';
+### Middleware
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx: Context, next: Next) => {
-    if (ctx.cookies['login-token']) {
-      await next();
-    } else {
-      ctx.status = 401;
-    }
-  });
-});
-```
+Middleware 可以为 Web Server 添加前置中间件，只有 SSR 请求会经过 Middleware 的处理。
 
-### Nest
-
-Nest 支持添加两种类型的内容：Express 的函数中间件和 Nest 中的 [Module](https:/docs.nestjs.com/modules)。
-
-Express 的函数中间件的添加与 Express 部分的示例相同，同时这里使用 Module 来为 Web Server 添加一条新的路由。
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-import { Module, Injectable, Controller, Get } from '@nestjs/common';
-
-@Controller('cats')
-export class CatsController {
-  constructor(private readonly catsService: CatsService) {}
-
-  @Get()
-  getHello() {
-    return this.catsService.getHello();
-  }
-}
-
-@Injectable()
-class CatsService {
-  getHello(): string {
-    return '<div>Hello world!</div>';;
-  }
-}
-
-@Module({
-  controllers: [CatsController],
-  providers: [CatsService],
-})
-class CatsModule {}
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware((request: Request, response: Response, next: NextFunction) => {
-    if (request.headers.cookies['login-token']) {
-      return next();
-    } else {
-      response.status = 401;
-      response.end();
-    }
-  });
-
-  addMiddleware(CatsModule);
-});
-```
+Middleware 可以使用运行时框架拓展。
+
+详细 API 可以查看 [Hook](/docs/apis/app/runtime/web-server/middleware)。
+
+## 完全自定义的 Web Server
 
-:::info 注
-Modern.js 中 Web Server 与应用是一体的，在开发调试、生产部署阶段都无需单独运维。
+:::note
+敬请期待
 :::

package/zh/guides/basic-features/data-fetch.md

@@ -2,3 +2,64 @@
 title: 数据获取
 sidebar_position: 2
 ---
+
+Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在 CSR 和 SSR 环境同构的进行开发。
+
+需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好的管理数据与路由的关系。
+
+## useLoader（旧版）
+
+**`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。
+
+:::tip
+CSR 的项目没有必要使用 `useLoader` 获取数据。
+:::
+
+以下是一个最简单的例子：
+
+```tsx
+import { useLoader } from '@modern-js/runtime';
+
+export default () => {
+  const { data } = useLoader(async () => {
+    console.log('fetch in useLoader');
+
+    // 这里没有发送真实的请求，只是返回了一个写死的数据。
+    // 真实项目中，应该返回从远端获取的数据。
+    return {
+      name: 'modern.js',
+    };
+  });
+
+  return <div>Hello, {data?.name}</div>;
+};
+```
+
+上述代码启动后，访问页面。可以看到在终端输出了日志，而在浏览器终端却没有打印日志。
+
+这是因为 Modern.js 在服务端渲染时，在会收集 `useLoader` 返回的数据，并将数据注入到响应的 HTML 中。如果 SSR 渲染成功，在 HTML 中可以看到如下代码片段：
+
+```html
+<script>
+window._SSR_DATA = {};
+</script>
+```
+
+在这全局变量中，记录了每一份数据，而在浏览器端渲染的过程中，会优先使用这份数据。如果数据不存在，则会重新执行 `useLoader` 函数。
+
+:::note
+在构建阶段，Modern.js 会自动为每个 `useLoader` 生成一个 Loader ID，并注入到 SSR 和 CSR 的 JS Bundle 中，用来关联 Loader 和数据。
+:::
+
+相比于 Next.js 中的 `getServerSideProps`，在渲染前预先获取数据。使用 `useLoader`，可以在组件中获取局部 UI 所需要的数据，而不用将数据层层传递。同样，也不会因为不同路由需要不同数据请求，而在最外层的数据获取函数中添加冗余的逻辑。当然 `useLoader` 也存在一些问题，例如服务端代码 Treeshaking 困难，服务端需要多一次预渲染等。
+
+Modern.js 在新版本中，设计了全新的 Loader 方案。新方案解决了这些问题，并能够配合**嵌套路由**，对页面性能做优化。
+
+:::note
+详细 API 可以查看 [useLoader](/docs/apis/app/runtime/core/use-loader)。
+:::
+## Route Loader
+
+:::note
+敬请期待
+:::

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

@@ -3,9 +3,65 @@ 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。
+:::
+
+## 自定义环境变量
+
+环境变量支持通过 `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 +69,7 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
-执行 `dev` 命令之后可以看到构建产物如下:
+执行 `pnpm run dev` 命令之后可以看到如下构建产物:
 
 ```js
 if (true) {
@@ -21,62 +77,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)。