@modern-js/main-doc 0.0.0-nightly-20231218170633 → 0.0.0-nightly-20231219170633

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

@@ -0,0 +1,240 @@
+---
+sidebar_position: 2
+title: 流式渲染
+---
+
+# 流式渲染
+
+## 概述
+
+流式渲染是一种新的渲染方式，它可以在用户与页面交互时，实时地更新页面内容，从而提高用户体验。
+
+在传统的渲染方式中，页面的渲染是一次性完成的，而在流式渲染中，页面的渲染是逐步完成的，在用户与页面交互时，逐步加载数据，而不是一次性加载所有数据。
+
+相比传统渲染：
+
+- 拥有更快感知速度：流式渲染可以在渲染过程中逐步显示内容能够以最快的速度显示业务首页。
+- 拥有更好的用户体验：通过流式渲染，用户可以更快地看到页面上的内容，而不需要等待整个页面都渲染完成后才能交互。
+- 拥有更好的性能控制：流式渲染可以让开发者更好地控制页面加载的优先级和顺序，从而更好地优化性能和用户体验。
+- 更好的适应性：流式渲染可以更好地适应不同网络速度和设备性能，使得页面在各种环境下都能有更好的表现。
+
+## 使用
+
+Modern.js 支持了 React 18 的流式渲染，可以通过如下配置启用：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream',
+    },
+  },
+});
+```
+
+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.data.ts"
+import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
+
+interface User {
+  name: string;
+  age: number;
+}
+
+export interface Data {
+  data: User;
+}
+
+export const loader = ({ 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.data.ts"
+// 省略部分代码
+
+export const loader = ({ 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 中异步返回的数据，然后进行渲染。例如：
+
+```tsx title="page.tsx"
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+import type { Data } from './page.data';
+
+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://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) 模式，渲染获取到的数据。在数据的获取阶段，将展示
+`Suspense` 组件 `fallback` 属性设置的内容。
+
+:::warning 注意
+从 Data Loader 文件导入类型时，需要使用 import type 语法，保证只导入类型信息，这样可以避免 Data Loader 的代码打包到前端产物的 bundle 文件中。
+
+所以，这里的导入方式为：`import type { Data } from './page.data'`;
+
+:::
+
+也可以通过 `useAsyncValue` 获取 Data Loader 返回的异步数据。例如：
+
+```tsx 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` 属性：
+
+```tsx 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)
+
+:::

package/docs/zh/guides/advanced-features/{ssr.mdx → ssr/usage.mdx}

@@ -1,10 +1,9 @@
 ---
-sidebar_position: 4
+sidebar_position: 1
+title: 基础使用
 ---
 
-# 服务端渲染
-
-在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
+# 基础使用
 
 启用 SSR 非常简单，只需要设置 [`server.ssr`](/configure/app/server/ssr) 为 `true` 即可：
 
@@ -139,6 +138,10 @@ CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不
 
 ## Serverless Pre-render
 
+:::warning
+x.43.0+ 已废弃，请使用 [SSR Cache](guides/advanced-features/ssr/cache) 替代
+:::
+
 Modern.js 提供 Serverless Pre-rendering (SPR) 这一特性来提升 SSR 性能。
 
 SPR 利用预渲染与缓存技术，为 SSR 页面提供静态 Web 的响应性能。它让 SSR 应用拥有静态 Web 页面的响应速度与稳定性，同时还能保持数据的动态更新。
@@ -324,224 +327,3 @@ export const loader = () => {
 需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
 
 如果实在需要透传所有请求头，请务必过滤 `host` 字段。
-
-## 流式渲染
-
-Modern.js 支持了 React 18 的流式渲染，可以通过如下配置启用：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  server: {
-    ssr: {
-      mode: 'stream',
-    },
-  },
-});
-```
-
-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.data.ts"
-import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
-
-interface User {
-  name: string;
-  age: number;
-}
-
-export interface Data {
-  data: User;
-}
-
-export const loader = ({ 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.data.ts"
-// 省略部分代码
-
-export const loader = ({ 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 中异步返回的数据，然后进行渲染。例如：
-
-```tsx title="page.tsx"
-import { Await, useLoaderData } from '@modern-js/runtime/router';
-import { Suspense } from 'react';
-import type { Data } from './page.data';
-
-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://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) 模式，渲染获取到的数据。在数据的获取阶段，将展示
-`Suspense` 组件 `fallback` 属性设置的内容。
-
-:::warning 注意
-从 Data Loader 文件导入类型时，需要使用 import type 语法，保证只导入类型信息，这样可以避免 Data Loader 的代码打包到前端产物的 bundle 文件中。
-
-所以，这里的导入方式为：`import type { Data } from './page.data'`;
-
-:::
-
-也可以通过 `useAsyncValue` 获取 Data Loader 返回的异步数据。例如：
-
-```tsx 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` 属性：
-
-```tsx 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)
-
-:::

package/docs/zh/guides/basic-features/css.mdx

@@ -22,7 +22,7 @@ Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
 
 ## 使用 CSS Modules
 
-请阅读 [使用 CSS Modules](https://modernjs.dev/builder/guide/basic/css-modules.html) 章节来了解 CSS Modules 的完整用法。
+请阅读 [使用 CSS Modules](/guides/basic-features/css-modules) 章节来了解 CSS Modules 的完整用法。
 
 ## 使用 CSS-in-JS
 
@@ -72,18 +72,7 @@ Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://git
 ? 请选择功能名称 启用 「Tailwind CSS」 支持
 ```
 
-成功开启后，会看到 `package.json` 中新增了依赖：
-
-```json title="./package.json"
-{
-  "dependencies": {
-    "tailwindcss": "^3.0.0"
-  },
-  "devDependencies": {
-    "@modern-js/plugin-tailwindcss": "^2.0.0"
-  }
-}
-```
+成功开启后，你会看到 `package.json` 中新增了 `tailwindcss` 和 `@modern-js/plugin-tailwindcss` 依赖。
 
 2. 在 `modern.config.ts` 中注册 Tailwind 插件:
 

package/docs/zh/guides/basic-features/data/data-write.mdx

@@ -84,7 +84,7 @@ Modern.js 中提供 Data Action 主要是为了使 UI 和服务器的状态能
 ![state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage1.png)
 
 如果项目中组件共享的数据主要服务端的状态，则无需在项目引入客户端状态管理库，使用 Data Loader 请求数据，通过 [`useRouteLoaderData`](/guides/basic-features/data/data-fetch.md) 在子组件中共享数据，
-通过 Data Actino 修改和同步服务端的状态。
+通过 Data Action 修改和同步服务端的状态。
 
 
 

package/docs/zh/guides/get-started/tech-stack.mdx

@@ -97,7 +97,7 @@ Modern.js 支持 [Sass](https://sass-lang.com/)、[Less](https://lesscss.org/)
 
 Modern.js 对 [CSS Modules](https://github.com/css-modules/css-modules) 提供了开箱即用的支持，内部基于 [css-loader](https://www.npmjs.com/package/css-loader) 实现。
 
-请参考[「使用 CSS Modules」](https://modernjs.dev/builder/guide/basic/css-modules.html) 来使用。
+请参考[「使用 CSS Modules」](/guides/basic-features/css-modules) 来使用。
 
 ---
 

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-nightly-20231218170633",
+  "version": "0.0.0-nightly-20231219170633",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "0.0.0-nightly-20231218170633"
+    "@modern-js/sandpack-react": "0.0.0-nightly-20231219170633"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "0.0.0-nightly-20231218170633"
+    "@modern-js/builder-doc": "0.0.0-nightly-20231219170633"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -39,8 +39,8 @@
     "@rspress/shared": "1.8.3",
     "@types/node": "^16",
     "@types/fs-extra": "9.0.13",
-    "@modern-js/doc-plugin-auto-sidebar": "0.0.0-nightly-20231218170633",
-    "@modern-js/builder-doc": "0.0.0-nightly-20231218170633"
+    "@modern-js/builder-doc": "0.0.0-nightly-20231219170633",
+    "@modern-js/doc-plugin-auto-sidebar": "0.0.0-nightly-20231219170633"
   },
   "scripts": {
     "dev": "rspress dev",