@modern-js/main-doc 0.0.0-nightly-20250513160312 → 0.0.0-nightly-20250515160310

package/docs/en/apis/app/hooks/server/server.mdx

@@ -0,0 +1,10 @@
+---
+title: modern.server.[tj]s
+sidebar_position: 1
+---
+
+# modern.server.[tj]s
+
+This file extends the Modern.js Server. In this file, you can configure [Middleware](/guides/advanced-features/custom-server.html#middleware), [RenderMiddleware](/guides/advanced-features/custom-server.html#rendermiddleware), or [Plugin](/guides/advanced-features/custom-server.html#plugin) for the Server that starts with the Modern.js project.
+
+You can intercept and handle requests and responses, perform authentication and role checks, preprocess requests, and handle exceptions, etc. You can also insert specific business logic into the built-in processing logic (including route matching, resource addressing, header injection, page rendering, and static web hosting).

package/docs/en/apis/app/runtime/bff/use-hono-context.mdx

@@ -0,0 +1,30 @@
+---
+title: useHonoContext
+---
+# useHonoContext
+
+Used to obtain Hono context in an integrated BFF function.
+
+## Usage
+
+```ts
+import { useHonoContext } from '@modern-js/plugin-bff/hono';
+```
+
+## Function Signature
+
+`function useHonoContext(): Context`
+
+## Example
+
+Developers can use `context` to obtain more request information, such as setting response headers:
+
+```ts
+import { useHonoContext } from '@modern-js/plugin-bff/hono';
+
+export async function get() {
+  const c = useHonoContext();
+  c.res.headers.set('x-bff-api', 'true');
+  // ...
+}
+```

package/docs/en/components/enable-bff.mdx

@@ -9,40 +9,14 @@ import { PackageManagerTabs } from '@theme';
 ```bash
 ? Please select the operation you want to perform Enable optional features
 ? Please select the feature to enable Enable "BFF"
-? Please select BFF type Framework mode
 ```
 
-:::note
-Currently, it is recommended to create BFF in framework mode. We will remove the BFF type concept in the future.
-:::
-
 3. Depending on the chosen runtime framework, add the following code to `modern.config.[tj]s`:
 
-import { Tabs, Tab as TabItem } from "@theme";
-
-<Tabs>
-  <TabItem value="express" label="Express.js" default>
-
-```ts title="modern.config.ts"
-import { expressPlugin } from '@modern-js/plugin-express';
-import { bffPlugin } from '@modern-js/plugin-bff';
-
-export default defineConfig({
-  plugins: [expressPlugin(), bffPlugin()],
-});
-```
-
-  </TabItem>
-  <TabItem value="koa" label="Koa.js">
-
 ```ts title="modern.config.ts"
-import { koaPlugin } from '@modern-js/plugin-koa';
 import { bffPlugin } from '@modern-js/plugin-bff';
 
 export default defineConfig({
-  plugins: [koaPlugin(), bffPlugin()],
+  plugins: [bffPlugin()],
 });
 ```
-
-  </TabItem>
-</Tabs>

package/docs/en/components/tech-stack-node-framework.mdx

@@ -1 +1 @@
-Modern.js supports [Express.js](https://expressjs.com/) and [Koa.js](https://koajs.com/) as optional BFF runtime frameworks. Please refer to the [BFF - Frameworks](/guides/advanced-features/bff/frameworks.html) for more information.
+Modern.js Server and BFF use [Hono.js](https://hono.dev/) as the runtime framework, and you can extend the Server based on the Hono.js ecosystem. Please refer to [Custom Server](/guides/advanced-features/custom-server.html).

package/docs/en/configure/app/plugins.mdx

@@ -1,47 +1,27 @@
----
-sidebar_position: 9
----
-
 # plugins
 
 - **Type:** `CliPlugin[]`
 - **Default:** `[]`
 
-Used to configure custom Modern.js framework plugins.
-
-Refer to [How to Develop Plugins](/plugin/plugin-system) for how to write custom plugins.
+Used to configure custom Modern.js framework CLI plugins. For information on how to create custom CLI plugins, please refer to [How to Write CLI Plugins](/plugin/introduction.html#cli-plugins).
 
 ## Note
 
-This option is used to configure framework plugins. If you need to configure other types of plugins, please choose the corresponding configuration method:
-
-- Use [builderPlugins](/configure/app/builder-plugins) to configure Rsbuild plugins.
-- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack or webpack plugins.
-- Use [tools.babel](/configure/app/tools/babel) to configure Babel plugins.
-
-## Plugin types
-
-Modern.js has three types of plugins:
-
-- `CLI plugins`, applicable to local development, compilation and construction stages, can extend various capabilities in the command line and compilation stages.
-- `Server plugins`, applicable to the server.
-- `Runtime plugins`, applicable to the front-end runtime.
-
-Currently, Modern.js has opened up the ability to customize CLI plugins, and Server plugins and Runtime plugins will be opened up later.
-
-## Plugin execution order
+This option is **specifically for configuring framework CLI plugins**. If you need to configure other types of plugins, use the appropriate configuration method:
 
-By default, custom plugins are executed in the order of the `plugins` array, and the execution time of built-in Modern.js plugins is earlier than that of custom plugins.
+- Use [builderPlugins](/configure/app/builder-plugins) for Rsbuild plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) for Rspack or webpack plugins.
+- Use [tools.babel](/configure/app/tools/babel) for Babel plugins.
+- Use the [plugins field in runtime config](/configure/app/runtime/plugins) for framework Runtime plugins.
 
-When the plugin sets options that control the order, such as `pre` and `post`, the execution order will be adjusted based on the declared fields. Refer to [Plugins Structure](/plugin/plugin-system) for more information.
 
-## Example
+## Examples
 
-The following is an example of using CLI plugins.
+Below are examples of using CLI plugins:
 
-### Use plugins on npm
+### Using plugins from npm
 
-To use plugins from npm registry, you need to first install the plugins , and import them in `modern.config.ts`.
+To use plugins from the npm registry, first install the plugins and then import them in your configuration:
 
 ```ts title="modern.config.ts"
 import { myPlugin } from 'my-plugin';
@@ -51,9 +31,9 @@ export default defineConfig({
 });
 ```
 
-### Use local plugins
+### Using local plugins
 
-To use local plugins, import them directly using a relative path.
+To use plugins from your local repository, import them directly using a relative path:
 
 ```ts title="modern.config.ts"
 import { myPlugin } from './config/plugin/myPlugin';
@@ -65,7 +45,7 @@ export default defineConfig({
 
 ### Plugin configuration
 
-If the plugin provides some custom configuration options, they can be passed in as parameters to the plugin function.
+If a plugin provides custom configuration options, pass them as parameters to the plugin function:
 
 ```ts title="modern.config.ts"
 import { myPlugin } from 'my-plugin';

package/docs/en/configure/app/runtime/master-app.mdx

@@ -1,8 +1,4 @@
----
-title: masterApp
----
-
-# runtime.masterApp
+# masterApp
 
 - **Type:** `Object`
 

package/docs/en/configure/app/runtime/plugins.mdx

@@ -0,0 +1,58 @@
+# plugins
+
+- **Type:** `RuntimePlugin[]`
+- **Default:** `[]`
+
+Used to configure custom Modern.js Runtime plugins. For details on how to create custom Runtime plugins, please refer to [How to Write Runtime Plugins](/plugin/introduction#runtime-plugins).
+
+:::info
+
+Runtime plugins must be configured in the `plugins` array within the `src/modern.runtime.ts` file.
+
+:::
+
+## Examples
+
+Here are examples demonstrating how to use Runtime plugins:
+
+### Using plugins from npm packages
+
+To use plugins published on npm, first install them via your package manager, then import them into your configuration.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from 'my-plugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Using local plugins
+
+To use plugins from your local codebase, import them directly using relative paths.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Plugin configuration
+
+If a plugin supports custom configuration options, you can provide them as arguments to the plugin function.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin({
+    foo: 1,
+    bar: 2,
+  })],
+});
+```

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 the [Custom Server](/guides/advanced-features/custom-server.html) 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/bff.mdx

@@ -6,7 +6,7 @@ title: BFF
 
 BFF (Backends for Frontends) is an architectural pattern primarily used to address issues of data aggregation in front-end and back-end collaboration. Under the BFF architecture, front-end applications do not communicate directly with backend services. Instead, they interact with backend services through a dedicated BFF middleware layer, custom-made for the front end.
 
-The main problems it to solve include:
+The main problems it tries to solve include:
 
 - Aggregation, mapping, clipping, and proxying of lower-level APIs according to their own business needs.
 - Cache data for some specific scenarios to improve performance and thus improve user experience.

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

@@ -6,12 +6,19 @@ sidebar_position: 16
 
 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.
 
-## Custom Server Capabilities
+## Starting a Custom Server
 
-Create the `server/modern.server.ts` file in the project directory, and you can add the following configurations to extend the Server:
+To start a custom 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 Server
+
+In the `server/modern.server.ts` file, you can add the following configurations to extend the Server:
 - **Middleware**
 - **Render Middleware**
-- **Server Plugin**
+- **Server-side Plugin**
 
 In the **Plugin**, you can define **Middleware** and **RenderMiddleware**. The middleware loading process is illustrated in the following diagram:
 
@@ -60,20 +67,17 @@ type ServerConfig = {
 ### Middleware
 
 Middleware supports executing custom logic before and after the **request handling** and **page routing** processes in Modern.js services.
-That is, if custom logic needs to handle both API routes and affect page routes, then Middleware is the obvious choice. If you only need to handle BFF API routes, this can be achieved by configuring the `path` to the BFF's `prefix`.
+If custom logic needs to handle both API routes and page routes, Middleware is the clear choice.
 
-:::note
-In the BFF scenario, BFF routing will only go through Middleware when the [runtime framework](/guides/advanced-features/bff/frameworks.html) is Hono.
-:::
+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`.
 
 #### Using Posture
 
 ```ts title="server/modern.server.ts"
 import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
-import { getMonitors } from '@modern-js/runtime';
 
 export const handler: MiddlewareHandler = async (c, next) => {
-  const monitors = getMonitors();
+  const monitors = c.get('monitors');
   const start = Date.now();
 
   await next();

package/docs/en/guides/advanced-features/page-performance/inline-assets.mdx

@@ -96,6 +96,8 @@ When you reference a static asset in your CSS file, you can also force the asset
 :::tip Do you really need to exclude assets from inlining?
 Excluding assets from inlining will increase the number of assets that the Web App needs to load. This will reduce the efficiency of loading assets in a weak network environment or in scenarios where HTTP2 is not enabled. Please use force no Inline with caution.
 
+:::
+
 ## Inline JS files
 
 In addition to inlining static assets into JS files, Modern.js also supports inlining JS files into HTML files.

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -4,7 +4,7 @@ sidebar_position: 13
 
 # Bundle Size Optimization
 
-Bundle size optimization is an important part in production environment because it directly affects the user experience of online users. In this document, we will introduce some common bundle size optimization methods in Modern.js.
+Bundle size optimization is an important part of optimizing your production environment because it directly affects the user experience. In this document, we will introduce some common bundle size optimization methods in Modern.js.
 
 ## Reduce duplicate dependencies
 

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

@@ -8,7 +8,7 @@ Modern.js provides **JSX syntax** and **HTML(EJS) syntax** to customize the HTML
 
 ## JSX Syntax
 
-According to Modern.js conventions, you can create a `Document.[jt]sx` file under `src/` or the entry directory and default export a component". The rendering result of this component can be used as the HTML template of the entry.
+According to Modern.js conventions, you can create a `Document.[jt]sx` file under `src/` or the entry directory and default export a component. The rendering result of this component can be used as the HTML template of the entry.
 
 For example, consider the following directory structure:
 
@@ -218,9 +218,9 @@ The implementation of custom HTML fragments is to merge the fragments with the b
 
 :::
 
-### Custom the entire HTML Template
+### Customize the entire HTML Template
 
-In some cases, HTML fragments may be is not better meet the customization requirements. Modern.js provides a fully customized way.
+In some cases, HTML fragments may not offer enough control. Modern.js provides a fully customized way.
 
 :::caution Note
 It is generally not recommended to directly override the default HTML template, as some functional options may be lost. If it is truly necessary to customize the entire HTML template, it is recommended to modify based on the built-in template as needed.

package/docs/en/plugin/cli-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 This document details the API for Modern.js CLI plugins. CLI plugins allow you to extend and customize the functionality of Modern.js projects during the build and development process.
 
+:::info
+
+CLI plugins need to be configured via the [`plugins`](/configure/app/plugins) field in `modern.config.ts`.
+
+:::
+
 ## Plugin Basic Structure
 
 A typical CLI plugin structure is as follows: