@modern-js/main-doc 0.0.0-nightly-20250514160342 → 0.0.0-nightly-20250518160324

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

@@ -6,14 +6,20 @@ sidebar_position: 16
 
 Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
 
+## 开启自定义 Server
+
+开启自定义 Server 功能，需要执行以下步骤：
+1. devDependencies 增加 `@modern-js/server-runtime` 及 `ts-node`依赖并安装。
+2. `tsconfig` 的 `include` 中添加 `server`。
+3. 项目目录下创建 `server/modern.server.ts` 文件，可以在这个文件中编写自定义逻辑。
+
 ## 自定义 Server 能力
 
-项目目录下创建 `server/modern.server.ts` 文件，可以在这个文件中添加如下配置来扩展 Server：
+`server/modern.server.ts` 文件中添加如下配置来扩展 Server：
 - **中间件（Middleware）**
 - **渲染中间件（RenderMiddleware）**
 - **服务端插件（Plugin）**
 
-
 其中 **Plugin** 中可以定义 **Middleware** 与 **RenderMiddleware**。 中间件加载流程如下图所示：
 
 <img
@@ -58,20 +64,18 @@ type ServerConfig = {
 ### Middleware
 
 Middleware 支持在 Modern.js 服务的**请求处理**与**页面路由**的流程前后，执行自定义逻辑。
-即自定义逻辑既要处理接口路由，也要作用于页面路由，那么 Middleware 是不二选择。如果仅需要处理 BFF 接口路由，可以通过配置 `path` 为 BFF 的 `prefix` 来实现。
+即自定义逻辑既要处理接口路由，也要作用于页面路由，那么 Middleware 是不二选择。
+
+如果仅需要处理 BFF 接口路由，可以通过检查 `req.path` 是否以 BFF `prefix` 开头，来判断是否为 BFF 接口请求。
 
-:::note
-BFF 场景只有[运行时框架](/guides/advanced-features/bff/frameworks.html)为 Hono 时，BFF 路由才会经过 Middleware。
-:::
 
 #### 使用姿势
 
 ```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/zh/plugin/cli-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 本文档详细介绍了 Modern.js CLI 插件的 API。CLI 插件允许您在 Modern.js 项目的构建和开发过程中扩展和定制功能。
 
+:::info
+
+CLI 插件需要通过 `modern.config.ts` 中的 [`plugins`](/configure/app/plugins) 字段配置。
+
+:::
+
 ## 插件基础结构
 
 一个典型的 CLI 插件结构如下：

package/docs/zh/plugin/runtime-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 Modern.js 的 Runtime 插件允许您在应用程序的 React 代码运行时扩展和修改其行为。通过 Runtime 插件，您可以轻松地执行初始化任务、实现 React 高阶组件（HOC）封装等功能。
 
+:::info
+
+Runtime 插件需要通过 `src/modern.runtime.ts` 中的 [`plugins`](/configure/app/runtime/plugins) 字段配置。
+
+:::
+
 ## 插件结构
 
 一个典型的 Runtime 插件如下所示：

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

@@ -118,8 +118,9 @@ import { Radio } from 'antd';
 
 然后将 UI 最顶部进行修改，增加一组单选框
 
-```tsx {4-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   return (
     <div>
       <div className="h-16 p-2 flex items-center justify-center">
@@ -146,8 +147,9 @@ import { Outlet, useLocation, useNavigate } from '@modern-js/runtime/router';
 
 最后在 Layout 组件里增加局部状态和相关逻辑：
 
-```tsx {2-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   const navigate = useNavigate();
   const location = useLocation();
   const [currentList, setList] = useState(location.pathname || '/');

package/docs/zh/tutorials/first-app/c05-loader.mdx

@@ -56,11 +56,13 @@ Data Loader 并非只为 SSR 工作。在 CSR 项目中，Data Loader 也可以
 
 Modern.js 也提供了一个叫 `useLoaderData` 的 hooks API，我们修改 `src/routes/page.tsx` 导出的组件：
 
-```tsx {1,2,5,13}
+```tsx
+// [!code highlight:2]
 import { useLoaderData } from '@modern-js/runtime/router';
 import type { LoaderData } from './page.data';
 
 function Index() {
+  // [!code highlight:1]
   const { data } = useLoaderData() as LoaderData;
 
   return (
@@ -68,6 +70,7 @@ function Index() {
       <Helmet>
         <title>All</title>
       </Helmet>
+      // [!code highlight:1]
       <List
         dataSource={data}
         renderItem={info => <Item key={info.name} info={info} />}

package/package.json

@@ -15,17 +15,19 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-nightly-20250514160342",
+  "version": "0.0.0-nightly-20250518160324",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "0.0.0-nightly-20250514160342"
+    "@modern-js/sandpack-react": "0.0.0-nightly-20250518160324"
   },
   "devDependencies": {
-    "@rspress/shared": "1.43.11",
+    "@rsbuild/plugin-sass": "1.3.1",
+    "@shikijs/transformers": "^3.4.1",
+    "@rspress/shared": "2.0.0-beta.5",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
     "classnames": "^2.5.1",
@@ -33,7 +35,7 @@
     "fs-extra": "^10",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rspress": "1.43.11",
+    "rspress": "2.0.0-beta.5",
     "ts-node": "^10.9.1",
     "typescript": "^5"
   },

package/rspress.config.ts

@@ -1,4 +1,6 @@
 import path from 'path';
+import { pluginSass } from '@rsbuild/plugin-sass';
+import { transformerNotationHighlight } from '@shikijs/transformers';
 import { defineConfig } from 'rspress/config';
 
 const docPath = path.join(__dirname, 'docs');
@@ -12,7 +14,9 @@ export default defineConfig({
   themeDir: path.join(__dirname, 'src'),
   markdown: {
     checkDeadLinks: true,
-    experimentalMdxRs: true,
+    shiki: {
+      transformers: [transformerNotationHighlight()],
+    },
   },
   search: {
     codeBlocks: true,
@@ -91,5 +95,6 @@ export default defineConfig({
         '@site': require('path').resolve(__dirname),
       },
     },
+    plugins: [pluginSass()],
   },
 });

package/src/components/RsbuildLink/index.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { useLang } from 'rspress/runtime';
 
-const RsbuildLInk = ({ configName }: { configName: string }) => {
+const RsbuildLink = ({ configName }: { configName: string }) => {
   const lang = useLang();
   const href = `https://rsbuild.dev/${lang === 'zh' ? 'zh/' : ''}config/${configName
     .split('.')
@@ -16,4 +16,4 @@ const RsbuildLInk = ({ configName }: { configName: string }) => {
   );
 };
 
-export default RsbuildLInk;
+export default RsbuildLink;

package/src/index.ts

@@ -1,9 +1,5 @@
-import Theme from 'rspress/theme';
 import HomeLayout from './pages';
 
-export default {
-  ...Theme,
-  HomeLayout,
-};
+export { HomeLayout };
 
 export * from 'rspress/theme';

package/src/pages/index.tsx

@@ -1,6 +1,6 @@
 import clsx from 'clsx';
 import { useEffect } from 'react';
-import { Helmet, useLocation } from 'rspress/runtime';
+import { Head, useLocation } from 'rspress/runtime';
 import ContentCard from '../components/ContentCard';
 import { FeatureLayout } from '../components/FeatureLayout';
 import Footer from '../components/Footer';
@@ -94,7 +94,7 @@ export default function Home() {
 
   return (
     <div>
-      <Helmet>
+      <Head>
         <html className="dark" />
         <script>window.MODERN_THEME = 'dark';</script>
         <style type="text/css">{`
@@ -102,7 +102,7 @@ export default function Home() {
             display: none!important;
           }
         `}</style>
-      </Helmet>
+      </Head>
       <HomepageHeader />
       <main className={styles['homepage-main']}>
         <FeatureLayout>

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

@@ -1,11 +0,0 @@
----
-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/apis/app/runtime/bff/hook.mdx

@@ -1,44 +0,0 @@
----
-title: hook
----
-# hook
-
-Used to add framework middleware under BFF function mode, the middleware will execute before BFF function.
-
-## Usage
-
-according to the framework extend plugin, export from the corresponding namespace:
-
-```ts
-import { hook } from '@modern-js/runtime/{namespace}';
-```
-
-## Function Signature
-
-```ts
-type HookOptions = {
-  addMiddleware: string | function;
-};
-
-function hook(options: HookOptions): void;
-```
-
-### Input
-
-- `options`: a range of hooks provided by Modern.js.
-  - `addMiddleware`: add middlewares for BFF.
-
-## Example
-
-middleware for different frameworks should be different(an example is when using the koa framework):
-
-```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();
-  });
-});
-```

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

@@ -1,38 +0,0 @@
----
-title: useContext
----
-# useContext
-
-Used to get the request context in the BFF function.
-
-## Usage
-
-according to the framework extend plugin, export from the corresponding namespace:
-
-```ts
-import { useContext } from '@modern-js/runtime/{namespace}';
-```
-
-## Function Signature
-
-`function useContext(): any`
-
-## Example
-
-Developers can get more request information through `context`, such as browser UA(an example is when using the koa framework):
-
-```ts
-import { useContext } from '@modern-js/runtime/koa';
-
-export async function get() {
-  const ctx = useContext();
-  return ctx.req.headers['user-agent'];
-}
-```
-
-:::caution
-only in BFF function, `useContext` API can be used.
-
-:::
-
-Although the `useContext` API is supported in any framework extend plugin, the types of return values are different.

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

@@ -1,11 +0,0 @@
----
-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/apis/app/runtime/bff/hook.mdx

@@ -1,44 +0,0 @@
----
-title: hook
----
-# hook
-
-用于在 BFF 函数写法下添加框架中间件，添加的中间件的执行会在 BFF 函数定义的路由之前。
-
-## 使用姿势
-
-根据使用的框架拓展插件，从对应的命名空间中导出：
-
-```ts
-import { hook } from '@modern-js/runtime/{namespace}';
-```
-
-## 函数签名
-
-```ts
-type HookOptions = {
-  addMiddleware: string | function;
-};
-
-function hook(options: HookOptions): void;
-```
-
-### 参数
-
-- `options`: Modern.js 提供的一系列钩子。
-  - `addMiddleware`: 添加 BFF 中间件的钩子。
-
-## 示例
-
-使用不同的框架，应添加不同框架的中间件（示例为使用 koa 框架时）：
-
-```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();
-  });
-});
-```

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

@@ -1,38 +0,0 @@
----
-title: useContext
----
-# useContext
-
-用于在一体化 BFF 函数中获取请求上下文。
-
-## 使用姿势
-
-根据使用的框架拓展插件，从对应的命名空间中导出：
-
-```ts
-import { useContext } from '@modern-js/runtime/{namespace}';
-```
-
-## 函数签名
-
-`function useContext(): any`
-
-## 示例
-
-开发者可以通过 `context` 获取更多的请求信息，例如获取请求 UA（示例为使用 koa 框架时）：
-
-```ts
-import { useContext } from '@modern-js/runtime/koa';
-
-export async function get() {
-  const ctx = useContext();
-  return ctx.req.headers['user-agent'];
-}
-```
-
-:::caution 注意
-只有在一体化 BFF 函数中，你才可以使用 `useContext` API 。
-
-:::
-
-使用不同的运行时框架时，虽然均支持 `useContext` API，但它们的返回值的类型是不同的。