@modern-js/main-doc 2.67.5 → 2.67.7

package/docs/en/configure/app/tools/style-loader.mdx

@@ -1,6 +1,5 @@
 ---
 title: styleLoader
-configName: tools.styleLoader
 ---
 
 # tools.styleLoader
@@ -10,6 +9,6 @@ configName: tools.styleLoader
 
 The config of [style-loader](https://github.com/webpack-contrib/style-loader) can be set through `tools.styleLoader`.
 
-import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 
-<RsbuildConig />
+<RsbuildConfig configName="tools.styleLoader" />

package/docs/en/configure/app/tools/swc.mdx

@@ -21,7 +21,7 @@ When using Rspack as the bundler, SWC will be used for transpiling and compressi
 
 You can set the options of [builtin:swc-loader](https://rspack.dev/guide/features/builtin-swc-loader) through `tools.swc`.
 
-```
+```ts
 import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig<'rspack'>({

package/docs/en/configure/app/tools/terser.mdx

@@ -4,6 +4,10 @@ title: terser
 
 # tools.terser
 
+import { Badge } from '@theme';
+
+<Badge type="danger" >Webpack Only</Badge>
+
 - **Type:** `Object | Function | undefined`
 - **Default:**
 
@@ -17,8 +21,6 @@ const defaultTerserOptions = {
 };
 ```
 
-- **Bundler:** `only support webpack`
-
 When building for production, Modern.js will minimize the JavaScript code through [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin). The config of [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin) can be modified via `tools.terser`.
 
 ### Object Type

package/docs/en/configure/app/tools/ts-loader.mdx

@@ -4,9 +4,12 @@ title: tsLoader
 
 # tools.tsLoader
 
+import { Badge } from '@theme';
+
+<Badge type="danger" >Webpack Only</Badge>
+
 - **Type:** `Object | Function | undefined`
 - **Default:** `undefined`
-- **Bundler:** `only support webpack`
 
 :::warning Deprecated
 

package/docs/en/configure/app/tools/webpack-chain.mdx

@@ -4,9 +4,12 @@ title: webpackChain
 
 # tools.webpackChain
 
+import { Badge } from '@theme';
+
+<Badge type="danger" >Webpack Only</Badge>
+
 - **Type:** `Function | undefined`
 - **Default:** `undefined`
-- **Bundler:** `only support webpack`
 
 You can modify the webpack configuration by configuring `tools.webpackChain` which is type of `Function`. The function receives two parameters, the first is the original webpack chain object, and the second is an object containing some utils.
 

package/docs/en/configure/app/tools/webpack.mdx

@@ -4,9 +4,12 @@ title: webpack
 
 # tools.webpack
 
+import { Badge } from '@theme';
+
+<Badge type="danger" >Webpack Only</Badge>
+
 - **Type:** `Object | Function | undefined`
 - **Default:** `undefined`
-- **Bundler:** `only support webpack`
 
 `tools.webpack` is used to configure [webpack](https://webpack.js.org/).
 

package/docs/en/guides/advanced-features/_meta.json

@@ -23,6 +23,5 @@
     "label": "server-monitor",
     "collapsed": true
   },
-  "custom-server",
   "web-server"
 ]

package/docs/en/guides/advanced-features/bff/extend-server.mdx

@@ -1,35 +1,41 @@
 # Extend BFF Server
 
-In some applications, developers may want to handle all BFF functions uniformly, such as for authentication, logging, data processing, etc.
+In some applications, developers may want to handle all BFF functions uniformly, such as authentication, logging, data processing, etc.
 
-Modern.js provides two methods that allow developers to extend the BFF Server freely according to the runtime framework.
+Modern.js allows users to freely extend the BFF Server through [Middleware](/guides/advanced-features/web-server.html#middleware) method.
 
-## Middleware
+## Using Middleware
 
-Developers can write middleware in the `api/_app.ts` file to extend the BFF Server. Taking Express as the runtime framework, here is an example of how to write a middleware to add permission checks:
+Developers can use middleware by configuring middlewares in `server/modern.server.ts`. The following describes how to write a BFF middleware manually to add permission verification:
 
-```ts title="api/_app.ts"
-import { hook } from '@modern-js/runtime/server';
-import { Request, Response, NextFunction } from 'express';
+```ts title="server/modern.server.ts"
+import {
+  type MiddlewareHandler,
+  defineServerConfig,
+} from '@modern-js/server-runtime';
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (req: Request, res: Response, next: NextFunction) => {
-    if (req.url !== '/api/login') {
-      const sid = req?.cookies?.sid;
-      if (!sid) {
-        res.status(400);
-        res.json({ code: -1, message: 'need login' });
-      } else {
-        next();
-      }
-    } else {
-      next();
+const requireAuthForApi: MiddlewareHandler = async (c, next) => {
+  if (c.req.path.startsWith('/api') && c.req.path !== '/api/login') {
+    const sid = c.req.cookie('sid');
+    if (!sid) {
+      return c.json({ code: -1, message: 'need login' }, 400);
     }
-  });
+  }
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'require-auth-for-api',
+      handler: requireAuthForApi,
+    },
+  ]
 });
+
 ```
 
-Then add a standard BFF function `api/lambda/hello.ts`:
+Then add a regular BFF function `api/lambda/hello.ts`:
 
 ```ts title="api/lambda/hello.ts"
 export default async () => {
@@ -37,7 +43,7 @@ export default async () => {
 };
 ```
 
-Next, in the frontend, add the code to access the API in `src/routes/page.tsx`, directly using the integrated method for the call:
+Next, in the frontend `src/routes/page.tsx`, add the interface access code and directly use the integrated method to call:
 
 ```ts title="src/routes/page.tsx"
 import { useState, useEffect } from 'react';
@@ -59,14 +65,14 @@ export default () => {
 };
 ```
 
-Now run the `dev` command to start the project, and visit `http://localhost:8080/`. You will find that the request to `/api/hello` is intercepted:
+Now run the `dev` command to start the project, and access `http://localhost:8080/` to find that the request for `/api/hello` has been intercepted:
 
 ![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
 
-Finally, modify the frontend code in `src/routes/page.tsx` to call the login interface before accessing `/api/hello`:
+Finally, modify the frontend code `src/routes/page.tsx`, and call the login interface before accessing `/api/hello`:
 
 :::note
-Here the login interface is not actually implemented; the code is just for demonstration.
+This part does not implement a real login interface; the code is just for demonstration.
 :::
 
 ```ts
@@ -92,63 +98,8 @@ export default () => {
 };
 ```
 
-Refresh the page to see that the access to `/api/hello` is successful:
+Refresh the page, and you can see that the access to `/api/hello` is successful:
 
 ![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
 
-The above code simulates adding middleware in `api/_app.ts` to implement simple login functionality. Similarly, other functionalities can be implemented in this hook file to extend the BFF Server.
-
-:::info
-The way middleware is written may differ depending on the runtime framework. For details, see [Runtime Frameworks](/guides/advanced-features/bff/frameworks).
-:::
-
-## Define Server Instance
-
-In addition to middleware, you can also define a BFF Server instance via the `api/app.ts`. Developers need to export an instance that can be recognized by the runtime framework plugin. Here is a simple demonstration of how to define a server instance with Koa and Express.
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-<Tabs>
-  <TabItem value="express" label="Express.js" default>
-
-```ts title="api/app.ts"
-import express from 'express';
-
-const app = express();
-app.use(async (req, res, next) => {
-  console.info(`access url: ${req.url}`);
-  next();
-});
-
-export default app;
-```
-
-  </TabItem>
-  <TabItem value="koa" label="Koa.js">
-
-```ts title="api/app.ts"
-import koa from 'koa';
-
-const app = new Koa();
-app.use(async (ctx, next) => {
-  console.info(`access url: ${ctx.url}`);
-  await next();
-});
-
-export default app;
-```
-
-  </TabItem>
-</Tabs>
-
-In complex BFF logic, defining a server instance allows for easier organization of code logic and directory structure design through a single entry point. In this file, you can perform initialization logic, add global middleware, declare routes, and even extend the original framework.
-
-The routes defined by the BFF functions will be registered after the routes defined in the `app.ts` file. Therefore, you can also intercept the routes defined by the BFF functions here for preprocessing or early responses.
-
-:::note
-At this time, if `api/_app.ts` exists in the application, the defined middleware will be executed after the middleware exported by the `api/app.ts` instance. In most cases, middleware can cover most customization needs for BFF functions. Only when the application's server-side logic is more complex do you need to customize the server instance.
-:::
-
-:::caution
-When `api/app.ts` does not exist in the application, Modern.js will default to adding [koa-body](https://www.npmjs.com/package/koa-body). When `api/app.ts` does exist in the application, if developers wish to use BFF functions with bodies, they will need to **add `koa-body` themselves**.
-:::
+The above code simulates defining middleware in `server/Modern.server.ts` and implements a simple login function. Similarly, other functionalities can be implemented in this configuration file to extend the BFF Server.

package/docs/en/guides/advanced-features/bff/frameworks.mdx

@@ -1,81 +1,25 @@
-# Runtime Framework
-
-Modern.js BFF supports different runtime frameworks. Currently, Modern.js BFF supports two runtime frameworks: [Express.js](https://expressjs.com/) and [Koa.js](https://koajs.com/).
+---
+sidebar_position: 3
+title: Runtime Framework
+---
 
-When using different runtime frameworks, some APIs may differ.
-
-## Accessing Request Context
+# Runtime Framework
 
-In BFF functions, you may need to access the request context to handle more logic. Depending on the runtime framework, you need to use different APIs:
+Modern.js uses [Hono.js](https://hono.dev/) as the BFF and Server runtime framework, so you can [extend BFF Server](/guides/advanced-features/bff/extend-server.html) based on the Hono.js ecosystem.
 
-import { Tabs, Tab as TabItem } from "@theme";
+## Getting Request Context
 
-<Tabs>
-  <TabItem value="express" label="Express.js" default>
+Sometimes in BFF functions, it's necessary to obtain the request context to handle more logic. In such cases, you can use `useHonoContext` to get it:
 
 ```ts title="api/lambda/hello.ts"
-import { useContext } from '@modern-js/runtime/express'
+import { useHonoContext } from '@modern-js/plugin-bff/hono'
 export const get = async () => {
-  const { req } = useContext();
-  console.info(`access url: ${req.url}`);
+  const c = useHonoContext();
+  console.info(`access url: ${c.req.url}`);
   return 'Hello Modern.js'
 };
 ```
 
-  </TabItem>
-  <TabItem value="koa" label="Koa.js">
-
-```ts title="api/lambda/hello.ts"
-import { useContext } from '@modern-js/runtime/koa'
-export const get = async () => {
-  const ctx = useContext();
-  console.info(`access url: ${req.url}`);
-  return 'Hello Modern.js'
-};
-```
-
-  </TabItem>
-</Tabs>
-
-:::info
-For more details, refer to [useContext](/apis/app/runtime/bff/use-context).
-:::
-
-## Using Middleware
-
-In BFF functions, you may need to use middleware to handle more logic. Depending on the runtime framework, you need to use different APIs:
-
-<Tabs>
-  <TabItem value="express" label="Express.js" default>
-
-```ts title="api/_app.ts"
-import { hook } from '@modern-js/runtime/express';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware((req, res, next) => {
-    req.query.id = 'koa';
-    next();
-  });
-});
-```
-
-  </TabItem>
-  <TabItem value="koa" label="Koa.js">
-
-```ts title="api/_app.ts"
-import { hook } from '@modern-js/runtime/koa';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx, next) => {
-    ctx.req.query.id = 'koa';
-    await next();
-  });
-});
-```
-
-  </TabItem>
-</Tabs>
-
 :::info
-For more details, refer to [hook](/apis/app/runtime/bff/hook).
+For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-hono-context).
 :::

package/docs/en/guides/advanced-features/page-performance/_meta.json

@@ -1 +1 @@
-["code-split", "inline-assets", "optimize-bundle"]
+["code-split", "inline-assets", "optimize-bundle", "react-compiler"]

package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx

@@ -0,0 +1,44 @@
+# React Compiler
+
+The React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.
+
+Before starting to use the React Compiler, it is recommended to read the [React Compiler documentation](https://zh-hans.react.dev/learn/react-compiler) to understand its features, current status, and usage.
+
+## How to Use
+
+The steps to use the React Compiler in Modern.js are as follows:
+
+1. Modern.js does not officially support React 19 yet, but you can install `react-compiler-runtime@rc` in React 17 or 18 projects to allow the compiled code to run on versions before 19.
+
+2. Currently, the React Compiler only provides a Babel plugin, so you need to install `babel-plugin-react-compiler`.
+
+3. Register the Babel plugin in your Modern.js configuration file:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+  },
+  tools: {
+    babel(_, { addPlugins }) {
+      addPlugins([
+        [
+          'babel-plugin-react-compiler',
+          {
+            target: '18',
+          },
+        ],
+      ]);
+    },
+  },
+  plugins: [
+    appTools({
+      bundler: 'rspack',
+    }),
+  ],
+});
+```
+
+> For detailed code, you can refer to the [Modern.js & React Compiler example project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/react-compiler)

package/docs/en/guides/advanced-features/web-server.mdx

@@ -2,42 +2,245 @@
 sidebar_position: 16
 ---
 
-# Custom Web Server (Not Recommended)
-
-:::warning
-Custom Web Server is compatible but no longer recommended. For extending Server capabilities, please refer to [Custom Server](/guides/advanced-features/custom-server.html). For migration guide, see [Migrate to the New Version of Custom Server](/guides/advanced-features/web-server.html#migrate-to-the-new-version-of-custom-server).
-:::
+# Custom Web Server
 
 Modern.js encapsulates most server-side capabilities required by projects, typically eliminating the need for server-side development. However, in certain scenarios such as user authentication, request preprocessing, or adding page skeletons, custom server-side logic may still be necessary.
 
-Modern.js provides two types of APIs to extend the Web Server: **Middleware** and **Lifecycle Hooks**.
+## Starting a Custom Web Server
 
-:::note
-Middleware and Hooks only take effect when users request page routes, and BFF routes won't pass through these APIs.
+:::info
+You must ensure that the Modern.js version is x.67.5 or above.
 :::
 
-## Enabling Custom Web Server
-
-Developers can execute the `pnpm run new` command in the project root directory to enable the "Custom Web Server" feature:
+Developers can execute the `pnpm run new` command in the project root directory to start the "Custom Web Server" feature:
 
 ```bash
 ? Select operation: Create project element
 ? Select element type: Create "Custom Web Server" source directory
 ```
 
-After executing the command, register the `@modern-js/plugin-server` plugin in `modern.config.ts`:
+After executing the command, a `server/modern.server.ts` file will be automatically created in the project directory, where you can write custom logic.
+
+
+## Capabilities of the Custom Web Server
+
+In the `server/modern.server.ts` file, you can add the following configurations to extend the Server:
+- **Middleware**
+- **Render Middleware**
+- **Server-side Plugin**
+
+In the **Plugin**, you can define **Middleware** and **RenderMiddleware**. The middleware loading process is illustrated in the following diagram:
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/10eh7nuhpenuhog/server-md-wf.png"
+  style={{ width: '100%', maxWidth: '540px' }}
+/>
+
+### Basic Configuration
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [],
+  renderMiddlewares: [],
+  plugins: [],
+});
+```
+
+
+### Type Definition
+
+`defineServerConfig` type definition is as follows:
+
+```ts
+import type { MiddlewareHandler } from 'hono';
+
+type MiddlewareOrder = 'pre' | 'post' | 'default';
+type MiddlewareObj = {
+    name: string;
+    path?: string;
+    method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+    handler: MiddlewareHandler | MiddlewareHandler[];
+    before?: Array<MiddlewareObj['name']>;
+    order?: MiddlewareOrder;
+};
+type ServerConfig = {
+    middlewares?: MiddlewareObj[];
+    renderMiddlewares?: MiddlewareObj[];
+    plugins?: (ServerPlugin | ServerPluginLegacy)[];
+}
+```
+
+
+### Middleware
+
+Middleware supports executing custom logic before and after the **request handling** and **page routing** processes in Modern.js services.
+If custom logic needs to handle both API routes and page routes, Middleware is the clear choice.
+
+:::note
+If you only need to handle BFF API routes, you can determine whether a request is for a BFF API by checking if `req.path` starts with the BFF `prefix`.
+:::
+
+Usage is as follows:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // Report Duration
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```
+
+:::warning
+You must execute the `next` function to proceed with the subsequent Middleware.
+:::
+
+
+### RenderMiddleware
+
+If you only need to handle the logic before and after page rendering, modern.js also provides rendering middleware, which can be used as follows:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+// Inject render performance metrics
+const renderTiming: MiddlewareHandler = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  c.res.headers.set('server-timing', `render; dur=${end - start}`);
+};
+
+// Modify the Response Body
+const modifyResBody: MiddlewareHandler = async (c, next) => {
+  await next();
+
+  const { res } = c;
+  const text = await res.text();
+  const newText = text.replace('<body>', '<body> <h3>bytedance</h3>');
+
+  c.res = c.body(newText, {
+    status: res.status,
+    headers: res.headers,
+  });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [
+    {
+      name: 'render-timing',
+      handler: renderTiming,
+    },
+    {
+      name: 'modify-res-body',
+      handler: modifyResBody,
+    },
+  ],
+});
+```
+
+
+### Plugin
+
+Modern.js supports adding the aforementioned middleware and rendering middleware for the Server in custom plugins, which can be used as follows:
+
+
+```ts title="server/plugins/server.ts"
+import type { ServerPluginLegacy } from '@modern-js/server-runtime';
+
+export default (): ServerPluginLegacy => ({
+  name: 'serverPlugin',
+  setup(api) {
+    return {
+      prepare(serverConfig) {
+        const { middlewares, renderMiddlewares } = api.useAppContext();
+
+        // Inject server-side data for page dataLoader consumption
+        middlewares?.push({
+          name: 'server-plugin-middleware',
+          handler: async (c, next) => {
+            c.set('message', 'hi modern.js');
+            await next();
+            // ...
+          },
+        });
+
+        // redirect
+        renderMiddlewares?.push({
+          name: 'server-plugin-render-middleware',
+          handler: async (c, next) => {
+            const user = getUser(c.req);
+            if (!user) {
+              return c.redirect('/login');
+            }
+
+            await next();
+          },
+        });
+        return serverConfig;
+      },
+    };
+  },
+});
+```
+
 
-```ts title="modern.config.ts"
-import { serverPlugin } from '@modern-js/plugin-server';
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import serverPlugin from './plugins/serverPlugin';
 
-export default defineConfig({
-  plugins: [..., serverPlugin()],
+export default defineServerConfig({
+  plugins: [serverPlugin()],
 });
 ```
 
-Once enabled, a `server/index.ts` file will be automatically created in the project directory where custom logic can be implemented.
 
-## Custom Web Server Capabilities
+```ts title="src/routes/page.data.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const ctx = useHonoContext();
+  // SSR scenario consumes data injected by the Server Side
+  const message = ctx.get('message');
+
+  // ...
+};
+
+```
+
+
+## Legacy API (Deprecated)
+
+:::warning
+The legacy API is compatible but no longer recommended. For extending server capabilities, please refer to [Custom Web Server](/guides/advanced-features/web-server.html#custom-web-server). For migration guidelines, see [Migrating to the New Version of Custom Web Server](/guides/advanced-features/web-server.html#migrate-to-the-new-version-of-custom-web-server).
+:::
+
+### Enable
+To enable the custom Web Server feature, follow these steps:
+1. Add `@modern-js/plugin-server`、`tsconfig-paths` and `ts-node` to `devDependencies` and install them.
+2. Add `server` to the `include` section of `tsconfig`.
+3. Register the `@modern-js/plugin-server` plugin in `modern.config.ts`.
+4. Create a `server/index.ts` file in the project directory, where you can write custom logic.
 
 ### Unstable Middleware
 
@@ -102,7 +305,7 @@ For detailed API and more usage, see [Hook](/apis/app/runtime/web-server/hook).
 :::
 
 
-## Migrate to the New Version of Custom Server
+## Migrate to the New Version of Custom Web Server
 
 ### Migration Background
 
@@ -153,7 +356,7 @@ Differences between UnstableMiddleware Context and Hono Context:
 | `c.request`              | `c.req.raw`                   | Refer to [HonoRequest raw](https://hono.dev/docs/api/request#raw) documentation         |
 | `c.response`             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation       |
 | `c.route`                | `c.get('route')`              | Get application context information.                                                          |
-| `loaderContext.get`      | `honoContext.get`             | After injecting data using `c.set`, consume in dataLoader: the old version uses `loaderContext.get`, refer to the new version in [Plugin](/guides/advanced-features/custom-server.html#using-posture-2) example    |
+| `loaderContext.get`      | `honoContext.get`             | After injecting data using `c.set`, consume in dataLoader: the old version uses `loaderContext.get`, refer to the new version in [Plugin](/guides/advanced-features/web-server.html#plugin) example    |
 
 
 #### Middleware