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

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

@@ -7,7 +7,7 @@ sidebar_position: 3
 
 启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configure/app/server/ssr) 为 `true` 即可：
 
-```json title="package.json"
+```json
 {
   "server": {
     "ssr": true
@@ -17,12 +17,23 @@ sidebar_position: 3
 
 ## SSR 时的数据获取
 
-Modern.js 中提供了 [`useLoader`](/docs/apis/app/runtime/core/use-loader) Hooks API，用于在 SSR 环境下同构的获取数据：
+Modern.js 中提供了 Data Loader，方便开发者在 SSR、CSR 下同构的获取数据。每个路由模块，如 `layout.tsx` 和 `page.tsx` 都可以定义自己的 Data Loader：
 
-```ts
-const { data, loading, error } = useLoader(() => {
-  return loadData()
-});
+```ts title="src/routes/page.tsx"
+export const loader = () => {
+  return {
+    message: 'Hello World',
+  };
+};
+```
+
+在组件中可以通过 Hooks API 的方式获取 `loader` 函数返回的数据：
+
+```tsx
+export default () => {
+  const data = useLoaderData();
+  return <div>{data.message}</div>;
+}
 ```
 
 Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发体验。并且提供了优雅的降级处理，一旦 SSR 请求失败，会自动降级在浏览器端重新发起请求。
@@ -30,7 +41,7 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 不过，开发者仍然需要关注数据的兜底处理，例如 `null` 值或不符合预期的数据返回。避免在 SSR 时产生 React 渲染错误或是返回凌乱的渲染结果。
 
 :::info 补充信息
-更多相关内容可以查看[数据获取](/docs/guides/basic-features/data-fetch)。
+使用 Data Loader 时，数据获取发生在渲染前，Modern.js 也仍然支持在组件渲染时获取数据。更多相关内容可以查看[数据获取](/docs/guides/basic-features/data-fetch)。
 :::
 
 ## 保持渲染一致
@@ -55,10 +66,10 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 Warning: Expected server HTML to contain a matching <div> in <div>.
 ```
 
-这是 React 在客户端执行注水逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
+这是 React 在客户端执行 hydrate 逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
 
 :::info 注
-关于注水逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
+关于 hydrate (注水)逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
 :::
 
 应用需要保持 SSR 与 CSR 渲染结果的一致性，如果存在不一致的情况，说明这部分内容无需在 SSR 中进行渲染。Modern.js 为这类在 SSR 中不需要渲染的内容提供 [`<NoSSR>` 工具组件](/docs/apis/app/runtime/core/use-runtime-context)：
@@ -129,29 +140,25 @@ SPR 利用预渲染与缓存技术，为 SSR 页面提供静态 Web 的响应性
 
 在 Modern.js 中使用 SPR 非常简单，只需要在组件中新增 `PreRender` 组件，该组件所在的页面就会自动开启 SPR。
 
-这里模拟一个使用 `useLoader` API 的组件，`useLoader` 中的请求需要消耗 2s 时间。
+这里模拟一个使用 `useLoaderData` API 的组件，Data Loader 中的请求需要消耗 2s 时间。
 
 ```jsx
-import { useLoader } from '@modern-js/runtime';
+import { useLoaderData } from '@modern-js/runtime/router';
+
+export const loader = async () => {
+  await new Promise((resolve, reject) => {
+    setTimeout(() => {
+      resolve(null);
+    }, 2000);
+  });
+
+  return {
+    message: 'Hello Modern.js',
+  };
+};
 
 export default () => {
-  const { data } = useLoader(
-    async () => {
-      await new Promise((resolve, reject) => {
-        setTimeout(() => {
-          resolve(null);
-        }, 2000);
-      });
-
-      return {
-        message: 'Hello Modern.js',
-      };
-    },
-    {
-      params: 'foo',
-    },
-  );
-
+  const data = useLoaderData();
   return <div>{data?.message}</div>;
 };
 ```
@@ -187,17 +194,39 @@ import { PreRender } from '@modern-js/runtime/ssr';
 
 开启 SSR 时，Modern.js 会用相同的入口，构建出 SSR Bundle 和 CSR Bundle 两份产物。因此，在 SSR Bundle 中存在 Web API，或是在 CSR Bundle 中存在 Node API 时，都可能导致运行出错。
 
+在组件中引入 Web API，通常情况下是要做一些全局监听，或是获取浏览器相关的数据，例如：
+
+```tsx
+document.addEventListener('load', () => {
+  console.log('document load');
+});
+const App = () => {
+  return <div>Hello World</div>
+}
+export default App;
+```
+
+在组件文件中引入 Node API，通常情况下是因为使用了 Data Loader，例如：
+
+```ts
+import fse from 'fs-extra';
+export const loader = () => {
+  const file = fse.readFileSync('./myfile');
+  return {
+    ...
+  };
+};
+```
+
 ### 环境变量区分
 
-在组件中可以直接使用 Modern.js 内置的环境变量 `MODERN_TARGET` 进行判断，方便在构建时删除无用代码：
+对于第一种情况，我们可以直接使用 Modern.js 内置的环境变量 `MODERN_TARGET` 进行判断，在构建时删除无用代码：
 
 ```ts
-export default () => {
-  if (process.env.MODERN_TARGET === 'node') {
-    console.log('server render');
-  } else {
-    console.log('client render');
-  }
+if (process.env.MODERN_TARGET === 'browser') {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
 }
 ```
 
@@ -207,38 +236,34 @@ export default () => {
 
 ### 文件后缀区分
 
-但有时，这种 Treeshaking 的方式并不能保证代码被完全分离。EdenX 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
+但例如第二种情况，Treeshaking 的方式并不能保证代码被完全分离。Modern.js 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
 
-例如存在 `client-sdk` 中直接使用了 Web API：
-
-```ts
-// client-sdk
-export const href = location.href;
-```
-
-这时候直接引用到组件中，会造成 SSR 报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
+例如在代码中引入了 `fs-extra`，这时候直接引用到组件中，会造成 CSR 加载报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
 
 ```ts title="compat.ts"
-export { href } from 'client-sdk';
+export { readFileSync } from 'fs-extra';
 ```
 
 ```ts title="compat.node.ts"
-export const href = '';
+export const readFileSync: any = () => {};
 ```
 
 在文件中直接引入 `./compat`，此时 SSR 环境下会优先使用 `.node.ts` 后缀的文件，CSR 环境下会使用 `.ts` 后缀的文件。
 
 ```ts title="App.tsx"
-import { href } from './compat'
+import { readFileSync } from './compat'
 
-export default () => {
-  return <div onClick={() => { console.log(href) }}></div>
-}
+export const loader = () => {
+  const file = readFileSync('./myfile');
+  return {
+    ...
+  };
+};
 ```
 
 ### 独立文件
 
-上述两种方式，都会为开发者带来一些心智负担。Modern.js 正在基于[嵌套路由](/docs/guides/basic-features/routes)开发设计[更简单的方案](/docs/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+上述两种方式，都会为开发者带来一些心智负担。Modern.js 基于[嵌套路由](/docs/guides/basic-features/routes)开发设计了[更简单的方案](/docs/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
 
 ## 接口请求
 
@@ -247,3 +272,21 @@ export default () => {
 需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
 
 如果实在需要透传所有请求头，请务必过滤 `host` 字段。
+
+## 流式渲染
+
+Modern.js 支持了 React 18 的流式渲染，可以通过如下配置修改默认的渲染模式：
+
+```json
+{
+  "server": {
+    "ssr": {
+      "mode": "stream"
+    }
+  }
+}
+```
+
+:::note
+目前 Modern.js 内置的数据获取方式还未支持流式渲染，如迫切需要开发者可以按照 React Stream SSR 的 Demo 自建。
+:::

package/zh/guides/advanced-features/testing.md

@@ -1,4 +1,36 @@
 ---
-title: 测试
 sidebar_position: 10
 ---
+
+# 测试
+
+Modern.js 默认继承了 [Jest](https://jestjs.io/) 的测试能力。
+
+我们首先需要执行 `pnpm run new` 启用「单元测试 / 集成测试」功能：
+
+```
+? 请选择你想要的操作： 启用可选功能
+? 启用可选功能： 启用「单元测试 / 集成测试」功能
+```
+
+执行上述命令后，`package.json` 中将会自动生成 `"test": "modern test"` 命令。
+
+## 测试文件
+
+Modern.js 默认识别的测试文件路径为： `<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
+
+如果你需要自定义 test 目录，可通过 [tools.jest](/docs/configure/app/tools/jest) 进行配置。
+
+## 使用姿势
+
+Modern.js test 支持使用 [testing-library](https://testing-library.com/docs/) 相关包 API，可直接通过 `@modern-js/runtime/testing` 进行导入:
+
+```
+import { render, screen } from '@modern-js/runtime/testing';
+```
+
+其他 Modern.js 支持的 testing API 可参考[这里](/docs/apis/app/runtime/testing/cleanup)。
+
+## transform
+
+Modern.js 测试默认使用 [babel-jest](https://www.npmjs.com/package/babel-jest) 进行源码编译，如果你需要使用 [ts-jest](https://github.com/kulshekhar/ts-jest)，可以通过 [testing.transform](/docs/configure/app/testing/transformer) 进行配置。

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

@@ -12,8 +12,8 @@ Modern.js 作为以客户端为中心的开发框架，对服务端的定制能
 在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「自定义 Web Serve」功能：
 
 ```bash
-? 请选择你想要的操作： 创建工程元素
-? 创建工程元素： 新建「自定义 Web Server」源码目录
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「自定义 Web Server」源码目录
 ```
 
 执行命令后，项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。

package/zh/guides/basic-features/css/tailwindcss.md

@@ -9,8 +9,8 @@ sidebar_position: 2
 按照如下进行选择：
 
 ```bash
-? 请选择你想要的操作: 启用可选功能
-? 启用可选功能: 启用 Tailwind CSS 支持
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用 Tailwind CSS 支持
 ```
 
 使用时在入口的根组件(如 `src/App.jsx`)添加如下代码：
@@ -68,11 +68,7 @@ export default defineConfig({
 在开启「Tailwind CSS 支持」的功能后，首先需要安装 [`Twin`](https://github.com/ben-rogerson/twin.macro) 依赖:
 
 ``` bash
-# package manager is `pnpm`
 pnpm add twin.macro -D
-
-# package manager is `yarn`
-yarn add twin.macro -D
 ```
 
 当项目安装 `twin.macro` 依赖后，Modern.js 会检测到该依赖并对内置的 `babel-plugin-macro` 增加 `twin.macro` 相关的配置。因此在安装完依赖后，无需手动配置。下面是一个简单使用 `twin.macro` 的示例：

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

@@ -3,6 +3,188 @@ title: HTML 模板
 sidebar_position: 9
 ---
 
+Modern.js 提供了 `jsx` 和 `ejs` 两种方式用于自定义 html 模板。推荐使用 `jsx` 语法，让写模板跟写组件一样丝滑。
+
+## jsx
+
+### 使用说明
+
+#### 引入
+```tsx
+import {
+  Html,
+  Root,
+  Head,
+  DocumentContext,
+  Body,
+} from '@modern-js/runtime/document';
+```
+
+#### 导出
+```tsx
+export default Document() {}
+
+```
+
+#### 文件位置
+
+Document 文件，默认在应用根目录下:
+
+```bash
+.
+├── src
+│   ├── modern-app-env.d.ts
+│   ├── myapp
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       ├── Document.tsx
+│   │       └── page.tsx
+│   ├── new-entry
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       ├── Document.tsx
+│   │       └── page.tsx
+│   └── Document.tsx
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```
+
+多 entry 场景构建时，优先 entry 的根目录下的 Docoument.tsx 文件。如果当前 entry 没有 Document.tsx 文件，则会查找根目录下的 Document.tsx 文件。
+如果还没有，则会 fallback 到 `html 模板` 的逻辑。
+
+#### 子组件
+
+Document 模板共提供了 `Html`、`Root` `Head` `Body` 渲染页面的组件，以及 `DocumentContext` 等提供
+分别渲染：
+- `Html`: 提供 html 原生 dom。并计算出 `DocumentStructrueContext` 的值，将 `Html` 的结构传递给子组件，判断其它子组件是否默认渲染。
+
+- `Body`: 渲染生成 `body` 节点。其子元素包含 `Root` 组件。支持其它元素同时作为子元素，例如页脚。
+
+- `Root`: 渲染的根节点 `<div id='root'></div>`。默认根节点的 `id = 'root'`。可以设置 props.rootId 来更改 id 属性。子元素，也会被渲染进 DOM 里，随着 react 渲染完成，会替换掉，一般用来实现全局 loading。
+
+- `Head`: 渲染生成 `head` 节点。会自动填充 meta 元素，以及 `Scripts` 组件。
+
+- `Scripts`: 将构建产生的 script 标签渲染到该位置。用于调整构建产物的位置，默认放在 `Head` 组件里，用于
+
+`Html` 组件中，`Head` 和 `Body` 是必须要存在的，其它组件可以按需选择合适的组件进行组装。
+
+#### 模板参数
+
+因为是 JSX 形式，Document.tsx 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
+但同时 Document 自身也提供了 `DocumentContext` context 来提供一些配置、环境参数，方便直接获取。主要以下参数：
+
+- `processEnv`：提供构建时的 `process.env`
+- `config`: Modern.js 项目的配置。目前只暴露出 output 相关的配置
+- `entryName`: 当前的 entry 名。
+- `templateParams`: html 模板的参数，由 builder 提供。对应 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的 `templateParameters` 配置项最终获取到的结果。不建议使用!
+
+
+### 示例
+
+```tsx
+import React, { useContext } from 'react';
+import {
+  Html,
+  Root,
+  Head,
+  DocumentContext,
+  Body,
+} from '@modern-js/runtime/document';
+import Script from '@/components/Script';
+
+// 默认导出
+export default function Document(): React.ReactElement {
+  // DocumentContext 提供一些构建时的参数
+  const {
+    config: { output: htmlConfig },
+    entryName,
+    templateParams,
+  } = useContext(DocumentContext);
+
+  return (
+    <Html>
+      <Head>
+        // Head 组件支持自定义子元素。包括 link, script
+        <link href="https://modernjs.dev">Modern.js</link>
+        <script
+          // inline script 的脚本需要如下处理
+          dangerouslySetInnerHTML={{
+            __html: `window.b = 22`,
+          }}
+        ></script>
+      </Head>
+      <Body>
+        // rootId 可以更改根元素的 id
+        <Root rootId="root">
+          // Root 支持子元素
+          <h1 style={{ color: 'red' }}>以下为构建时传过来的参数：</h1>
+          <h2> entryName：{entryName}</h2>
+          <h2> title：{htmlConfig.title}</h2>
+          <h2> rootId: {templateParams.mountId}</h2>
+        </Root>
+        // Body 组件支持 Root 以外增加不同的组件，共同组成页面
+        <h1>bottom</h1>
+      </Body>
+    </Html>
+  );
+}
+
+```
+
+以上文件，将会生成以下 html 文件：
+
+```html
+<!DOCTYPE html>
+<html>
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport"
+        content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
+    <meta http-equiv="x-ua-compatible" content="ie=edge">
+    <meta name="renderer" content="webkit">
+    <meta name="layoutmode" content="standard">
+    <meta name="imagemode" content="force">
+    <meta name="wap-font-scale" content="no">
+    <meta name="format-detection" content="telephone=no">
+    <script>...</script>
+    <script defer src="/static/js/lib-react.js"></script>
+    <script defer src="/static/js/lib-polyfill.js"></script>
+    <script defer src="/static/js/lib-router.js"></script>
+    <script defer
+        src="/static/js/vendors-node_modules_pnpm_loadable_component_5_15_2_react_18_2_0_node_modules_loadable_compon-3fb0cf.js"></script>
+    <script defer
+        src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"></script>
+    <script defer src="/static/js/sub.js"></script>
+    <link href="https://www.baidu.com" />
+    <script>window.b = 22</script>
+</head>
+
+<body>
+    <div id="root">
+        <!--<?- html ?>-->
+        <h1 style="color:red">以下为构建时传过来的参数：</h1>
+        <h2> entryName：sub</h2>
+        <h2> title：</h2>
+        <h2> rootId: root</h2>
+    </div>
+    <h1>bottom</h1>
+    <!--<?- chunksMap.js ?>-->
+    <!--<?- SSRDataScript ?>-->
+</body>
+
+</html>
+```
+
+## ejs
+
+Modern.js 同时支持了使用 `ejs` 语法编写模板，当项目中，没有编写 `Document.[j|t]sx` 文件时，将自动回退至  `ejs` HTML 模板。
+
 默认情况下，Modern.js 的应用工程中会内置一份 HTML 模板，用于生成 HTML 代码。
 
 Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML 模板」**两种方式来自定义模板。

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

@@ -44,28 +44,22 @@ module.exports = {
 
 ## 返回随机数据
 
-可以在 `./config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started)、[faker.js](https://github.com/marak/Faker.js/) 等库生成随机数据，例如：
+可以在 `./config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据，例如：
 
 ```js
 const Mock = require('mockjs');
-const faker = require('faker');
 
 module.exports = {
   '/api/getInfo': Mock.mock({
      'data|1-10': [{ name: '@cname' }]
-   }) /* => {data: [{name: "董霞"}, {name: "魏敏"},  {name: "石磊"}} */
-  '/a/b': {
-    name: faker.fake("{{name.lastName}}, {{name.firstName}} {{name.suffix}}")
-   }  /* => { name: 'Marks, Dean Sr.'} */
-}
+   }), /* => {data: [{name: "董霞"}, {name: "魏敏"},  {name: "石磊"}} */
+};
 ```
 
 :::info 更多随机数据生成库
 
-* [Faker.js](https://github.com/marak/Faker.js/)
 * [Chancejs](https://github.com/chancejs/chancejs)
 * [Mock](https://github.com/nuysoft/Mock/wiki/Getting-Started)
-* https://www.npmtrends.com/mockjs-vs-faker-vs-chance
 
 :::
 

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

@@ -32,34 +32,9 @@ export default defineConfig({
 
 ## 全局代理
 
-Modern.js 提供了开箱即用的全局代理插件 `@modern-js/plugin-proxy`，该插件底层基于 [whistle](https://github.com/avwo/whistle)，可用来查看、修改 HTTP/HTTPS 的请求和响应，也可作为 HTTP 代理服务器使用。
-
-### 设置代理规则
-
-引入代理插件并填写规则后，执行 `pnpm run dev`，Modern.js 会在开发服务器启动之后，自动启用代理服务器。
-
-具体代理规则，可通过 [`dev.proxy`](/docs/configure/app/dev/proxy) 选项或 `config/proxy.js` 文件进行设置。
-
-### 代理服务器 UI 界面
-
-安装代理插件并配置代理规则后， 执行 `pnpm run dev` 命令：
-
-```bash
-  App running at:
-
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-ℹ  info      Starting the proxy server.....
-✔  success   Proxy Server start on localhost:8899
-```
-
-在控制台中可以看到代理服务器成功启动。
-
-访问 `http://localhost:8899`，显示下图所示的 UI 界面后，即可通过界面设置规则。
-
-![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)
+import GlobalProxy from '@site-docs/components/global-proxy.md'
 
+<GlobalProxy />
 
 ## BFF 代理
 

package/zh/guides/concept/entries.md

@@ -13,7 +13,6 @@ Modern.js 初始化的项目是单入口的，项目结构如下：
 
 ```
 .
-├── node_modules
 ├── src
 │   ├── modern-app-env.d.ts
 │   └── routes
@@ -30,9 +29,9 @@ Modern.js 初始化的项目是单入口的，项目结构如下：
 Modern.js 可以很方便的将单入口切换成多入口。可以在项目下执行 `pnpm run new`，通过生成器创建入口：
 
 ```bash
-? 请选择你想要的操作： 创建工程元素
-? 创建工程元素： 新建「应用入口」
-? 请填写入口名称： new-entry
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 new-entry
 ```
 
 执行后，`src/` 目录将会变成如下结构：
@@ -73,7 +72,7 @@ Modern.js 会将和 `package.json` 中 `name` 同名的目录作为主入口，
 1. 具有 `routes/` 目录
 2. 具有 `App.[jt]sx?` 文件
 3. 具有 `index.[jt]sx?` 文件
-2. 具有 `pages/` 目录（兼容旧版本）
+2. 具有 `pages/` 目录（兼容 Modern.js 1.0）
 
 当 `src/` 目录满足入口特征时，Modern.js 会认为当前项目为单入口应用。