@modern-js/main-doc 2.6.0 → 2.8.0

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/advanced-features/web-server.mdx

@@ -1,23 +1,37 @@
 ---
 title: Custom Web Server
-sidebar_position: 2
+sidebar_position: 3
 ---
 # Custom Web Server
 
-Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。
+As a client side-centric development framework, Modern.js has weak customization capabilities on the server side. In some development scenarios, special server level logic needs to be customized, such as user authentication, request preprocessing, and adding page rendering skeletons.
 
-因此 Modern.js 提供了一种功能，让项目可以在给定的范围内扩展 Modern.js 内置的 Web Server，来实现相应的需求。
+Some developers may be wondering, Modern.js already provides [BFF](/guides/advanced-features/bff/function.html), why do you need **Custom Web Server**.
 
-## 创建自定义 Web Server
+Because by default, page routing does not go through BFF, it has no way to provide server-side custom logic for page access. The reason for this design is that we do not want the service that controls the page to be bound to the BFF service, so as to avoid the BFF framework restricting how the page is deployed.
 
-在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「自定义 Web Serve」功能：
+For example, hosting pages separately from BFF, deploying page services to non-Node environments, or customizing for deployment platforms, etc.
+
+For the above reasons, Modern.js provides three ways that projects can customize server level capabilities progressively according to their needs.
+
+:::warning
+The three extension methods cannot work at the same time, and developers need to choose the appropriate method according to the scenario.
+:::
+
+## Extending Web Server with API
+
+The first way is to customize the server level at a specific life cycle through the server level runtime API provided by Modern.js. The purpose of providing this way is that in some cases, developers do not need to control the full Web Server, but only need to add server level logic.
+
+Because the full web server cannot be controlled this way, and the extension logic **only takes effect when the page is requested**. Therefore, it is relatively simple to apply to server level logic, and you do not want to create additional BFFs or BFFs and pages without common server level logic scenarios.
+
+You can execute the'pnpm run new 'command in the project root directory to enable the "Custom Web Serve" function:
 
 ```bash
-? 请选择你想要的操作 创建工程元素
-? 创建工程元素 新建「自定义 Web Server」源码目录
+? Action Create project element
+? New "Custom Web Server" source code directory
 ```
 
-执行命令后，在 `modern.config.ts` 中注册 Server 插件:
+After executing the command, register the `@modern-js/plugin-server` plugin in `modern.config.ts`:
 
 ```ts title="modern.config.ts"
 import serverPlugin from '@modern-js/plugin-server';
@@ -27,31 +41,84 @@ export default defineConfig({
 });
 ```
 
-项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
+After the function is turned on, the `server/index.ts` file will be automatically created in the project directory, and custom logic can be written in this file. Modern.js provides two types of APIs, **Hook** and **Middleware**, to extend Web Server.
+
+### Hook
 
-## 使用 API 扩展 Web Server
+The Hook provided by Modern.js is used to control the built-in logic in the Web Server, and all page requests go through the Hook.
 
-Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
+There are currently two Hooks provided, namely `AfterMatch` and `AfterRender`, which can be used to modify the rendering results. It can be written in `server/index.ts` like this:
 
-### Hook
+```ts
+import type { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (ctx, next) => {
+  next();
+}
+
+export const afterRender: AfterRenderHook = (ctx, next) => {
+  next();
+}
+```
 
-Hook 可以控制 Web Server 对请求处理的内置逻辑，非 BFF 请求会经过 Hook 的处理。
+Projects should have the following best practices when using Hook:
 
-Hook 不可以使用运行时框架拓展。
+1. Permission verification in afterMatch.
+2. Do Rewrite and Redirect in afterMatch.
+3. Do HTML content injection in afterRender.
 
-详细 API 可以查看 [Hook](/apis/app/runtime/web-server/hook)。
+:::note
+For more detail, see [Hook](/apis/app/runtime/web-server/hook)。
+:::
 
 ### Middleware
 
-Middleware 可以为 Web Server 添加前置中间件，只有 SSR 请求会经过 Middleware 的处理。
+For some projects, there may be more requirements at the server level, Modern.js provides Middleware to add pre-middleware for Web Server. It can only run in a Node environment, so if the project is deployed to another environment, such as a Worker environment, Middleware cannot be used.
 
-Middleware 可以使用运行时框架拓展。
+Modern.js provides a set of APIs by default for projects to use:
 
-详细 API 可以查看 [Hook](/apis/app/runtime/web-server/middleware)。
+```ts
+import { Middlewre } from '@modern-js/runtime/server';
 
-## 完全自定义的 Web Server
+export const middleware = (context, next) => {
+  const { source: { req, res } } = context;
+  console.log(req.url);
+  next();
+};
+```
 
 :::note
-敬请期待
+For more detail, see [Middleware] (/apis/app/runtime/web-server/middleware).
+:::
+
+Projects should have the following best practices when using Middleware:
+
+1. In Middleware, you can directly operate origin request and response objects, do event tracking, and inject Node services (databases, Redis, etc.) that may be used for SSR rendering.
+2. Marking and crawler optimization can be done in Middleware.
+3. In Middleware, you can ignore the default rendering and customize the rendering process.
+
+**In general, in CSR projects, using Hook can basically meet all the needs of simple scenarios. In SSR projects, Middleware can be used for more complex Node extensions.**
+
+## Managed Page Requests with BFF
+
+The second way is to use BFF to Managed page rendering. In this way, all requests will first hit the BFF service.
+
+This method can uniformly control the server level logic of all requests through BFF. Therefore, it is suitable for scenarios where the server level logic is complex, and BFF and pages need common server level logic. But it still relies on the Web Server of Modern.js as a whole, and cannot run the logic on existing services.
+
+To use this method, we need to first enable the "BFF" function through `pnpm new`. Then add [`bff.enableHandleWeb`](/configure/app/bff/enable-handle-web.html) configuration in the configuration file:
 
+```ts
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```
+
+When this value is set to `true`, page request traffic also goes through the BFF, and the logic built into Modern.js for page rendering defaults to running as the last middleware for the BFF service.
+
+## Fully Customized Web Server
+
+:::note
+Comming soon..
 :::

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/guides/concept/builder.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 **Modern.js uses [Modern.js Builder](https://modernjs.dev/builder) to build your Web App.**
 
-Modern.js Builder is one of the core components of Modern.js. It is A Build Engine for web development. and can be used independently of Modern.js. Modern.js Builder supports multiple bundlers such as webpack and rspack, and it uses webpack by default.
+Modern.js Builder is one of the core components of Modern.js. It is A build engine for web development. and can be used independently of Modern.js. Modern.js Builder supports multiple bundlers such as webpack and Rspack, and it uses webpack by default.
 
 ## Build Architecture
 

package/en/guides/topic-detail/framework-plugin/extend.mdx

@@ -1,24 +1,24 @@
 ---
-title: 扩展插件 Hook
+title: Extending
 sidebar_position: 5
 ---
-# 扩展插件 Hook
+# Extending Plugin Hooks
 
-本小节介绍如何通过动态注册 [Hook 模型](/guides/topic-detail/framework-plugin/hook) 的方式来扩展插件 Hook。
+This section describes how to extend plugin Hooks by dynamically registering [Hook models](/guides/topic-detail/framework-plugin/hook).
 
-## 示例
+## Example
 
-这里我们用一个简单的例子演示一下。假设我们要添加一些管理控制台输出信息的 Hook。
+Here is a simple example to demonstrate how to extend plugin Hooks by adding Hooks that manage console output.
 
-首先我们初始化一个空的项目文件，并添加基础依赖：
+First, we initialize an empty project file and add basic dependencies:
 
 ```bash
 $ npx @modern-js/create modern-js-demo
 ```
 
-### 创建 Hook
+### Creating Hooks
 
-我们先创建一个 Hook 模型：
+First, let's create a Hook model:
 
 ```ts title=config/plugin/myPlugin.ts
 import { createWaterfall } from '@modern-js/plugin';
@@ -26,7 +26,7 @@ import { createWaterfall } from '@modern-js/plugin';
 const message = createWaterfall<string[]>();
 ```
 
-然后注册它：
+then register:
 
 ```ts title=config/plugin/myPlugin.ts
 import type { CliPlugin } from '@modern-js/core';
@@ -40,7 +40,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-添加 Hook 类型：
+add Hook types:
 
 ```ts title=config/plugin/myPlugin.ts
 declare module '@modern-js/core' {
@@ -50,9 +50,9 @@ declare module '@modern-js/core' {
 }
 ```
 
-### 使用 Hook
+### Using Hooks
 
-创建插件，通过 `commands` Hook 函数，添加命令处理逻辑：
+Create a plugin and add command handling logic through the `commands` Hook function:
 
 ```ts title=config/plugin/myPlugin.ts
 import type { CliPlugin } from '@modern-js/core';
@@ -74,7 +74,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-最后 `config/plugin/myPlugin.ts` 的状态是：
+now `config/plugin/myPlugin.ts` is:
 
 ```ts title=config/plugin/myPlugin.ts
 import { createWaterfall } from '@modern-js/plugin';
@@ -109,7 +109,7 @@ declare module '@modern-js/core' {
 }
 ```
 
-然后在 `modern.config.ts` 中添加这个插件：
+Then add this plugin in `modern.config.ts`:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -120,9 +120,9 @@ export default defineConfig({
 });
 ```
 
-这时运行 `npx modern message` 就会执行相关逻辑，但由于没有收集到任何信息，所以控制台输出为空。
+Now, run `npx modern message`, and the related logic will be executed, but no information is collected, so the console output is empty.
 
-那这里我们添加一个：
+add:
 
 ```ts title=config/plugin/otherPlugin.ts
 import type { CliPlugin } from '@modern-js/core';
@@ -140,7 +140,7 @@ export default (): CliPlugin => ({
 });
 ```
 
-将它添加到配置中：
+add to config:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -152,7 +152,7 @@ export default defineConfig({
 });
 ```
 
-这时运行 `npx modern message` 就可以在控制台看到信息了：
+run `npx modern message`, then we can get follow in console：
 
 ```bash
 $ modern message
@@ -160,4 +160,5 @@ $ modern message
 [foo] line 1
 ```
 
-以上面这种方式就可以扩展出拥有各种能力的插件 Hook。
+By using the above approach, you can extend plugin Hooks with various capabilities.
+