@modern-js/main-doc 2.59.0 → 2.60.0

package/docs/en/_meta.json

@@ -4,21 +4,26 @@
     "link": "/guides/get-started/introduction",
     "activeMatch": "/guides/"
   },
-  {
-    "text": "tutorials",
-    "link": "/tutorials/foundations/introduction",
-    "activeMatch": "/tutorials/"
-  },
   {
     "text": "configure",
     "link": "/configure/app/usage",
     "activeMatch": "/configure/"
   },
+  {
+    "text": "plugin-menu",
+    "link": "/plugin/introduction",
+    "activeMatch": "/plugin/"
+  },
   {
     "text": "apis",
     "link": "/apis/app/commands",
     "activeMatch": "/apis/"
   },
+  {
+    "text": "tutorials",
+    "link": "/tutorials/foundations/introduction",
+    "activeMatch": "/tutorials/"
+  },
   {
     "text": "community",
     "link": "/community/showcase",

package/docs/en/apis/app/hooks/api/lambda.mdx

@@ -4,54 +4,10 @@ sidebar_position: 3
 ---
 # lambda/*.[tj]s
 
-Files that declare API routes under the [BFF Framework Mode](/guides/advanced-features/bff/type.html#framework-mode). Except for [convention files](/apis/app/hooks/api/api#allow-list), files under the `lambda/` directory will be registered as the routes.
-
-:::info
-Using the `api` directory requires enabling the BFF function, and you need to run the new command to enable the "BFF" function under the project.
+After enabling BFF, the files under the `lambda/` directory will be registered as BFF routes according to conventions.
 
+:::note
+The files can be written in `js` or `ts` languages, but they must use `esm` syntax to export functions.
 :::
 
-:::tip
-This file supports using `js` or `ts` language, but must export functions using `esm` syntax.
-
-:::
-
-## Routing File Convention
-
-### Default Routing
-
-The routing system will map files named `index` to the previous directory.
-
-- `api/lambda/index.ts` -> `$BASENAME/`
-- `api/lambda/user/index.ts` -> `$BASENAME/user`
-
-### Nested Routing
-
-The routing system also supports parsing nested files. If you create a nested folder structure, the files will still automatically resolve routes in the same way.
-
-- `api/lambda/hello.ts` -> `$BASENAME/hello`
-- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Routing
-
-The routing system supports generating dynamic routes through file directories named with `[]`.
-
-- `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-
-The `$BASENAME` can be configured in `modern.config.js`, and the default value is `/api`.
-
-### Allow List
-
-By default, all files in the `lambda` directory are parsed as BFF function files, but we also set up a whitelist so that these files are not parsed:
-
-- Files named starting with `_`. For example: `_utils.ts`.
-- All files in a folder named starting with `_`. For example: `_utils/index.ts`, `_utils/cp.ts`.
-- Test files. For example: `foo.test.ts`.
-- TypeScript type files. For example: `hello.d.ts`.
-- Files under `node_module`.
-
-## Function Definition
-
-Completely consistent with the [Function Definition](/apis/app/hooks/api/api#function-definition) under the function mode.
+For detailed information, refer to [BFF API Routes](/guides/advanced-features/bff/function.html#api-routes).

package/docs/en/apis/app/hooks/api/middleware.mdx

@@ -0,0 +1,11 @@
+---
+title: _app.[tj]s
+sidebar_position: 2
+---
+# _app.[tj]s
+
+This file can add pre-middleware to BFF functions. For detailed information, refer to [Extend BFF Server](/guides/advanced-features/bff/extend-server).
+
+:::note
+For specific examples, please refer to [hook](/apis/app/runtime/bff/hook).
+:::

package/docs/en/community/blog/v2-release-note.mdx

@@ -132,7 +132,7 @@ Modern.js 可以划分为三个核心部分：**CLI 工具、服务端和运行
 
 在字节跳动内部，我们借助这些插件 API，结合公司内的基建和平台，封装出内部的企业级框架。如果你需要对 Modern.js 框架进行深度定制，也可以借助这些插件 API 来完成。
 
-> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/guides/topic-detail/framework-plugin/introduction.html)文档。
+> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/plugin/plugin-system/introduction.html)文档。
 
 ### 嵌套路由
 

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

@@ -1,5 +1,22 @@
-1. Execute `pnpm new` and select "Enable BFF"
-2. Add the following code to `modern.config.[tj]s` according to the chosen runtime framework:
+import { PackageManagerTabs } from '@theme';
+
+1. Execute the `new` command:
+
+<PackageManagerTabs command="run new" />
+
+2. Follow the prompts to **enable BFF functionality**:
+
+```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";
 

package/docs/en/components/extend-bff-function.mdx

@@ -0,0 +1,5 @@
+The standard BFF function writing method may not always meet your needs. We are designing a more powerful BFF function writing method to allow developers to extend BFF functions more conveniently.
+
+:::note
+Coming soon
+:::

package/docs/en/configure/app/auto-load-plugin.mdx

@@ -9,6 +9,10 @@ sidebar_position: 22
 
 Used to configure whether Modern.js enables auto-registration of plugins.
 
+:::warning
+This configuration is not recommended. Compared with manually registering plugin, this configuration is relatively black box and cannot add custom configurations to plugin.
+:::
+
 ### Manual Registration Plugin
 
 By default, installing the plugin requires you to register the plugin manually in the `modern.config.ts`.

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

@@ -9,7 +9,7 @@ sidebar_position: 9
 
 Used to configure custom Modern.js framework plugins.
 
-Refer to [How to Develop Plugins](/guides/topic-detail/framework-plugin/implement) for how to write custom plugins.
+Refer to [How to Develop Plugins](/plugin/plugin-system/implement) for how to write custom plugins.
 
 ## Note
 
@@ -33,7 +33,7 @@ Currently, Modern.js has opened up the ability to customize CLI plugins, and Ser
 
 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.
 
-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 [Relationship between plugins](/guides/topic-detail/framework-plugin/relationship) for more information.
+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 [Relationship between plugins](/plugin/plugin-system/relationship) for more information.
 
 ## Example
 

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

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-For config details, please refer to [Esbuild Plugin Configuration](/guides/rsbuild-plugins/plugin-esbuild.html#config).
+For config details, please refer to [Esbuild Plugin Configuration](/plugin/rsbuild-plugins/plugin-esbuild.html#config).

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

@@ -77,4 +77,4 @@ export default defineConfig({
 });
 ```
 
-For config details, please refer to [SWC Plugin Configuration](/guides/rsbuild-plugins/plugin-swc.html#config).
+For config details, please refer to [SWC Plugin Configuration](/plugin/cli-plugins/plugin-swc.html#config).

package/docs/en/guides/_meta.json

@@ -24,11 +24,6 @@
     "name": "topic-detail",
     "label": "topic"
   },
-  {
-    "type": "dir",
-    "name": "rsbuild-plugins",
-    "label": "Rsbuild Plugins"
-  },
   {
     "type": "dir",
     "name": "troubleshooting",

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

@@ -6,13 +6,16 @@
     "label": "use-bff",
     "collapsed": true
   },
-  "code-split",
+  {
+    "type": "dir",
+    "name": "page-performance",
+    "label": "page-performance",
+    "collapsed": true
+  },
+  "build-performance",
   "compatibility",
   "eslint",
   "low-level",
   "source-build",
-  "build-performance",
-  "inline-assets",
-  "optimize-bundle",
   "web-server"
 ]

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

@@ -1 +1 @@
-["function", "type", "frameworks", "sdk"]
+["function", "frameworks", "extend-server", "sdk"]

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

@@ -0,0 +1,154 @@
+# Extend BFF Server
+
+In some applications, developers may want to handle all BFF functions uniformly, such as for authentication, logging, data processing, etc.
+
+Modern.js provides two methods that allow developers to extend the BFF Server freely according to the runtime framework.
+
+## 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:
+
+```ts title="api/_app.ts"
+import { hook } from '@modern-js/runtime/server';
+import { Request, Response, NextFunction } from 'express';
+
+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();
+    }
+  });
+});
+```
+
+Then add a standard BFF function `api/lambda/hello.ts`:
+
+```ts title="api/lambda/hello.ts"
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+Next, in the frontend, add the code to access the API in `src/routes/page.tsx`, directly using the integrated method for the call:
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
+
+    fetchMyApi();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+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:
+
+![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`:
+
+:::note
+Here the login interface is not actually implemented; the code is just for demonstration.
+:::
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Refresh the page to 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**.
+:::

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

@@ -1,152 +1,81 @@
----
-sidebar_position: 3
----
+# Runtime Framework
 
-# Frameworks
+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/).
 
-Modern.js's BFF supports different runtime frameworks, currently Modern.js's BFF supports two runtime frameworks: [Express.js](https://expressjs.com/) and [Koa.js](https://koajs.com/).
+When using different runtime frameworks, some APIs may differ.
 
-## Function Mode
+## Accessing Request Context
 
-Under the function writing, only the middleware writing method of various runtime frameworks is different, and other implementations are basically the same. Take Express as an example to introduce how to write a middleware by hand in the `api/_ app.ts` and add permission verification:
+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:
 
-```ts
-import { hook } from '@modern-js/runtime/server';
-import { Request, Response, NextFunction } from 'express';
+import { Tabs, Tab as TabItem } from "@theme";
 
-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();
-    }
-  });
-});
-```
-
-Then add a normal BFF function `/api/hello.ts`:
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
 
-```ts
-export default async () => {
-  return 'Hello Modern.js';
+```ts title="api/lambda/hello.ts"
+import { useContext } from '@modern-js/runtime/express'
+export const get = async () => {
+  const { req } = useContext();
+  console.info(`access url: ${req.url}`);
+  return 'Hello Modern.js'
 };
 ```
 
-Finally, add the access code of the interface in the front-end `src/App.tsx`, and call it directly in an integrated way:
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
 
-```ts
-import { useState, useEffect } from 'react';
-import { get as hello } from '@api/hello';
-
-export default () => {
-  const [text, setText] = useState('');
-
-  useEffect(() => {
-    async function fetchMyApi() {
-      const { message } = await hello();
-      setText(message);
-    }
-
-    fetchMyApi();
-  }, []);
-
-  return <p>{text}</p>;
+```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'
 };
 ```
 
-Then exec `pnpm run dev` starts the project, and accessing `http://localhost:8080/` will find that the request for'/api/hello 'is blocked:
+  </TabItem>
+</Tabs>
 
-![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+:::info
+For more details, refer to [useContext](/apis/app/runtime/bff/use-context).
+:::
 
-Finally, modify the front-end code `src/App.tsx` to call the login interface before accessing `/api/hello`:
+## Using Middleware
 
-```ts
-import { useState, useEffect } from 'react';
-import { get as hello } from '@api/hello';
-import { post as login } from '@api/login';
+In BFF functions, you may need to use middleware to handle more logic. Depending on the runtime framework, you need to use different APIs:
 
-export default () => {
-  const [text, setText] = useState('');
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
 
-  useEffect(() => {
-    async function fetchAfterLogin() {
-      const { code } = await login();
-      if (code === 0) {
-        const { message } = await hello();
-        setText(message);
-      }
-    }
-    fetchAfterLogin();
-  }, []);
+```ts title="api/_app.ts"
+import { hook } from '@modern-js/runtime/express';
 
-  return <p>{text}</p>;
-};
+export default hook(({ addMiddleware }) => {
+  addMiddleware((req, res, next) => {
+    req.query.id = 'koa';
+    next();
+  });
+});
 ```
 
-Refresh the page and you can see that `/api/hello` was accessed successfully:
-
-![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
-
-The above code simulates the way to add middleware to the `/api/_app.ts` to achieve an easy login function. Also, other functions can be implemented in this hook file to extend BFF Server.
-
-## Framework Mode
-
-Under the framework writing, Modern.js does not collect middleware in the `api/_app.ts`, and the running process is controlled by the plugin itself.
-
-### Express
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
 
-The framework writing of Express supports defining the startup logic of API Server in `api/app.[tj]s`. performing the initialization work of the application, adding global middleware, declaring routes, and even extending the original framework.
+```ts title="api/_app.ts"
+import { hook } from '@modern-js/runtime/koa';
 
-The route defined by the BFF function will be registered after the route defined by the `app.ts` file, so here you can also intercept the route defined by the BFF function, preprocess or respond in advance.
-
-```ts title="api/app.ts"
-import express from 'express';
-
-const app = express();
-
-app.put('/user', function (req, res) {
-  res.send('Got a PUT request at /user');
-});
-
-app.use(async (req, res, next) => {
-  console.info(`access url: ${req.url}`);
-  next();
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    ctx.req.query.id = 'koa';
+    await next();
+  });
 });
-
-export default app;
 ```
 
-### Koa
-
-The Koa framework is written in a similar way to Express. It supports defining the startup logic of API Server in `app.[tj]s`, performing the initialization work of the application, adding global middleware, declaring routes, extending the original framework, etc.
-
-The route defined by the BFF function will be registered after the route defined by the `app.ts` file, so here you can also intercept the route defined by the BFF function, preprocess or respond in advance.
-
-:::caution
-Use the framework writing, when there is no `app.ts`, Modern.js will add koa-body by default. When there is `app.ts`, if the developer wants to use the BFF function with Body, he needs to ensure that the koa-body middleware has been added.
+  </TabItem>
+</Tabs>
 
+:::info
+For more details, refer to [hook](/apis/app/runtime/bff/hook).
 :::
-
-```ts title=api/app.ts
-import koa from 'koa';
-
-const app = new Koa();
-
-app.put('/user', function (req, res) {
-  res.send('Got a PUT request at /user');
-});
-
-app.use(async (ctx, next) => {
-  console.info(`access url: ${ctx.url}`);
-  await next();
-});
-
-export default app;
-```