@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -6,28 +6,54 @@ sidebar_position: 16
 
 Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
 
+要在 Modern.js 项目中使用自定义 Web Server，请按照以下步骤操作：
 
-## 开启自定义 Web Server
+1. 安装 `@modern-js/server-runtime` 依赖
 
-:::tip
-必须确保 Modern.js 版本是 x.67.5 及以上。
-:::
+如果项目尚未安装 `@modern-js/server-runtime` 依赖，请先安装：
+
+```bash
+pnpm add @modern-js/server-runtime
+```
 
-开发者可以在项目根目录执行 `pnpm run new` 命令，开启「自定义 Web Server」功能：
+:::tip 版本一致性
+请确保 `@modern-js/server-runtime` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/server-runtime`：
 
 ```bash
-? 请选择你想要的操作 创建工程元素
-? 请选择创建元素类型 新建「自定义 Web Server」源码目录
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<版本号>
 ```
 
-执行命令后，项目目录下会自动创建 `server/modern.server.ts` 文件，可以在这个文件中编写自定义逻辑。
+:::
+
+2. 创建 `server` 目录和配置文件
+
+在项目根目录下创建 `server/modern.server.ts` 文件：
 
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // 中间件
+  renderMiddlewares: [], // 渲染中间件
+  plugins: [], // 插件
+  onError: () => {}, // 错误处理
+});
+```
+
+创建文件后，可以在这个文件中编写自定义逻辑。
 
 ## 自定义 Web Server 能力
 
 Modern.js 的服务器基于 Hono 实现，在最新版本的自定义 Web Server 中，我们向用户暴露了 Hono 的中间件能力，你可以参考 [Hono 文档](https://hono.dev/docs/api/context) 了解更多用法。
 
 `server/modern.server.ts` 文件中添加如下配置来扩展 Server：
+
 - **中间件（Middleware）**
 - **渲染中间件（RenderMiddleware）**
 - **服务端插件（Plugin）**
@@ -52,7 +78,6 @@ export default defineServerConfig({
 });
 ```
 
-
 ### 类型定义
 
 `defineServerConfig` 类型定义如下:
@@ -61,17 +86,17 @@ export default defineServerConfig({
 import type { MiddlewareHandler } from 'hono';
 
 type MiddlewareObj = {
-    name: string;
-    path?: string;
-    method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
-    handler: MiddlewareHandler | MiddlewareHandler[];
+  name: string;
+  path?: string;
+  method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+  handler: MiddlewareHandler | MiddlewareHandler[];
 };
 type ServerConfig = {
-    middlewares?: MiddlewareObj[];
-    renderMiddlewares?: MiddlewareObj[];
-    plugins?: (ServerPlugin | ServerPluginLegacy)[];
-    onError?: (err: Error, c: Context) => Promise<any> | any;
-}
+  middlewares?: MiddlewareObj[];
+  renderMiddlewares?: MiddlewareObj[];
+  plugins?: ServerPlugin[];
+  onError?: (err: Error, c: Context) => Promise<any> | any;
+};
 ```
 
 ### Middleware
@@ -86,7 +111,10 @@ Middleware 支持在 Modern.js 服务的**请求处理**与**页面路由**的
 使用姿势如下：
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 export const handler: MiddlewareHandler = async (c, next) => {
   const monitors = c.get('monitors');
@@ -113,13 +141,15 @@ export default defineServerConfig({
 必须执行 `next` 函数才会执行后续的 Middleware。
 :::
 
-
 ### RenderMiddleware
 
 如果只需要处理页面渲染的前后执行逻辑，modern.js 也提供了渲染中间件，使用姿势如下：
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 // 注入 render 性能指标
 const renderTiming: MiddlewareHandler = async (c, next) => {
@@ -159,52 +189,46 @@ export default defineServerConfig({
 });
 ```
 
-
 ### Plugin
 
 Modern.js 支持在自定义插件中为 Server 添加上述 Middleware 及 RenderMiddleware，使用姿势如下：
 
-
 ```ts title="server/plugins/server.ts"
-import type { ServerPluginLegacy } from '@modern-js/server-runtime';
+import type { ServerPlugin } from '@modern-js/server-runtime';
 
-export default (): ServerPluginLegacy => ({
+export default (): ServerPlugin => ({
   name: 'serverPlugin',
   setup(api) {
-    return {
-      prepare(serverConfig) {
-        const { middlewares, renderMiddlewares } = api.useAppContext();
-
-        // 注入服务端数据，供页面 dataLoader 消费
-        middlewares?.push({
-          name: 'server-plugin-middleware',
-          handler: async (c, next) => {
-            c.set('message', 'hi modern.js');
-            await next();
-            // ...
-          },
-        });
-
-        // 重定向
-        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;
-      },
-    };
+    api.onPrepare(() => {
+      const { middlewares, renderMiddlewares } = api.getServerContext();
+
+      // 注入服务端数据，供页面 dataLoader 消费
+      middlewares?.push({
+        name: 'server-plugin-middleware',
+        handler: async (c, next) => {
+          c.set('message', 'hi modern.js');
+          await next();
+          // ...
+        },
+      });
+
+      // 重定向
+      renderMiddlewares?.push({
+        name: 'server-plugin-render-middleware',
+        handler: async (c, next) => {
+          const user = getUser(c.req);
+          if (!user) {
+            return c.redirect('/login');
+          }
+
+          await next();
+        },
+      });
+    });
   },
 });
 ```
 
-
 ```ts title="server/modern.server.ts"
 import { defineServerConfig } from '@modern-js/server-runtime';
 import serverPlugin from './plugins/serverPlugin';
@@ -214,7 +238,6 @@ export default defineServerConfig({
 });
 ```
 
-
 ```ts title="src/routes/page.data.ts"
 import { useHonoContext } from '@modern-js/server-runtime';
 import { defer } from '@modern-js/runtime/router';
@@ -226,10 +249,8 @@ export default () => {
 
   // ...
 };
-
 ```
 
-
 ### onError
 
 `onError` 是一个全局错误处理函数，用于捕获和处理 Modern.js server 中的所有未捕获错误。通过自定义 `onError` 函数，开发者可以统一处理不同类型的错误，返回自定义的错误响应，实现错误日志记录、错误分类处理等功能。
@@ -258,245 +279,3 @@ export default defineServerConfig({
   },
 });
 ```
-
-
-## 旧版 API（废弃）
-
-:::warning
-旧版 API 兼容但不再推荐使用，扩展 Server 能力请移步 [自定义 Web Server](/guides/advanced-features/web-server.html)，迁移指南参考 [迁移至新版自定义 Web Server](/guides/advanced-features/web-server.html#迁移至新版自定义-web-server)。
-:::
-
-### 开启
-开启自定义 Web Server 功能，需要执行以下步骤：
-1. devDependencies 增加 `@modern-js/plugin-server`、`tsconfig-paths` 及 `ts-node`依赖并安装。
-2. `tsconfig` 的 `include` 中添加 `server`。
-3. `modern.config.ts` 中注册 `@modern-js/plugin-server` 插件。
-4. 项目目录下创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。
-
-
-### Unstable Middleware
-
-Modern.js 支持为 Web Server 添加渲染中间件，支持在处理页面路由的前后执行自定义逻辑。
-
-```ts title="server/index.ts"
-import {
-  UnstableMiddleware,
-  UnstableMiddlewareContext,
-} from '@modern-js/runtime/server';
-
-const time: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
-  const start = Date.now();
-
-  await next();
-
-  const end = Date.now();
-
-  console.log(`dur=${end - start}`);
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [time];
-```
-
-:::info
-详细 API 和更多用法查看 [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware)。
-:::
-
-### Hook
-
-Modern.js 提供的 Hook 用于控制 Web Server 中的特定逻辑，所有的页面请求都会经过 Hook。
-
-目前提供了两种 Hook，分别是 `AfterMatch` 和 `AfterRender`，开发者可以在 `server/index.ts` 中这样写：
-
-```ts
-import type {
-  AfterMatchHook,
-  AfterRenderHook,
-} from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (ctx, next) => {
-  next();
-};
-
-export const afterRender: AfterRenderHook = (ctx, next) => {
-  next();
-};
-```
-
-项目在使用 Hook 时，应该有以下最佳实践：
-
-1. 在 afterMatch 中做权限校验。
-2. 在 afterMatch 做 Rewrite 和 Redirect。
-3. 在 afterRender 中做 HTML 内容注入。
-
-:::info
-详细 API 和更多用法可以查看 [Hook](/apis/app/runtime/web-server/hook)。
-:::
-
-
-## 迁移至新版自定义 Web Server
-
-### 迁移背景
-
-Modern.js Server 在不断演进，为了提供更强大的功能，我们对中间件和 Server 插件的定义和使用方式进行了优化。
-虽然旧版 API 仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版的优势。
-
-### 迁移步骤
-
-1. 升级 Modern.js 版本至 x.67.5 及以上。
-2. 按照新版定义方式，在 `server/modern.server.ts` 中配置中间件或插件。
-3. 将 `server/index.ts` 自定义逻辑迁移到中间件或插件中，并参考 `Context` 和 `Next` 差异，更新您的代码。
-
-### Context 差异
-
-新版中间件 handler 类型为 Hono 的 `MiddlewareHandler`，即 `Context` 类型为 `Hono Context`。对比旧版自定义 Web Server 中 `Context` 差异如下：
-
-#### UnstableMiddleware
-
-
-```ts
-type Body = ReadableStream | ArrayBuffer | string | null;
-
-type UnstableMiddlewareContext<
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = {
-  request: Request;
-  response: Response;
-  get: Get<V>;
-  set: Set<V>;
-  // 当前匹配到的路由信息
-  route: string;
-  header: (name: string, value: string, options?: { append?: boolean }) => void;
-  status: (code: number) => void;
-  redirect: (location: string, status?: number) => Response;
-  body: (data: Body, init?: ResponseInit) => Response;
-  html: (
-    data: string | Promise<string>,
-    init?: ResponseInit,
-  ) => Response | Promise<Response>;
-};
-```
-
-UnstableMiddleware `Context` 和 Hono `Context` 的具体差异：
-
-| UnstableMiddleware       | Hono                          | 说明                                                                      |
-| :----------------------- | :---------------------------- | :------------------------------------------------------------------------ |
-| `c.request`              | `c.req.raw`                   | 参考 [HonoRequest raw](https://hono.dev/docs/api/request#raw) 文档         |
-| `c.response`             | `c.res`                       | 参考 [Hono Context res](https://hono.dev/docs/api/context#res) 文档       |
-| `c.route`                | `c.get('route')`              | 获取应用上下文信息                                                          |
-| `loaderContext.get`      | `honoContext.get`             | 通过 `c.set` 注入数据后 dataLoader 中消费：旧版通过 `loaderContext.get` 获取，新版参考 [Plugin](/guides/advanced-features/web-server.html#使用姿势-2) 示例    |
-
-#### Middleware
-
-```ts
-type MiddlewareContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-    locals: Record<string, any>;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-  source: {
-    req: IncomingMessage;
-    res: ServerResponse;
-  };
-};
-
-```
-
-Middleware `Context` 和 Hono `Context` 的具体差异：
-
-| UnstableMiddleware       | Hono                          | 说明                                                                         |
-| :----------------------- | :---------------------------- | :--------------------------------------------------------------------------- |
-| `c.request.cookie`         | `c.req.cookie()`              | 参考 [Hono Cookie Helper](https://hono.dev/docs/helpers/cookie) 文档        |
-| `c.request.pathname`       | `c.req.path`                  | 参考 [HonoRequest path](https://hono.dev/docs/api/request#path) 文档        |
-| `c.request.url`            | -                             | Hono `c.req.url` 为完整请求路径，自行通过 url 计算                             |
-| `c.request.host`           | `c.req.header('Host')`        | 通过 header 获取 host                                                       |
-| `c.request.query`          | `c.req.query()`               | 参考 [HonoRequest query](https://hono.dev/docs/api/request#query) 文档      |
-| `c.request.headers`        | `c.req.header()`              | 参考 [HonoRequest header](https://hono.dev/docs/api/request#header) 文档     |
-| `c.response.set`           | `c.res.headers.set`           | 例：`c.res.headers.set('custom-header', '1')`                               |
-| `c.response.status`        | `c.status`                    | 例：`c.status(201)`                                                         |
-| `c.response.cookies`       | `c.header`                    | 例：`c.header('Set-Cookie', 'user_id=123')`                                 |
-| `c.response.raw`           | `c.res`                       | 参考 [Hono Context res](https://hono.dev/docs/api/context#res) 文档          |
-
-
-#### Hook
-
-```ts
-type HookContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-};
-
-type AfterMatchContext = HookContext & {
-  router: {
-    redirect: (url: string, status: number) => void;
-    rewrite: (entry: string) => void;
-  };
-};
-
-type AfterRenderContext = {
-  template: {
-    get: () => string;
-    set: (html: string) => void;
-    prependHead: (fragment: string) => void;
-    appendHead: (fragment: string) => void;
-    prependBody: (fragment: string) => void;
-    appendBody: (fragment: string) => void;
-  };
-};
-```
-
-Hook Context 大部分和 Middleware Context 一致，因此我们要额外关注不同 Hook 多余的部分。
-
-| UnstableMiddleware       | Hono                          | 说明                           |
-| :----------------------- | :---------------------------- | :----------------------------- |
-| `router.redirect`        | `c.redirect`                  | 参考 [Hono Context redirect](https://hono.dev/docs/api/context#redirect) 文档      |
-| `router.rewrite`         | -                             | 暂时没有提供对应的能力                                                               |
-| template API             | `c.res`                       | 参考 [Hono Context res](https://hono.dev/docs/api/context#res) 文档               |
-
-
-### Next API 差异
-
-在 Middleware 和 Hook 中，即使不执行 `next`，渲染函数也会执行。
-在新的设计中，必须执行 `next` 函数才会执行后续的 Middleware。

package/docs/zh/guides/basic-features/_meta.json

@@ -1,5 +1,10 @@
 [
-  "routes",
+  {
+    "type": "dir",
+    "name": "routes",
+    "label": "路由",
+    "collapsed": true
+  },
   {
     "type": "dir",
     "name": "data",

package/docs/zh/guides/basic-features/css/css-in-js.mdx

@@ -2,12 +2,49 @@
 
 CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。
 
-Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
+Modern.js 支持社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。
+
+Modern.js 插件 `@modern-js/plugin-styled-components` 提供了对 styled-components 的支持，并为 styled-components 添加了服务器端渲染能力。你可以通过安装 `@modern-js/plugin-styled-components` 插件来使用 styled-components。
+
+## 在 Modern.js 中使用 styled-components
+
+首先，你需要安装 `styled-components` 插件依赖和 `styled-components` 库：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-styled-components styled-components -D',
+    yarn: 'yarn add @modern-js/plugin-styled-components styled-components -D',
+    pnpm: 'pnpm install @modern-js/plugin-styled-components styled-components -D',
+  }}
+/>
+
+然后在 `modern.config.ts` 中配置 `styled-components` 插件：
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { styledComponentsPlugin } from '@modern-js/plugin-styled-components';
+
+export default defineConfig({
+  plugins: [
+    styledComponentsPlugin({
+      // ...
+      displayName: true,
+      minify: process.env.NODE_ENV === 'production',
+    }),
+  ],
+});
+```
+
+styledComponentsPlugin 插件的配置项与 [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) 插件的配置项相同，你可以参考 [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) 插件的文档进行配置。
+
+## 使用 styled-components 编写样式
 
 当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const RedDiv = styled.div`
   color: red;
@@ -17,7 +54,7 @@ const RedDiv = styled.div`
 当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   color: ${props => (props.primary ? 'white' : 'red')};
@@ -27,8 +64,6 @@ const Button = styled.button`
 
 关于 styled-components 的更多用法，请参考 [styled-components 官网](https://styled-components.com/)。
 
-Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 插件，你可以通过 [tools.styledComponents](/configure/app/tools/styled-components) 对插件进行配置。
-
 :::tip 提示
 如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
 :::

package/docs/zh/guides/basic-features/css/css-modules.mdx

@@ -81,18 +81,6 @@ export default {
 };
 ```
 
-## 自定义类名
-
-自定义 CSS Modules 生成的类名也是我们比较常用的功能，你可以使用 [output.cssModuleLocalIdentName](/configure/app/output/css-modules.html#cssmodulesexportlocalsconvention) 来进行配置。
-
-```ts
-export default {
-  output: {
-    cssModuleLocalIdentName: '[hash:base64:4]',
-  },
-};
-```
-
 如果你需要自定义 CSS Modules 的其他配置，可以通过 [tools.cssLoader](/configure/app/tools/css-loader) 进行设置。
 
 ## 添加类型声明
@@ -185,14 +173,15 @@ export default {
 import styles from './index.module.scss';
 
 export default () => {
-  <div>
-    <div className={styles.pageHeader}>Page Header</div>
-  </div>;
+  return (
+    <div>
+      <div className={styles.pageHeader}>Page Header</div>
+    </div>
+  );
 };
 ```
 
-```scss
-// index.module.scss
+```scss title="src/index.module.scss"
 .page-header {
   color: black;
 }

package/docs/zh/guides/basic-features/css/css.mdx

@@ -18,13 +18,13 @@ Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
 
 Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
 
-请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.rs/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
+请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.rs/zh/guide/styling/css-usage) 了解更多用法。
 
 ## 使用 Lightning CSS
 
 Modern.js 支持使用 [Lightning CSS](https://lightningcss.dev/) 来转换 CSS 代码，可以通过配置 [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader) 来开启此功能。
 
-请阅读 [Rsbuild - 使用 Lightning CSS](https://rsbuild.rs/zh/guide/basic/css-usage#lightning-css) 了解更多用法。
+请阅读 [Rsbuild - 使用 Lightning CSS](https://rsbuild.rs/zh/guide/styling/css-usage#lightning-css) 了解更多用法。
 
 ## 使用 Uno CSS