@modern-js/main-doc 2.6.0 → 2.7.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.6.0 build /github/workspace/packages/toolkit/main-doc
+> @modern-js/main-doc@2.7.0 build /github/workspace/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

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

@@ -26,6 +26,16 @@ If the file ends with `.min.js`, it will not compression.
 
 ## More Usage
 
+In React components, this prefix can be added via [built-in environment variables](/guides/basic-features/env-vars.html#asset_prefix):
+
+```tsx
+export default () => {
+  return (
+    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
+  );
+};
+```
+
 Whether in [custom HTML](/guides/basic-features/html), or in any HTML file under ['config/public/'](/apis/app/hooks/config/public), you can directly use the HTML tag to refer to the resources in the `config/upload/`:
 
 ```html

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

@@ -9,6 +9,8 @@ sidebar_label: ssr
 
 Enalbe SSR configuration.
 
+### Boolean Type
+
 When the value type is `boolean`, it indicates whether to enable SSR deployment mode, and `false` is not enabled by default.
 
 ```ts title="modern.config.ts"
@@ -18,3 +20,19 @@ export default defineConfig({
   },
 });
 ```
+
+### Object Type
+
+When the value type is `Object`, The following properties can be configured:
+
+- `mode`：`string = 'string'`, use `renderToString` rendering default. onfigure 'stream' to enable streaming rendering.
+- `forceCSR`：`boolean = false`, forced CSR rendering is disable by default. When configured as `true`, add `?csr=true` in URL to force CSR.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    forceCSR: true,
+    mode: 'stream',
+  },
+});
+```

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

@@ -44,8 +44,9 @@ And it provides elegant degradation processing. Once the SSR request fails, it w
 However, developers still need to pay attention to the fallback of data, such as `null` values or data returns that do not as expect. Avoid React rendering errors or messy rendering results when SSR.
 
 :::info
-When using Data Loader, data fetching happens before rendering, Modern.js still supports fetching data when the component is rendered. See [Data Fetch](/guides/basic-features/data-fetch).
+1. When you request the page on client-side page transitions, Modern.js sends an API request to the server, which runs Data Loader function.
 
+2. When using Data Loader, data fetching happens before rendering, Modern.js still supports fetching data when the component is rendered. See [Data Fetch](/guides/basic-features/data-fetch).
 :::
 
 ## Keep Rendering Consistent
@@ -288,9 +289,9 @@ In addition, some backend interfaces, or general gateways, will verify according
 
 Be sure to filter the `host` field if you really need to pass through all request headers.
 
-## Stream SSR
+## Streaming SSR
 
-Modern.js supports streaming rendering in React 18, the default rendering mode can be modified with the following configuration:
+Modern.js supports streaming rendering in React 18. Opt in it with the following configuration:
 
 ```json
 {
@@ -302,7 +303,211 @@ Modern.js supports streaming rendering in React 18, the default rendering mode c
 }
 ```
 
-:::note
-At present Modern.js built-in data fetch does not support streaming rendering. If app need it, developers can build it according to the demo of React Stream SSR.
+The streaming SSR of Modern.js is implemented based on React Router, and the main APIs involved are:
+
+- [`defer`](https://reactrouter.com/en/main/utils/defer): This utility allows you to defer values returned from loaders by passing promises instead of resolved values.
+- [`Await`](https://reactrouter.com/en/main/components/await): Used to render deferred values with automatic error handling.
+- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value)：Returns the resolved data from the nearest `<Await>` ancestor component.
+
+
+### Return async data
+
+```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` is of `Promise` type, which means the data will be obtained asynchronously. Note that `defer` must accept an object type parameter,
+therefore, the parameter passed to `defer` is `{data: user}`.
+
+`defer` can also receive asynchronous data and synchronous data at the same time. For example:
+
+```ts title='page.loader.ts'
+
+// skip some codes
+
+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
+  });
+};
+
+```
+
+`await` is added before `otherData`, so the data is obtained synchronously. It can be passed to `defer` with the data `user` at the same time.
+
+
+### Render async data
+
+Use the `Await` component to render the data returned asynchronously from the Data Loader. For example:
+
+```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` needs to be wrapped inside the `Suspense` component. The `resolve` of `Await` passes in the data acquired asynchronously by the Data Loader. When the data acquisition is completed,
+the obtained data is rendered through the [Render Props](https://reactjs.org/docs/render-props.html) mode. When the data acquisition is in pending status, the
+content set by the `fallback` property of the `Suspense` component will display.
+
+
+:::warning Warning
+When importing a type from a Data Loader file, you need to use the `import type` syntax to ensure that only type information is imported, which can prevent the Data Loader code from being packaged into the client bundle.
+
+So, here we import like this: `import type { Data } from './page.loader'`;
+:::
+
+You can also get the asynchronous data returned by Data Loader through `useAsyncValue`. For example:
+
+```
+```ts title='page.tsx'
+import { useAsyncValue } from '@modern-js/runtime/router';
+
+// skip some codes
+
+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;
+```
+
+### Error handling
+
+The `errorElement` property of the `Await` component can be used to handle errors thrown when the Data Loader executes or when a child component renders.
+For example, we intentionally throw an error in the Data Loader function:
+
+```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 });
+};
+```
+
+Then use `useAsyncError` to get the error, and assign the component used to render the error to the `errorElement` property of the `Await` component:
+
+```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 More
+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/en/guides/{css/tailwindcss.mdx → basic-features/css.mdx}

@@ -2,7 +2,64 @@
 sidebar_position: 2
 ---
 
-# Tailwind CSS
+# CSS Solutions
+
+Modern.js has built-in multiple CSS solutions, including Less / Sass / Stylus preprocessor, PostCSS, CSS Modules, CSS-in-JS and Tailwind CSS.
+
+## Using Less, Sass and Stylus
+
+Modern.js has built-in community popular CSS preprocessors such as Less, Sass.
+
+By default, you don't need to configure anything for Less and Sass. If you need to customize loader config, you can configure [tools.less](/configure/app/tools/less), [tools.sass](/configure/app/tools/sass) to set it up.
+
+You can also use Stylus in Modern.js, just install the Stylus plugin provided by Modern.js Builder, please refer to [Stylus Plugin](https://modernjs.dev/builder/en/plugins/plugin-stylus.html) for usage.
+
+## Using PostCSS
+
+Modern.js has built-in [PostCSS](https://postcss.org/) to transform the CSS code.
+
+Please refer to [Modern.js Builder - Using PostCSS](https://modernjs.dev/builder/en/guide/basic/css-usage.html#using-postcss) for detailed usage.
+
+## Using CSS Modules
+
+Please read the [Using CSS Modules](https://modernjs.dev/builder/en/guide/basic/css-modules.html) chapter for a complete usage of CSS Modules.
+
+## Using CSS-in-JS
+
+CSS-in-JS is a technology that can write CSS styles in JS files.
+
+Modern.js integrates the CSS-in-JS library [styled-components](https://styled-components.com/) commonly used in the community, which uses the new feature of JavaScript [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write CSS styles for components. You can use the [styled-components](https://styled-components.com/) API directly from `@modern-js/runtime/styled`.
+
+When you need to write a `div` component with an internal font in red, you can do the following implementation:
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const RedDiv = styled.div`
+  color: red;
+`;
+```
+
+When you need to dynamically set the component style according to the `props` of the component, for example, when the attribute `primary` of `props` is `true`, the color of the button is white, and otherwise it is red. The implementation code is as follows:
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const Button = styled.button`
+  color: ${props => (props.primary ? 'white' : 'red')};
+  font-size: 1em;
+`;
+```
+
+For more usage of styled-components, please refer to [[styled-components official website](https://styled-components.com/) ].
+
+Modern.js uses the Babel plugin [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) internally, and the plugin can be configured through [tools.styledComponents](/configure/app/tools/styled-components).
+
+:::tip
+If you need to use [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/) and other CSS-in-JS libraries, you need to install the dependency of the corresponding library first. For specific usage, please refer to the official website of the corresponding library.
+:::
+
+## Using Tailwind CSS
 
 [Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles. To use [Tailwind CSS](https://tailwindcss.com/) in the Modern.js, just execute `pnpm run new` in the project root directory and turn it on.
 
@@ -36,7 +93,7 @@ According to different needs, you can optionally import the CSS files provided b
 
 :::
 
-## Tailwind CSS version
+### Tailwind CSS version
 
 Modern.js supports both Tailwind CSS v2 and v3. The framework will recognize the version of `tailwindcss` in the project `package.json` and apply the corresponding configuration. By default, we install Tailwind CSS v3 for you.
 
@@ -54,7 +111,7 @@ Both Tailwind CSS v2 and v3 do not support IE 11 browsers. For background, pleas
 
 If you use Tailwind CSS on IE 11 browser, some styles may not be available, please pay attention.
 
-## Theme config
+### Theme config
 
 When you need to customize the [theme](https://tailwindcss.com/docs/theme) configuration of Tailwind CSS, you can modify it in the configuration [`source.designSystem`](/configure/app/source/design-system), for example, add a color theme `primary`:
 

package/en/guides/basic-features/env-vars.mdx

@@ -8,6 +8,10 @@ Modern.js provides support for environment variables, including built-in environ
 
 ## Built-in Environment
 
+### ASSET_PREFIX
+
+The  current path prefix of resource file, which is a **read-only** environment variable.
+
 ### NODE_ENV
 
 The current execution environment and is a **read-only** environment variable whose have different values under different execution commands:

package/en/tutorials/first-app/c03-css.mdx

@@ -293,7 +293,7 @@ A Utility Class named `custom-text-gray` is implemented in `src/routes/styles/ut
 ```
 
 :::info note
-Modern.js integrates with [PostCSS](/guides/css/postcss) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+Modern.js integrates with [PostCSS](/guides/basic-features/css) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
 
 :::
 

package/package.json

@@ -11,13 +11,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.6.0",
+  "version": "2.7.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.6.0"
+    "@modern-js/builder-doc": "^2.7.0"
   },
   "devDependencies": {
     "ts-node": "^10",
@@ -25,7 +25,7 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.6.0"
+    "@modern-js/builder-doc": "2.7.0"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

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/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/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)
 :::

package/zh/guides/{css/tailwindcss.mdx → basic-features/css.mdx}

@@ -2,7 +2,64 @@
 sidebar_position: 2
 ---
 
-# Tailwind CSS
+# CSS 开发方案
+
+Modern.js 内置多种常用的 CSS 开发方案，包括 Less / Sass / Stylus 预处理器、PostCSS、CSS Modules、CSS-in-JS 和 Tailwind CSS。
+
+## 使用 Less、Sass 和 Stylus
+
+Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
+
+默认情况下，你不需要对 Less 和 Sass 进行任何配置。如果你有自定义 loader 配置的需求，可以通过配置 [tools.less](/configure/app/tools/less)、[tools.sass](/configure/app/tools/sass) 来进行设置。
+
+你也可以在 Modern.js 中使用 Stylus，只需要安装 Modern.js Builder 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://modernjs.dev/builder/plugins/plugin-stylus.html)。
+
+## 使用 PostCSS
+
+Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
+
+请阅读 [Modern.js Builder - 使用 PostCSS](https://modernjs.dev/builder/guide/basic/css-usage.html#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
+
+## 使用 CSS Modules
+
+请阅读 [使用 CSS Modules](https://modernjs.dev/builder/guide/basic/css-modules.html) 章节来了解 CSS Modules 的完整用法。
+
+## 使用 CSS-in-JS
+
+CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。
+
+Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
+
+当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const RedDiv = styled.div`
+  color: red;
+`;
+```
+
+当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const Button = styled.button`
+  color: ${props => (props.primary ? 'white' : 'red')};
+  font-size: 1em;
+`;
+```
+
+关于 styled-components 的更多用法，请参考 [styled-components 官网](https://styled-components.com/)。
+
+Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 插件，你可以通过 [tools.styledComponents](/configure/app/tools/styled-components) 对插件进行配置。
+
+:::tip 提示
+如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
+:::
+
+## 使用 Tailwind CSS
 
 [Tailwind CSS](https://tailwindcss.com/) 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。在 Modern.js 中使用 [Tailwind CSS](https://tailwindcss.com/)，只需要在项目根目录下执行 `pnpm run new` 并开启。
 
@@ -46,7 +103,7 @@ const App = () => (
 
 :::
 
-## Tailwind CSS 版本
+### Tailwind CSS 版本
 
 Modern.js 同时支持 Tailwind CSS v2 和 v3 版本，框架会识别项目 `package.json` 中的 `tailwindcss` 依赖版本，并启用相应的配置。默认情况下，我们会为你安装 Tailwind CSS v3 版本。
 
@@ -64,7 +121,7 @@ Tailwind CSS v2 和 v3 均不支持 IE 11 浏览器，相关背景请参考：
 
 如果你在 IE 11 浏览器上使用 Tailwind CSS，可能会出现部分样式不可用的现象，请谨慎使用。
 
-## Theme 配置
+### Theme 配置
 
 当需要自定义 Tailwind CSS 的 [theme](https://tailwindcss.com/docs/theme) 配置的时候，可以在配置 [`source.designSystem`](/configure/app/source/design-system) 中修改，例如，颜色主题中增加一个 `primary`：
 

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

@@ -8,6 +8,10 @@ Modern.js 提供了对环境变量的支持，包含内置的环境变量和自
 
 ## 内置的环境变量
 
+### ASSET_PREFIX
+
+表示当前资源文件的路径前缀，是**只读的**的环境变量。
+
 ### NODE_ENV
 
 表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：

package/zh/tutorials/first-app/c03-css.mdx

@@ -293,7 +293,7 @@ import '../styles/utils.css';
 ```
 
 :::info
-Modern.js 集成了 [PostCSS](/guides/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)。
+Modern.js 集成了 [PostCSS](/guides/basic-features/css)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)。
 
 :::
 

package/en/guides/css/_category_.json

@@ -1,5 +0,0 @@
-{
-  "label": "CSS Solutions",
-  "position": 4,
-  "collapsed": false
-}

package/en/guides/css/css-in-js.mdx

@@ -1,40 +0,0 @@
----
-sidebar_position: 1
----
-
-# CSS-in-JS
-
-CSS-in-JS is a technology that can write CSS styles in JS files. Modern.js integrates the CSS-in-JS library [styled-components](https://styled-components.com/) commonly used in the community, which uses the new feature of JavaScript [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write CSS styles for components. You can use the [styled-components](https://styled-components.com/) API directly from `@modern-js/runtime/styled`.
-
-When you need to write a `div` component with an internal font in red, you can do the following implementation:
-
-```js
-import styled from '@modern-js/runtime/styled';
-
-const RedDiv = styled.div`
-  color: red;
-`;
-```
-
-When you need to dynamically set the component style according to the `props` of the component, for example, when the attribute `primary` of `props` is `true`, the color of the button is white, and otherwise it is red. The implementation code is as follows:
-
-```js
-import styled from '@modern-js/runtime/styled';
-
-const Button = styled.button`
-  color: ${props => (props.primary ? 'white' : 'red')};
-  font-size: 1em;
-`;
-```
-
-For more usage of styled-components, please refer to [[styled-components official website](https://styled-components.com/) ].
-
-:::info Additional
-Modern.js uses the Babel plugin [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) internally, and the plugin can be configured through [`tools.styled Components`](/configure/app/tools/styled-components).
-
-:::
-
-:::tip
-If you need to use [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/) and other CSS-in-JS libraries, you need to install the dependency of the corresponding library first. For specific usage, please refer to the official website of the corresponding library.
-
-:::

package/en/guides/css/css-modules.mdx

@@ -1,87 +0,0 @@
----
-sidebar_position: 5
----
-
-# CSS Modules
-
-Modern.js out of the box support for [CSS Modules](https://github.com/css-modules/css-modules).
-
-## File Suffix Form CSS Modules
-
-By default, files ending in `.module.(css|scss|sass|less)` are treated as CSS Modules files, for example:
-
-```css title="button.module.css"
-.redColor {
-  color: red;
-}
-```
-
-```js title="Button.jsx"
-import styles from './button.module.css';
-
-export default function Button() {
-  return (
-    <button type="button" className={styles.redColor}>
-      red button
-    </button>
-  );
-}
-```
-
-Will eventually be compiled as:
-
-```js
-<button type="button" className="button_redColor__1-RBg">
-  red button
-</button>
-```
-
-## Global CSS Modules
-
-If you want to remove the `.module` suffix from the filename, you can set [`output.disable CssModuleExtension`](/configure/app/output/disable-css-module-extension).
-
-After setting, all style files except the style files in the `node_modules/` directory and the file name format of `[name].global.(css|scss|sass|less)` will be processed as CSS Modules.
-
-If you need global styles at this point, you can solve it by creating a style file with the filename format `[name].global.(css|scss|sass|less)`, for example:
-
-```css title="app.global.css"
-.bg-blue {
-  background-color: blue;
-}
-```
-
-```css title="button.css"
-.redColor {
-  color: red;
-}
-```
-
-```js title="App.jsx"
-import './app.global.css';
-import styles from './button.css';
-
-export default function Button() {
-  return (
-    <button type="button" className={`${styles.redColor} bg-blue`}>
-      button
-    </button>
-  );
-}
-```
-
-Will eventually be compiled as:
-
-```js
-<button type="button" className="button__redColor--JsFYl bg-blue">
-  button
-</button>
-```
-
-The final effect is as follows:
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/more-css-modules.png)
-
-:::tip
-When using [babel-plugin-react-css-modules](https://github.com/gajus/babel-plugin-react-css-modules), it is important to note that the configuration option `generateScopedName` of this plugin needs to be the same as [`output.css ModuleLocalIdentName`](/configure/app/output/css-module-local-ident-name).
-
-:::

package/en/guides/css/less-sass.mdx

@@ -1,17 +0,0 @@
----
-sidebar_position: 4
----
-
-# Less and Sass
-
-[Less](https://lesscss.org/) and [Sass](https://sass-lang.com/) are two commonly used CSS preprocessors that Modern.js built-in support for the Less and Sass compile capabilities.
-
-## Customized Configuration
-
-- If you need to customize the configuration of [less-loader](https://github.com/webpack-contrib/less-loader), please refer to the [tools.less](/configure/app/tools/less).
-- If you need to customize the configuration of [sass-loader](https://github.com/webpack-contrib/sass-loader), please refer to the [tools.less](/configure/app/tools/sass).
-
-:::tip
-CSS files pre-compiled by Less and Sass will still undergo Modern.js build-in [PostCSS](https://postcss.org/) conversion, which has good browser compatibility. For related content, please refer to [[PostCSS](/guides/css/postcss)].
-
-:::

package/en/guides/css/postcss.mdx

@@ -1,79 +0,0 @@
----
-sidebar_position: 3
----
-
-# PostCSS
-
-[PostCSS](https://postcss.org/) is a tool for converting CSS code with JavaScript tools and plugins. Modern.js built-in PostCSS and integrates common PostCSS plugins such as [Autoprefixer](https://github.com/postcss/autoprefixer) to meet the style development needs of most projects.
-
-By default, Modern.js compile and transform CSS as follows:
-
-1. [Autoprefixer](https://github.com/postcss/autoprefixer) Automatically add the required browser vendor prefix to CSS rules according to the required browser range. Modern.js default supported browser ranges are: `['> 0.01%', 'not dead', 'not op_mini all']`.
-
-:::info Note
-  - [Supported browser range: `> 0.01%`] means that the browser market share is greater than 0.01%.
-  - `Not dead` means excluding browsers that are no longer officially supported and browsers that have not been updated in the past 24 months.
-  - `not op_mini all` means exclude Opera Mini.
-
-:::
-
-:::info Additional
-If you need to modify the default browser support range, you can configure `browserslist` in the project's `package.json` file, and set the rule to refer to the use of [Browserslist](https://github.com/browserslist/browserslist). The following is an example:
-`json title ="package.json" { "Browserslist": [ "The last 1 versions", "> 1%", "IE 10" ] } `
-
-:::
-
-2. Provide [CSS custom properties](https://www.w3.org/TR/css-variables-1/) support, you can define and use custom variables in CSS, such as:
-
-```css
-:root {
-  --main-bg-color: pink;
-}
-
-body {
-  background-color: var(--main-bg-color);
-}
-```
-
-3. Provide [CSS Nesting](https://drafts.csswg.org/css-nesting-1/) support, you can use nested writing in CSS, such as:
-
-```css
-table.colortable td {
-  text-align: center;
-}
-table.colortable td.c {
-  text-transform: uppercase;
-}
-```
-
-It can also be rewritten as CSS nested:
-
-```css
-table.colortable {
-  & td {
-    text-align: center;
-    &.c {
-      text-transform: uppercase;
-    }
-  }
-}
-```
-
-4. Fix known [Flexbugs](https://github.com/philipwalton/flexbugs).
-5. Provide compatibility with the following CSS features:
-   - [`initial` attribute value](https://developer.mozilla.org/en-US/docs/Web/CSS/initial_value)
-   - [`break-` attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
-   - [`font-variant`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
-   - [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#syntax_improvements_in_level_4)
-
-When you need to modify the PostCSS configuration, you can implement it through the underlying configuration [`tools.postcss`](/configure/app/tools/postcss), here is an example:
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    postcss: {
-      plugins: ['autoprefixer', ('postcss-flexbugs-fixes': {})],
-    },
-  },
-});
-```

package/zh/guides/css/_category_.json

@@ -1,5 +0,0 @@
-{
-  "label": "CSS 开发方案",
-  "position": 5,
-  "collapsed": false
-}

package/zh/guides/css/css-in-js.mdx

@@ -1,40 +0,0 @@
----
-sidebar_position: 1
----
-
-# CSS-in-JS
-
-CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
-
-当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
-
-```js
-import styled from '@modern-js/runtime/styled';
-
-const RedDiv = styled.div`
-  color: red;
-`;
-```
-
-当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
-
-```js
-import styled from '@modern-js/runtime/styled';
-
-const Button = styled.button`
-  color: ${props => (props.primary ? 'white' : 'red')};
-  font-size: 1em;
-`;
-```
-
-关于 styled-components 的更多用法，请参考【[styled-components 官网](https://styled-components.com/)】。
-
-:::info 补充信息
-Modern.js 内部使用了 Babel 插件 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components)，可以通过 [`tools.styledComponents`](/configure/app/tools/styled-components) 对插件进行配置。
-
-:::
-
-:::tip 提示
-如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
-
-:::

package/zh/guides/css/css-modules.mdx

@@ -1,87 +0,0 @@
----
-sidebar_position: 5
----
-
-# CSS Modules
-
-Modern.js 为 [CSS Modules](https://github.com/css-modules/css-modules) 提供了开箱即用的支持。
-
-## 文件后缀形式 CSS Modules
-
-默认情况下，以 `.module.(css|scss|sass|less)` 结尾的文件会作为 CSS Modules 文件处理，例如：
-
-```css title="button.module.css"
-.redColor {
-  color: red;
-}
-```
-
-```js title="Button.jsx"
-import styles from './button.module.css';
-
-export default function Button() {
-  return (
-    <button type="button" className={styles.redColor}>
-      red button
-    </button>
-  );
-}
-```
-
-最终将被编译为
-
-```js
-<button type="button" className="button_redColor__1-RBg">
-  red button
-</button>
-```
-
-## 全面启用 CSS Modules
-
-如果想去掉文件名中 `.module` 后缀，可以设置 [`output.disableCssModuleExtension`](/configure/app/output/disable-css-module-extension)。
-
-设置后，除了 `node_modules/` 目录下的样式文件和文件名称格式为 `[name].global.(css|scss|sass|less)` 之外的所有样式文件，都会作为 CSS Modules 处理。
-
-如果此时需要全局样式，可以通过创建文件名称格式为 `[name].global.(css|less|scss|sass)` 的样式文件来解决， 例如:
-
-```css title="app.global.css"
-.bg-blue {
-  background-color: blue;
-}
-```
-
-```css title="button.css"
-.redColor {
-  color: red;
-}
-```
-
-```js title="App.jsx"
-import './app.global.css';
-import styles from './button.css';
-
-export default function Button() {
-  return (
-    <button type="button" className={`${styles.redColor} bg-blue`}>
-      button
-    </button>
-  );
-}
-```
-
-最终将被编译为:
-
-```js
-<button type="button" className="button__redColor--JsFYl bg-blue">
-  button
-</button>
-```
-
-最终效果如下：
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/more-css-modules.png)
-
-:::tip 提示
-使用 [babel-plugin-react-css-modules](https://github.com/gajus/babel-plugin-react-css-modules) 时需要注意，该插件的配置选项 `generateScopedName` 需要和 [`output.cssModuleLocalIdentName`](/configure/app/output/css-module-local-ident-name) 保持一致。
-
-:::

package/zh/guides/css/less-sass.mdx

@@ -1,17 +0,0 @@
----
-sidebar_position: 4
----
-
-# Less 和 Sass
-
-[Less](https://lesscss.org/) 和 [Sass](https://sass-lang.com/) 是常用的两种 CSS 预处理器，Modern.js 内置了 Less 和 Sass 编译能力的支持。
-
-## 自定义配置
-
-- 如果需要自定义 [less-loader](https://github.com/webpack-contrib/less-loader) 的配置，请参考 [tools.less](/configure/app/tools/less) 配置项。
-- 如果需要自定义 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的配置，请参考 [tools.less](/configure/app/tools/sass) 配置项。
-
-:::tip 提示
-经过 Less 和 Sass 预编译后的 CSS 文件，仍然会经过 Modern.js 内置的 [PostCSS](https://postcss.org/) 的转换，具备良好的浏览器兼容性。相关内容请参考【[PostCSS](/guides/css/postcss)】。
-
-:::

package/zh/guides/css/postcss.mdx

@@ -1,80 +0,0 @@
----
-sidebar_position: 3
----
-
-# PostCSS
-
-[PostCSS](https://postcss.org/) 是一个用 JavaScript 工具和插件转换 CSS 代码的工具。Modern.js 内置 PostCSS，并集成 [Autoprefixer](https://github.com/postcss/autoprefixer) 等常用的 PostCSS 插件，能够满足大多数项目的样式开发需求。
-
-默认情况下，Modern.js 会对 CSS 进行以下编译和转换：
-
-1. [Autoprefixer](https://github.com/postcss/autoprefixer) 根据需要支持的浏览器范围，会自动为 CSS 规则添加需要的浏览器厂商前缀。Modern.js 默认支持的浏览器范围为：`['> 0.01%', 'not dead', 'not op_mini all']`。
-
-:::info 注意
-
-- 【支持的浏览器范围为：`> 0.01%`】是指浏览器市场份额大于 0.01%。
-- `not dead` 是指不包含官方不再支持的浏览器和过去 24 个月没有更新的浏览器。
-- `not op_mini all` 是指不包含 Opera Mini。
-
-:::
-
-:::info 补充信息
-如果需要修改默认浏览器支持范围，可以在项目的 `package.json` 文件中配置 `browserslist`，设置规则参考 [Browserslist](https://github.com/browserslist/browserslist) 的使用，下面是一个示例：
-`json title="package.json" { "browserslist": [ "last 1 version", "> 1%", "IE 10" ] } `
-
-:::
-
-2. 提供 [CSS custom properties](https://www.w3.org/TR/css-variables-1/) 支持，可以在 CSS 中定义和使用自定义变量，如：
-
-```css
-:root {
-  --main-bg-color: pink;
-}
-
-body {
-  background-color: var(--main-bg-color);
-}
-```
-
-3. 提供 [CSS Nesting](https://drafts.csswg.org/css-nesting-1/) 支持，可以在 CSS 中使用嵌套写法，如：
-
-```css
-table.colortable td {
-  text-align: center;
-}
-table.colortable td.c {
-  text-transform: uppercase;
-}
-```
-
-也可以改写成 CSS 嵌套写法：
-
-```css
-table.colortable {
-  & td {
-    text-align: center;
-    &.c {
-      text-transform: uppercase;
-    }
-  }
-}
-```
-
-4. 修复已知的 [Flexbugs](https://github.com/philipwalton/flexbugs) 。
-5. 对以下 CSS 特性提供兼容：
-   - [`initial` 属性值](https://developer.mozilla.org/en-US/docs/Web/CSS/initial_value)
-   - [`break-` 属性](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
-   - [`font-variant`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
-   - [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#syntax_improvements_in_level_4)
-
-当需要修改 PostCSS 配置时，可以通过底层配置 [`tools.postcss`](/configure/app/tools/postcss) 来实现，下面是一个示例：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    postcss: {
-      plugins: ['autoprefixer', ('postcss-flexbugs-fixes': {})],
-    },
-  },
-});
-```