@modern-js/main-doc 2.6.0 → 2.8.0

package/zh/apis/app/hooks/config/upload.mdx

@@ -26,13 +26,23 @@ sidebar_position: 4
 
 ## 更多用法
 
-不论是在[自定义 HTML](/guides/basic-features/html) 中，或是在 [`config/public/`](/apis/app/hooks/config/public) 下的任意 HTML 文件中，都可以直接使用 HTML 标签引用 `config/upload/` 目录下的资源：
+在 React 组件中，可以通过[内置环境变量](/guides/basic-features/env-vars.html#asset_prefix)来添加该前缀：
+
+```tsx
+export default () => {
+  return (
+    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
+  );
+};
+```
+
+另外，不论是在[自定义 HTML](/guides/basic-features/html) 中，或是在 [`config/public/`](/apis/app/hooks/config/public) 下的任意 HTML 文件中，都可以直接使用 HTML 标签引用 `config/upload/` 目录下的资源：
 
 ```html
 <script src="/upload/index.js"></script>
 ```
 
-如果设置了 [`output.assetPrefix`](/configure/app/output/asset-prefix) 前缀，也可以直接使用模板语法添加该前缀：
+如果设置了 [`dev.assetPrefix`](/configure/app/dev/asset-prefix) 或 [`output.assetPrefix`](/configure/app/output/asset-prefix) 前缀，也可以直接使用模板语法添加该前缀：
 
 ```html
 <script src="<%=assetPrefix %>/upload/index.js"></script>

package/zh/apis/app/runtime/model/connect.mdx

@@ -9,7 +9,7 @@ import ReduckTip from "@site-docs/components/reduck-tip"
 <ReduckTip />
 
 :::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**connect**](https://github.com/modern-js-dev/reduck/blob/main/packages/react/src/connect.ts)。
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**connect**](https://github.com/web-infra-dev/reduck/blob/main/packages/react/src/connect.ts)。
 
 :::
 

package/zh/apis/app/runtime/model/model_.mdx

@@ -9,7 +9,7 @@ import ReduckTip from "@site-docs/components/reduck-tip"
 <ReduckTip />
 
 :::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/model.ts)。
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/model.ts)。
 
 :::
 

package/zh/apis/app/runtime/model/use-model.mdx

@@ -9,7 +9,7 @@ import ReduckTip from "@site-docs/components/reduck-tip"
 <ReduckTip />
 
 :::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/useModel.ts)。
+Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/useModel.ts)。
 
 :::
 

package/zh/apis/app/runtime/web-server/hook.mdx

@@ -3,11 +3,10 @@ title: Hook
 ---
 # Hook
 
-用于拓展 Modern.js 内置的 Web Server，非 BFF 请求会经过这些中 Hook 的处理。
+用于拓展 Modern.js 内置的 Web Server，所有的页面请求都会经过 Hook。
 
 :::note
 更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
-
 :::
 
 ## 使用姿势
@@ -27,7 +26,6 @@ pnpm run new
 ? 请选择你想要的操作 创建工程元素
 ? 新建「自定义 Web Server」源码目录
 ```
-
 :::
 
 ## 函数签名
@@ -64,7 +62,7 @@ type HookContext = {
 function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
 ```
 
-另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AtferMatch` 和 `AfterRender` 两个 Hook。
+另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AfterMatch` 和 `AfterRender` 两个 Hook。
 
 ```ts
 type AfterMatchContext = HookContext & {

package/zh/apis/app/runtime/web-server/middleware.mdx

@@ -3,13 +3,10 @@ title: Middleware
 ---
 # Middleware
 
-用于拓展 Modern.js 内置的 Web Server，只有 SSR 请求会经过这些中间件。
-
-与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以使用 Server 运行时框架拓展。
+用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
 
 :::note
 更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
-
 :::
 
 ## 使用姿势
@@ -38,6 +35,11 @@ pnpm run new
 ## 函数签名
 
 ```ts
+type Middleware = (
+  context: MiddlewareContext,
+  next: NextFunction,
+) => Promise<void> | void;
+
 type MiddlewareContext = {
   response: {
     set: (key: string, value: string) => void;
@@ -71,11 +73,6 @@ type MiddlewareContext = {
     res: ServerResponse;
   };
 };
-
-type RequestHandler = (
-  context: Context,
-  next: NextFunction,
-) => Promise<void> | void;
 ```
 
 ### 参数
@@ -86,6 +83,10 @@ type RequestHandler = (
   - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
 - `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
 
+:::warning
+`next` 函数的执行不影响后续内置流程，只控制下一个中间件是否执行。只有当响应被写入时，后续渲染流程才会中断。
+:::
+
 ## 示例
 
 ### 服务端耗时打点
@@ -107,5 +108,24 @@ Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量
 export const Middleware = () => async (ctx, next) => {
   ctx.res.locals.id = 'Modern.js';
   ctx.res.locals.rpc = createRpcInstance();
-});
+};
 ```
+
+### 框架拓展
+
+Middleware 还可以和 BFF 一样，使用运行时框架拓展。Modern.js 约定，当使用框架运行时拓展时，类型信息从 `@modern-js/runtime/{namespace}` 下导出，Middleware 可以使用框架语法，例如框架中间件写法，以下是伪代码：
+
+```ts
+import { SomeType } from '@modern-js/runtime/{namespace}';
+
+export const middleware: SomeType = (ctx, next) => {
+  console.log(ctx.url);
+  next();
+};
+```
+
+默认情况下，在安装框架拓展插件后，Web Server 的框架拓展能力是关闭的。如果希望使用框架拓展，可以通过 [`server.enableFrameworkExt`](/configure/app/server/enable-framework-ext.html) 开启。
+
+:::info
+框架拓展导出的类型名不一定为 Middleware，命名由框架拓展插件。
+:::

package/zh/apis/monorepo/commands/gen-release-note.mdx

@@ -9,7 +9,7 @@ Usage: modern gen-release-note [options]
 根据当前仓库 changeset 文件生成 Release Note
 
 Options:
-  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： modern-js-dev/modern.js
+  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： web-infra-dev/modern.js
   --custom <cumtom>  自定义 Release Note 生成函数
   -h, --help         display help for command
 ```
@@ -24,9 +24,9 @@ Options:
 ```markdown
 ## Features:
 
-[[#1160](https://github.com/modern-js-dev/modern.js/pull/1160)] export ExecaError type
+[[#1160](https://github.com/web-infra-dev/modern.js/pull/1160)] export ExecaError type
 
 ## Bug Fix:
 
-[[#1264](https://github.com/modern-js-dev/modern.js/pull/1264)] fix: conventional router app use App.init not work
+[[#1264](https://github.com/web-infra-dev/modern.js/pull/1264)] fix: conventional router app use App.init not work
 ```

package/zh/components/enable-bff.mdx

@@ -7,8 +7,8 @@ import { Tabs, Tab as TabItem } from "@theme";
   <TabItem value="express" label="Express.js" default>
 
 ```ts title="edenx.config.ts"
-import expressPlugin from '@edenx/plugin-express';
-import bffPlugin from '@edenx/plugin-bff';
+import expressPlugin from '@modern-js/plugin-express';
+import bffPlugin from '@modern-js/plugin-bff';
 
 export default defineConfig({
   plugins: [expressPlugin(), bffPlugin()],
@@ -19,8 +19,8 @@ export default defineConfig({
   <TabItem value="koa" label="Koa.js">
 
 ```ts title="edenx.config.ts"
-import koaPlugin from '@edenx/plugin-koa';
-import bffPlugin from '@edenx/plugin-bff';
+import koaPlugin from '@modern-js/plugin-koa';
+import bffPlugin from '@modern-js/plugin-bff';
 
 export default defineConfig({
   plugins: [koaPlugin(), bffPlugin()],

package/zh/components/init-rspack-app.mdx

@@ -0,0 +1,7 @@
+```bash
+$ npx @modern-js/create myapp
+? 请选择你想创建的工程类型 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请选择构建工具 Rspack
+```

package/zh/components/release-note.mdx

@@ -1 +1 @@
-根据官网 [Release Note](https://github.com/modern-js-dev/modern.js/releases)，开发者也可以手动将项目升级到想要的版本。
+根据官网 [Release Note](https://github.com/web-infra-dev/modern.js/releases)，开发者也可以手动将项目升级到想要的版本。

package/zh/configure/app/bff/enable-handle-web.mdx

@@ -0,0 +1,24 @@
+---
+title: enableHandleWeb
+---
+
+# bff.enableHandleWeb
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+:::caution 注意
+请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+:::
+
+默认情况下，BFF 服务只能处理 BFF API 的请求。
+
+当该值设置为 `true` 时，页面请求流量也会经过 BFF，并且 Modern.js 内置的页面渲染的逻辑默认会作为 BFF 服务的最后一个中间件运行。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```

package/zh/configure/app/server/enable-framework-ext.mdx

@@ -35,7 +35,7 @@ export const middleware: Middleware = (ctx, next) => {
 开启后，Middleware 类型将从其他命名空间下导出，并且可以使用框架拓展的语法：
 
 ```ts title="server/index.ts"
-import { SomeType } from '@modern-js/runtime/{frameworknName}';
+import { SomeType } from '@modern-js/runtime/{namespace}';
 
 export const middleware: SomeType = (...args) => {
   console.log(args[0].url);

package/zh/configure/app/server/ssr.mdx

@@ -4,11 +4,13 @@ sidebar_label: ssr
 
 # server.ssr
 
-- **类型：** `boolean`
+- **类型：** `boolean` | `Object`
 - **默认值：** `false`
 
 SSR 开关以及相关设置。
 
+### Boolean 类型
+
 当值类型为 `boolean` 时，表示是否开启 SSR 部署模式，默认 `false` 不开启。
 
 ```ts title="modern.config.ts"
@@ -18,3 +20,19 @@ export default defineConfig({
   },
 });
 ```
+
+### Object 类型
+
+当值类型为 `Object` 时，可以配置如下属性：
+
+- `mode`：`string = 'string'`，默认为使用 `renderToString` 渲染。配置为 'stream' 开启流式渲染。
+- `forceCSR`：`boolean = false`，默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 即可强制 CSR。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    forceCSR: true,
+    mode: 'stream',
+  },
+});
+```

package/zh/guides/advanced-features/bff/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "BFF",
-  "position": 1,
+  "position": 2,
   "link": {
     "type": "doc",
     "id": "guides/advanced-features/bff/index"

package/zh/guides/advanced-features/rspack-start.mdx

@@ -1,11 +1,11 @@
 ---
 title: 使用 Rspack
-sidebar_position: 12
+sidebar_position: 1
 ---
 
 # 使用 Rspack
 
-[Rspack](https://www.rspack.org/) 是字节跳动 Web Infra 团队自研的 Rust Bundler，核心架构对齐 webpack 实现，并对社区常用的构建能力做了开箱即用的支持。
+[Rspack](https://www.rspack.dev/) 是字节跳动 Web Infra 团队自研的 Rust Bundler，核心架构对齐 webpack 实现，并对社区常用的构建能力做了开箱即用的支持。
 
 Rspack 通过以下方式来提升编译性能：
 
@@ -13,22 +13,18 @@ Rspack 通过以下方式来提升编译性能：
 - 充分利用多核优势，整个编译过程充分进行多线程优化。
 - 基于请求的按需编译（Lazy Compilation），减小每次编译的模块数目，以提升冷启动的速度。
 
-## 初始化 rspack 项目
+## 初始化 Rspack 项目
 
-Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为**rspack**，即可创建一个 rspack 项目:
+Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为 **Rspack**，即可创建一个 Rspack 项目:
 
-```bash
-$ npx @modern-js/create myapp
-? 请选择你想创建的工程类型 应用
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-? 请选择构建工具 rspack
-```
+import InitRspackApp from "@site-docs/components/init-rspack-app"
+
+<InitRspackApp />
 
 项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目。更多项目信息可参考[快速上手](/guides/get-started/quick-start.html)。
 
 :::tip
-使用 rspack 作为打包工具时，以下功能暂不支持使用:
+使用 Rspack 作为打包工具时，以下功能暂不支持使用:
 
 - 服务端渲染（SSR）
 - 静态站点生成（SSG）
@@ -37,17 +33,17 @@ $ npx @modern-js/create myapp
 
 :::
 
-## 从 webpack 迁移至 rspack
+## 从 webpack 迁移至 Rspack
 
-通过执行 `pnpm run new` 可启用 rspack 构建：
+通过执行 `pnpm run new` 可启用 Rspack 构建：
 
 ```bash
 $ pnpm run new
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「rspack 构建」
+? 启用可选功能 启用「Rspack 构建」
 ```
 
-执行命令后，在 modern.config.ts 中开启 rspack 构建：
+执行命令后，在 modern.config.ts 中开启 Rspack 构建：
 
 ```ts title=modern.config.ts
 import appTools, { defineConfig } from '@modern-js/app-tools';
@@ -65,5 +61,5 @@ export default defineConfig<'rspack'>({
 ```
 
 :::tip
-从 webpack 迁移至 rspack，会有一些构建和配置能力上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
+从 webpack 迁移至 Rspack，会有一些构建和配置能力上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
 :::

package/zh/guides/advanced-features/ssr.mdx

@@ -43,10 +43,13 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 不过，开发者仍然需要关注数据的兜底处理，例如 `null` 值或不符合预期的数据返回。避免在 SSR 时产生 React 渲染错误或是返回凌乱的渲染结果。
 
 :::info 补充信息
-使用 Data Loader 时，数据获取发生在渲染前，Modern.js 也仍然支持在组件渲染时获取数据。更多相关内容可以查看[数据获取](/guides/basic-features/data-fetch)。
+1. 当以客户端路由的方式请求页面时，Modern.js 会发送一个 HTTP 请求，服务端接收到请求后执行页面对应的 Data Loader 函数，然后将执行结果作为请求的响应返回浏览器。
 
+2. 使用 Data Loader 时，数据获取发生在渲染前，Modern.js 也仍然支持在组件渲染时获取数据。更多相关内容可以查看[数据获取](/guides/basic-features/data-fetch)。
 :::
 
+
+
 ## 保持渲染一致
 
 有些业务中，通常需要根据当前的运行容器环境特征做不同的 UI 展示，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息。如果处理不够仔细，此时很有可能出现不符合预期的渲染结果。
@@ -277,7 +280,7 @@ export const loader = () => {
 
 ## 流式渲染
 
-Modern.js 支持了 React 18 的流式渲染，可以通过如下配置修改默认的渲染模式：
+Modern.js 支持了 React 18 的流式渲染，可以通过如下配置启用：
 
 ```json
 {
@@ -289,7 +292,210 @@ Modern.js 支持了 React 18 的流式渲染，可以通过如下配置修改默
 }
 ```
 
-:::note
-目前 Modern.js 内置的数据获取方式还未支持流式渲染，如迫切需要开发者可以按照 React Stream SSR 的 Demo 自建。
+Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
+
+- [`defer`](https://reactrouter.com/en/main/utils/defer)：在 Data Loader 中使用，用于支持异步获取数据。
+- [`Await`](https://reactrouter.com/en/main/components/await)：用于渲染 Data Loader 返回的异步数据。
+- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value)：用于从最近的父级 `Await` 组件中获取数据。
+
+
+### 异步获取数据
+
+```ts title='page.loader.ts'
+import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+interface User {
+  name: string;
+  age: number;
+}
+
+export interface Data {
+  data: User;
+}
+
+export default ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 200);
+  });
+
+  return defer({ data: user });
+};
+
+```
+
+`user` 是一个 Promise 类型的对象，表示需要异步获取的数据，通过 `defer` 处理需要异步获取的 `user`。注意，`defer` 必须接收一个对象类型的参数，
+因此， 传入 `defer` 的参数为 `{data: user}`。
+
+`defer` 还可以同时接收异步数据和同步数据。例如：
+
+```ts title='page.loader.ts'
+
+// 省略部分代码
+
+export default ({ params }: LoaderFunctionArgs) => {
+  const userId = params.id;
+
+  const user = new Promise<User>(resolve => {
+    setTimeout(() => {
+      resolve({
+        name: `user-${userId}`,
+        age: 18,
+      });
+    }, 200);
+  });
+
+  const otherData = new Promise<string>(resolve => {
+    setTimeout(() => {
+      resolve('some sync data');
+    }, 200);
+  });
+
+  return defer({
+    data: user,
+    other: await otherData
+  });
+};
+
+```
+
+`otherData` 前加了 `await`，所以是同步获取的数据，它可以和异步获取的数据 `user` 同时传入 `defer`。
+
+
+### 渲染异步数据
+
+通过 `Await` 组件，可以获取到 Data Loader 中异步返回的数据，然后进行渲染。例如：
+
+```ts title='page.tsx'
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+import type { Data } from './page.loader';
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          {(user) => {
+            return (
+              <div id="data">
+                name: {user.name}, age: {user.age}
+              </div>
+            );
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
 
+export default Page;
+```
+
+`Await` 需要包裹在 `Suspense` 组件内部，`Await` 的 `resolve` 传入的是 Data Loader 异步获取的数据，当数据获取完成后，
+通过 [Render Props](https://reactjs.org/docs/render-props.html) 模式，渲染获取到的数据。在数据的获取阶段，将展示
+`Suspense` 组件 `fallback` 属性设置的内容。
+
+:::warning 注意
+从 Data Loader 文件导入类型时，需要使用 import type 语法，保证只导入类型信息，这样可以避免 Data Loader 的代码打包到前端产物的 bundle 文件中。
+
+所以，这里的导入方式为：`import type { Data } from './page.loader'`;
+:::
+
+也可以通过 `useAsyncValue` 获取 Data Loader 返回的异步数据。例如：
+
+```
+```ts title='page.tsx'
+import { useAsyncValue } from '@modern-js/runtime/router';
+
+// 省略部分代码
+
+const UserInfo = () => {
+  const user = useAsyncValue();
+
+  return (
+     <div>
+      name: {user.name}, age: {user.age}
+    </div>
+  )
+}
+
+const Page = () => {
+  const data = useLoaderData() as Data;
+
+  return (
+    <div>
+      User info:
+      <Suspense fallback={<div id="loading">loading user data ...</div>}>
+        <Await resolve={data.data}>
+          <UserInfo />
+        </Await>
+      </Suspense>
+    </div>
+  );
+};
+
+export default Page;
+```
+
+### 错误处理
+
+`Await` 组件的 `errorElement` 属性，可以用来处理当 Data Loader 执行时，或者子组件渲染时抛出的错误。
+例如，我们故意在 Data Loader 函数中抛出错误：
+
+```ts title='page.loader.ts'
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const data = new Promise((resolve, reject) => {
+    setTimeout(() => {
+      reject(new Error('error occurs'));
+    }, 200);
+  });
+
+  return defer({ data });
+};
+```
+
+然后通过 `useAsyncError` 获取错误，并将用于渲染错误信息的组件赋值给 `Await` 组件的 `errorElement` 属性：
+
+```ts title='page.ts'
+import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+
+export default function Page() {
+  const data = useLoaderData();
+
+  return (
+    <div>
+      Error page
+      <Suspense fallback={<div>loading ...</div>}>
+        <Await resolve={data.data} errorElement={<ErrorElement />}>
+          {(data: any) => {
+            return <div>never displayed</div>;
+          }}
+        </Await>
+      </Suspense>
+    </div>
+  );
+}
+
+function ErrorElement() {
+  const error = useAsyncError() as Error;
+  return <p>Something went wrong! {error.message}</p>;
+}
+```
+
+:::info 补充信息
+1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
+2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
 :::