@modern-js/main-doc 2.59.0 → 2.60.0

package/docs/en/{guides/rsbuild-plugins → plugin/cli-plugins}/plugin-swc.mdx

@@ -4,6 +4,13 @@ sidebar_position: 2
 
 # SWC Plugin
 
+:::warning
+**The SWC feature in the current document is no longer maintained**, we recommend using the Rspack + SWC solution.
+
+Please refer to [「Use Rspack」](guides/advanced-features/rspack-start) for more information.
+
+:::
+
 import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
 
 <SWC />

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

@@ -0,0 +1,5 @@
+# Tailwind CSS Plugin
+
+Tailwind CSS is a utility-first CSS framework and design system that allows you to quickly add commonly used styles to components while supporting flexible theme style extensions.
+
+For more details, refer to [Using Tailwind CSS](/guides/basic-features/css/tailwindcss).

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

@@ -0,0 +1,6 @@
+# Overview
+
+- [@modern-js/plugin-tailwindcss](/plugin/cli-plugins/plugin-tailwind): Enables the use of Tailwind CSS styles.
+- [@modern-js/plugin-bff](/plugin/cli-plugins/plugin-bff): Provides BFF services and unified invocation capabilities.
+- [@modern-js/plugin-ssg](/plugin/cli-plugins/plugin-ssg): Provides static site generation capabilities.
+- [@modern-js/plugin-swc](/plugin/cli-plugins/plugin-swc): Provides SWC compilation support.

package/docs/en/{guides/advanced-features/rsbuild-plugin.mdx → plugin/introduction.mdx}

@@ -1,11 +1,26 @@
----
-sidebar_position: 21
-title: Using Rsbuild Plugin
----
+# Plugin
 
-# Using Rsbuild Plugin
+In Modern.js, you can directly use two types of plugins: Modern.js framework plugins and Rsbuild plugins.
 
-## Introduce Rsbuild Plugin
+## Modern.js Framework Plugin
+
+Modern.js has its own framework plugin system. You can use Modern.js plugins by configuring the [`plugins`](/configure/app/plugins) field in `modern.config.ts`.
+
+### Plugin Types
+
+Framework plugins can be categorized into three types:
+
+1. [CLI Plugins](/plugin/cli-plugins): These are used to provide additional functionality when the Modern.js commands are executed in the application. Examples include adding commands, modifying configuration, and monitoring files. Most build-related capabilities can be achieved through CLI plugins.
+2. Server Plugins: These add extra functionality when the application receives requests. Examples include adding middleware and modifying request responses.
+3. Runtime Plugins: These provide additional functionality when the application runs React code. Examples include performing initialization actions and wrapping React higher-order components.
+
+:::note
+Server plugins and Runtime plugins are coming soon.
+:::
+
+### Developing Plugins
+
+If you need to develop Modern.js framework plugins, you can read [Modern.js Plugin System](/plugin/plugin-system/introduction) for more information.
 
 Rsbuild is the build tool of Modern.js. You can modify the default build behavior and add various additional features by adding the Rsbuild plugin, including but not limited to:
 
@@ -22,9 +37,15 @@ Modern.js has upgraded the build tool to [Rsbuild](https://rsbuild.dev/) startin
 If your current version is lower than MAJOR_VERSION.46.0, you can upgrade by executing `npx modern upgrade`.
 :::
 
-## Official Plugins
+:::info
+For more information about the Rsbuild plugin system, you can read [Rsbuild Official Site - Plugins](https://rsbuild.dev/plugins/list/index).
+:::
+
+## Rsbuild Plugin
 
-### Builtin Plugins
+### Official Plugins
+
+#### Builtin Plugins
 
 Here are the official Rsbuild plugins built into Modern.js:
 
@@ -44,10 +65,14 @@ Here are the official Rsbuild plugins built into Modern.js:
 | [YAML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                           | Used to import YAML files and convert them into JavaScript objects                                           | [TOML File](/guides/basic-features/static-assets/json-files.html#toml-file)                                                                         |
 | [TOML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml)                           | Used to import TOML files and convert them into JavaScript objects                                           | [YAML File](/guides/basic-features/static-assets/json-files.html#yaml-file)                                                                         |
 
-### Un-builtin Plugins
+#### Un-builtin Plugins
 
 Here are the official Rsbuild plugins that are not built into Modern.js:
 
 - [Image Compress Plugin](https://github.com/rspack-contrib/rsbuild-plugin-image-compress): Compress the image resources used in the project.
 - [Stylus Plugin](https://rsbuild.dev/plugins/list/plugin-stylus): Use Stylus as the CSS preprocessor.
 - [UMD Plugin](https://github.com/rspack-contrib/rsbuild-plugin-umd): Used to build outputs in UMD format.
+
+import OtherPlugins from '@site-docs-en/components/other-plugins.mdx';
+
+<OtherPlugins />

package/docs/en/{guides/topic-detail/framework-plugin → plugin/plugin-system}/extend.mdx

@@ -4,7 +4,7 @@ sidebar_position: 5
 
 # Extending Plugin Hooks
 
-This section describes how to extend plugin Hooks by dynamically registering [Hook models](/guides/topic-detail/framework-plugin/hook).
+This section describes how to extend plugin Hooks by dynamically registering [Hook models](/plugin/plugin-system/hook).
 
 ## Example
 

package/docs/en/{guides/topic-detail/framework-plugin → plugin/plugin-system}/implement.mdx

@@ -28,7 +28,7 @@ const myPlugin = {
 };
 ```
 
-In addition, plugins allow configuration of the execution order with other plugins. For more information, please refer to [Plugin Relationship](/guides/topic-detail/framework-plugin/relationship).
+In addition, plugins allow configuration of the execution order with other plugins. For more information, please refer to [Plugin Relationship](/plugin/plugin-system/relationship).
 
 ### Plugin Types
 
@@ -108,7 +108,7 @@ import type { MyPluginHook } from 'xxx';
 const myPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
 ```
 
-Please refer to [Extending Hooks](/guides/topic-detail/framework-plugin/extend) for detailed explanations.
+Please refer to [Extending Hooks](/plugin/plugin-system/extend) for detailed explanations.
 
 ### Plugin Configuration
 
@@ -151,7 +151,7 @@ export const myPlugin = (): CliPlugin => ({
 });
 ```
 
-For more detail [Plugin API](/guides/topic-detail/framework-plugin/plugin-api).
+For more detail [Plugin API](/plugin/plugin-system/plugin-api).
 
 ### Async setup
 

package/docs/en/{guides/topic-detail/framework-plugin → plugin/plugin-system}/plugin-api.mdx

@@ -44,7 +44,7 @@ interface UserConfig {
 Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
 
 :::tip
-This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/guides/topic-detail/framework-plugin/hook-list.html#config).
+This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/plugin/plugin-system/hook-list.html#config).
 :::
 
 ### useResolvedConfigContext
@@ -67,7 +67,7 @@ interface NormalizedConfig {
 Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
 
 :::tip
-This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/guides/topic-detail/framework-plugin/hook-list.html#config).
+This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/plugin/plugin-system/hook-list.html#config).
 :::
 
 ### useAppContext

package/docs/en/plugin/rsbuild-plugins/_meta.json

@@ -0,0 +1 @@
+["plugin-esbuild"]

package/docs/en/plugin/rsbuild-plugins.mdx

@@ -0,0 +1,3 @@
+# Overview
+
+- [@modern-js/plugin-esbuild](/plugin/rsbuild-plugins/plugin-esbuild): Provides esbuild compilation support.

package/docs/zh/_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/zh/apis/app/hooks/api/lambda.mdx

@@ -2,56 +2,13 @@
 title: lambda/*.[tj]s
 sidebar_position: 3
 ---
-# lambda/*.[tj]s
-
-在 [BFF 框架写法](/guides/advanced-features/bff/type.html#框架写法)下，声明 API 路由的文件。除了[某些约定文件](/apis/app/hooks/api/lambda#白名单)外，`lambda/` 目录下的文件会被注册为接口的路由。
-
-:::info
-使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
 
-:::
+# lambda/*.[tj]s
 
-:::tip
-该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
+开启 BFF 后，`lambda/` 目录下的文件会按照约定被注册为 BFF 的路由。
 
+:::note
+文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
 :::
 
-## 路由规则
-
-### 默认路由
-
-路由系统会将以 `index` 命名的文件会被映射到上一层目录。
-
-- `api/lambda/index.ts` -> `$BASENAME/`
-- `api/lambda/user/index.ts` -> `$BASENAME/user`
-
-### 多级路由
-
-路由系统也支持解析多级的文件，如果创建文件夹结构，文件仍会以相同方式自动解析路由。
-
-- `api/lambda/hello.ts` -> `$BASENAME/hello`
-- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
-
-### 动态路由
-
-路由系统支持通过 `[]` 命名的文件目录生成动态路由。
-
-- `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`
-
-其中的 `$BASENAME` 可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
-
-### 白名单
-
-默认 `lambda` 目录下所有文件都会当作 BFF 函数文件去解析，但同样我们也设置了白名单，这些文件不被被解析：
-
-- 命名以 `_` 开头的文件。例如：`_utils.ts`。
-- 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
-- 测试文件。例如：`foo.test.ts`。
-- TypeScript 类型文件。例如：`hello.d.ts`。
-- `node_module` 下的文件。
-
-## 函数定义
-
-和函数写法下[函数定义](/apis/app/hooks/api/api#函数定义)完全一致。
+详细内容可以参考 [BFF 函数路由](/guides/advanced-features/bff/function.html#函数路由)。

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

@@ -0,0 +1,11 @@
+---
+title: _app.[tj]s
+sidebar_position: 2
+---
+# _app.[tj]s
+
+该文件可以为 BFF 函数添加前置中间件，详细内容参考 [扩展 BFF Server](/guides/advanced-features/bff/extend-server)。
+
+:::note
+具体示例请参考 [hook](/apis/app/runtime/bff/hook)。
+:::

package/docs/zh/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/zh/components/enable-bff.mdx

@@ -1,5 +1,22 @@
-1. 执行 `pnpm new`，选择启用 BFF
-2. 根据选择的运行时框架，将下面的代码添加到 `modern.config.[tj]s` 中：
+import { PackageManagerTabs } from '@theme';
+
+1. 执行 `new` 命令：
+
+<PackageManagerTabs command="run new" />
+
+2. 按照提示，选择**启用 BFF 功能**：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 启用「BFF」功能
+? 请选择 BFF 类型 框架模式
+```
+
+:::note
+目前推荐使用框架模式创建 BFF，后续我们将会移除 BFF 类型的概念。
+:::
+
+3. 根据选择的运行时框架，将下面的代码添加到 `modern.config.[tj]s` 中：
 
 import { Tabs, Tab as TabItem } from "@theme";
 

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

@@ -0,0 +1,5 @@
+普通的 BFF 函数写法有时并不能满足需求，我们正在设计一套更强大的 BFF 函数写法，让开发者更方便地扩展 BFF 函数。
+
+:::note
+敬请期待
+:::

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

@@ -9,6 +9,10 @@ sidebar_position: 22
 
 用于配置 Modern.js 是否开启自动注册插件。
 
+:::warning
+该配置不推荐使用，相比手动注册插件，该配置相对黑盒且无法为插件添加自定义配置。
+:::
+
 ### 手动注册插件
 
 默认情况下，安装插件后，你需要在 `modern.config.ts` 文件中手动注册插件。

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

@@ -9,7 +9,7 @@ sidebar_position: 9
 
 用于配置自定义的 Modern.js 框架插件。
 
-自定义插件的编写方式请参考 [如何编写插件](/guides/topic-detail/framework-plugin/implement)。
+自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system/implement)。
 
 ## 注意事项
 
@@ -33,7 +33,7 @@ Modern.js 中内置了三种不同的框架插件：
 
 默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
 
-当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/guides/topic-detail/framework-plugin/relationship)。
+当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件之间的关系](/plugin/plugin-system/relationship)。
 
 ## 示例
 

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

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [esbuild 插件配置](/guides/rsbuild-plugins/plugin-esbuild.html#配置)。
+完整配置项请参考 [esbuild 插件配置](/plugin/rsbuild-plugins/plugin-esbuild#配置)。

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

@@ -77,4 +77,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [SWC 插件配置](/guides/rsbuild-plugins/plugin-swc.html#配置)。
+完整配置项请参考 [SWC 插件配置](/plugin/cli-plugins/plugin-swc.html#配置)。

package/docs/zh/guides/_meta.json

@@ -24,11 +24,6 @@
     "name": "topic-detail",
     "label": "topic"
   },
-  {
-    "type": "dir",
-    "name": "rsbuild-plugins",
-    "label": "构建插件"
-  },
   {
     "type": "dir",
     "name": "troubleshooting",

package/docs/zh/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/zh/guides/advanced-features/bff/_meta.json

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

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

@@ -0,0 +1,156 @@
+# 扩展 BFF Server
+
+部分应用中，开发者可能希望对所有 BFF 函数做统一的处理，例如鉴权、日志、数据处理等。
+
+Modern.js 提供了两种方式，允许开发者根据运行时框架自由扩展 BFF Server。
+
+## 中间件
+
+开发者可以在编写 `api/_app.ts` 文件中编写中间件，用来扩展 BFF Server。以 Express 作为运行时框架为例，介绍如何手写一个中间件，添加权限校验：
+
+```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();
+    }
+  });
+});
+```
+
+
+然后添加一个普通的 BFF 函数 `api/lambda/hello.ts`：
+
+```ts title="api/lambda/hello.ts"
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+接下来，在前端 `src/routes/page.tsx` 添加接口的访问代码，直接使用一体化的方式调用：
+
+```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>;
+};
+```
+
+现在运行 `dev` 命令启动项目，访问 `http://localhost:8080/` 会发现 `/api/hello` 的请求被拦截了：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+最后修改前端代码 `src/routes/page.tsx`，在访问 `/api/hello` 前先调用登录接口：
+
+:::note
+此处没有真实实现登录接口，代码仅作为演示。
+:::
+
+```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>;
+};
+```
+
+刷新页面，可以看到 `/api/hello` 访问成功：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+以上代码模拟了在 `/api/_app.ts` 中添加中间件的方式，实现了简易的登录功能。同样，可以在这个钩子文件中实现其他功能来扩展 BFF Server。
+
+:::info
+不同运行时框架中，中间件的写法不一定相同，详情可见[运行时框架](/guides/advanced-features/bff/frameworks)。
+
+:::
+
+## 定义 Server 实例
+
+除了中间件之外，还可以通过 `api/app.ts` 文件来定义 BFF Server 的实例。开发者需要默认导出一个能被运行时框架插件识别的实例。这里简单展示一下 Koa 和 Express 如何定义 Server 实例。
+
+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>
+
+在复杂的 BFF 逻辑中，定义 Server 实例可以更方便通过一个入口来组织代码逻辑，设计目录结构。在这个文件中，可以执行初始化逻辑，添加全局中间件，声明路由，甚至扩展原有框架。
+
+BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
+
+:::note
+此时，如果应用中同时存在 `api/_app.ts`，则定义的中间件会被放在 `api/app.ts` 导出实例的最后执行。多数情况下，中间件就能覆盖大多数 BFF 函数的定制需求。只有当应用的服务端逻辑比较复杂时，才需要自定义 Server 实例。
+:::
+
+:::caution
+当应用中没有 `api/app.ts` 的时候，Modern.js 默认会添加 [koa-body](https://www.npmjs.com/package/koa-body)。当应用中存在 `api/app.ts` 时，如果开发者希望使用带有 Body 的 BFF 函数，需要**自行添加** `koa-body`。
+:::