@modern-js/main-doc 2.67.5 → 2.67.6

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,233 @@
 sidebar_position: 16
 ---
 
-# Custom Web Server (Not Recommended)
+# Custom Web Server
 
-:::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).
+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.
+
+## Starting a Custom Web Server
+
+:::info
+You must ensure that the Modern.js version is x.67.5 or above.
 :::
 
-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.
+To start a custom web server, the following steps need to be taken:
+1. Add and install the dependencies `@modern-js/server-runtime` and `ts-node` to `devDependencies`.
+2. Add `server` to the `include` section of `tsconfig`.
+3. Create a file `server/modern.server.ts` 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:
 
-Modern.js provides two types of APIs to extend the Web Server: **Middleware** and **Lifecycle Hooks**.
+<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
-Middleware and Hooks only take effect when users request page routes, and BFF routes won't pass through these APIs.
+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`.
 :::
 
-## Enabling Custom Web Server
+Usage is as follows:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
 
-Developers can execute the `pnpm run new` command in the project root directory to enable the "Custom Web Server" feature:
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
 
-```bash
-? Select operation: Create project element
-? Select element type: Create "Custom Web Server" source directory
+  await next();
+
+  const end = Date.now();
+  // Report Duration
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
 ```
 
-After executing the command, register the `@modern-js/plugin-server` plugin in `modern.config.ts`:
+:::warning
+You must execute the `next` function to proceed with the subsequent Middleware.
+:::
+
 
-```ts title="modern.config.ts"
-import { serverPlugin } from '@modern-js/plugin-server';
+### RenderMiddleware
 
-export default defineConfig({
-  plugins: [..., serverPlugin()],
+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;
+      },
+    };
+  },
 });
 ```
 
-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="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import serverPlugin from './plugins/serverPlugin';
+
+export default defineServerConfig({
+  plugins: [serverPlugin()],
+});
+```
+
+
+```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).
+:::
 
 ### Unstable Middleware
 
@@ -102,7 +293,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 +344,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

package/docs/en/guides/basic-features/deploy.mdx

@@ -285,6 +285,7 @@ Add the following script to `packages/app/package.json` to run `build` command o
 ```
 
 Add the following content to the `packages/app/vercel.json` file:
+
 ```json title="vercel.json"
 {
   "buildCommand": "npm run deploy",
@@ -298,7 +299,7 @@ Just submit your code and deploy it using the Vercel platform.
 
 If you're creating a GitHub Pages for a repository without a custom domain, the page URL will follow this format: `http://<username>.github.io/<repository-name>`. Therefore, you need to add the following configuration in `modern.config.ts`:
 
-```
+```ts
 import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
@@ -331,7 +332,6 @@ For branch deployment, follow these steps:
 :::info
 1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
 2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
-
 :::
 
 For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
@@ -407,7 +407,7 @@ Nginx is a high-performance HTTP and reverse proxy server that can handle static
 
 If your project is a purely front-end project, you can also deploy the application through Nginx. Here is an example of an Nginx configuration to demonstrate how to host the output of a purely front-end project.
 
-```conf title="nginx.conf"
+```nginx title="nginx.conf"
 # user [user] [group];
 worker_processes 1;
 

package/docs/en/guides/basic-features/output-files.mdx

@@ -96,34 +96,6 @@ dist
     └── qux.[hash].mp4
 ```
 
-## Node.js Output Directory
-
-When you enable SSR or SSG features in Modern.js, Modern.js will generate a Node.js bundle after the build and output it to the `bundles` directory.
-
-```bash
-dist
-├── bundles
-│   └── [name].js
-├── static
-└── html
-```
-
-Node.js files usually only contain JS files, no HTML or CSS. Also, JS file names will not contain hash.
-
-You can modify the output path of Node.js files through the [output.distPath.server](/configure/app/output/dist-path) config.
-
-For example, output Node.js files to the `server` directory:
-
-```ts
-export default {
-  output: {
-    distPath: {
-      server: 'server',
-    },
-  },
-};
-```
-
 ## Flatten the Directory
 
 Sometimes you don't want the dist directory to have too many levels, you can set the directory to an empty string to flatten the generated directory.

package/docs/en/tutorials/first-app/c04-routes.mdx

@@ -118,10 +118,11 @@ import { Radio } from 'antd';
 
 Then modify the top of the UI to add a set of radio group:
 
-```tsx {4-9}
+```tsx
 export default function Layout() {
   return (
     <div>
+      // [!code highlight:6]
       <div className="h-16 p-2 flex items-center justify-center">
         <Radio.Group onChange={handleSetList} value={currentList}>
           <Radio value="/">All</Radio>
@@ -146,8 +147,9 @@ import { Outlet, useLocation, useNavigate } from '@modern-js/runtime/router';
 
 Finally, add local state and related logic to the Layout component:
 
-```tsx {2-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   const navigate = useNavigate();
   const location = useLocation();
   const [currentList, setList] = useState(location.pathname || '/');