@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/zh/configure/app/tools/css-extract.mdx

@@ -27,7 +27,7 @@ const defaultOptions = {
 };
 ```
 
-通过 `tools.cssExtract` 可以更改 [CssExtractRspackPlugin](https://rspack.rs/zh/plugins/rspack/css-extract-rspack-plugin) 或 [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) 的配置。
+通过 `tools.cssExtract` 可以更改 [CssExtractRspackPlugin](https://rspack.rs/zh/plugins/rspack/css-extract-rspack-plugin) 的配置。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/tools/dev-server.mdx

@@ -15,118 +15,12 @@ Modern.js 中并没有直接使用 [webpack-dev-server](https://webpack.js.org/a
 
 ### 选项
 
-#### after
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
-:::
-
-- **类型：** `Array`
-- **默认值：** `[]`
-
-添加自定义中间件，在所有开发环境中间件后执行。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      after: [
-        async (req, res, next) => {
-          console.log('after dev middleware');
-          next();
-        },
-      ],
-    },
-  },
-};
-```
-
-`webpack-dev-server` 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 `req` 和 `res` 都是 Node 原生对象，因此 `webpack-dev-server` 的 Express 中间件不一定能直接在 Modern.js 中使用。
-
-如果要迁移 `webpack-dev-server` 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
-
-```js
-import expressMiddleware from 'my-express-middleware';
-import express from 'express';
-
-// 初始化 Express app
-const app = express();
-app.use(expressMiddleware);
-
-export default {
-  tools: {
-    devServer: {
-      after: [app],
-    },
-  },
-};
-```
-
-#### before
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
-:::
-
-- **类型：** `Array`
-- **默认值：** `[]`
-
-添加自定义中间件，在所有开发环境中间件前执行。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      before: [
-        async (req, res, next) => {
-          console.log('before dev middleware');
-          next();
-        },
-      ],
-    },
-  },
-};
-```
-
-#### client
+#### compress
 
 :::warning
-**Deprecated**：该配置已废弃，请使用 [dev.client](https://modernjs.dev/configure/app/dev/client) 代替。
+**Deprecated**：该配置已废弃，请使用 [dev.server.compress](https://modernjs.dev/configure/app/dev/server) 代替。
 :::
 
-- **类型：**
-
-```ts
-{
-    /** 指定协议名称 */
-    protocol?: string;
-    /** 事件流路径 */
-    path?: string;
-    /** 指定监听请求的端口号 */
-    port?: string;
-    /** 指定要使用的 host */
-    host?: string;
-}
-```
-
-- **默认值：**
-
-```js
-const defaultConfig = {
-  path: '/webpack-hmr',
-  // By default it is set to the port number of the dev server
-  port: '',
-  // By default it is set to "location.hostname"
-  host: '',
-  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
-  protocol: '',
-};
-```
-
-对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
-
-#### compress
-
 - **类型：** `boolean`
 - **默认值：** `true`
 
@@ -144,32 +38,12 @@ export default {
 };
 ```
 
-#### devMiddleware
+#### headers
 
 :::warning
-**Deprecated**：该配置已废弃，请使用 [dev.writeToDisk](https://modernjs.dev/configure/app/dev/write-to-disk) 代替。
+**Deprecated**：该配置已废弃，请使用 [dev.server.headers](https://modernjs.dev/configure/app/dev/server) 代替。
 :::
 
-- **类型：**
-
-```js
-{
-  writeToDisk: boolean | ((filename: string) => boolean);
-}
-```
-
-- **默认值：**
-
-```js
-{
-  writeToDisk: (file: string) => !file.includes('.hot-update.'),
-}
-```
-
-devMiddleware 配置项。当前配置是 [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) 配置项的子集.
-
-#### headers
-
 - **类型：** `Record<string, string>`
 - **默认值：** `undefined`
 
@@ -189,6 +63,10 @@ export default {
 
 #### historyApiFallback
 
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.historyApiFallback](https://modernjs.dev/configure/app/dev/server) 代替。
+:::
+
 - **类型：** `boolean | ConnectHistoryApiFallbackOptions`
 - **默认值：** `false`
 
@@ -206,128 +84,12 @@ export default {
 
 更多选项和详细信息可参考 [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) 文档。
 
-#### hot
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.hmr](https://modernjs.dev/configure/app/dev/hmr) 代替。
-:::
-
-- **类型：** `boolean`
-- **默认值：** `true`
-
-是否开启 [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) 热更新能力。
-
-#### https
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.https](https://modernjs.dev/configure/app/dev/https) 代替。
-:::
-
-- **类型：** `boolean | { key: string; cert: string }`
-- **默认值：** `false`
-
-默认情况下，DevServer 会启用 HTTP 服务器。通过设置 `devServer.https` 为 `true` 将开启对 HTTPS 的支持，同时会禁用 HTTP 服务器。
-
-你也可以手动传入 HTTPS 服务器所需要的证书和对应的私钥：
-
-```js
-export default {
-  tools: {
-    devServer: {
-      https: {
-        key: fs.readFileSync('certificates/private.pem'),
-        cert: fs.readFileSync('certificates/public.pem'),
-      },
-    },
-  },
-};
-```
-
-#### liveReload
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.liveReload](https://modernjs.dev/configure/app/dev/live-reload) 代替。
-:::
-
-- **类型：** `boolean`
-- **默认值：** `true`
-
-默认情况下，当监听到文件变化时，DevServer 将会刷新页面（为使 liveReload 能够生效，`devServer.hot` 配置项应当禁用）。通过设置 `devServer.liveReload` 为 `false` 可以关闭该行为。
-
-#### setupMiddlewares
+#### proxy
 
 :::warning
-**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
+**Deprecated**：该配置已废弃，请使用 [dev.server.proxy](https://modernjs.dev/configure/app/dev/server) 代替。
 :::
 
-- **类型：**
-
-```js
-Array<
-  (
-    middlewares: {
-      unshift: (...handlers: RequestHandler[]) => void;
-      push: (...handlers: RequestHandler[]) => void;
-    },
-    server: {
-      sockWrite: (
-        type: string,
-        data?: string | boolean | Record<string, any>,
-      ) => void;
-    },
-  ) => void
->;
-```
-
-- **默认值：** `undefined`
-
-提供执行自定义函数和应用自定义中间件的能力。
-
-几种不同中间件之间的执行顺序是: `devServer.before` => `unshift` => 内置中间件 => `push` => `devServer.after`。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      setupMiddlewares: [
-        (middlewares, server) => {
-          middlewares.unshift((req, res, next) => {
-            next();
-          });
-
-          middlewares.push((req, res, next) => {
-            next();
-          });
-        },
-      ],
-    },
-  },
-};
-```
-
-一些特殊场景需求可能需要使用服务器 API：
-
-- sockWrite。允许向 hmr 客户端传递一些消息，hmr 客户端将根据接收到的消息类型进行不同的处理。如果你发送一个 "content-changed " 的消息，页面将会重新加载。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      setupMiddlewares: [
-        (middlewares, server) => {
-          // 添加自定义 watcher 并在文件更新时触发页面刷新
-          watcher.on('change', changed => {
-            server.sockWrite('content-changed');
-          });
-        },
-      ],
-    },
-  },
-};
-```
-
-#### proxy
-
 - **类型：** `Record<string, string> | Record<string, ProxyDetail>`
 - **默认值：** `undefined`
 
@@ -436,6 +198,10 @@ export default {
 
 #### watch
 
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.watch](https://modernjs.dev/configure/app/dev/server) 代替。
+:::
+
 - **类型：** `boolean`
 - **默认值：** `true`
 

package/docs/zh/configure/app/tools/html-plugin.mdx

@@ -17,7 +17,8 @@ const defaultOptions = {
   filename, // 基于 `output.distPath` 和 `entryName` 生成
   templateParameters, // 对应 `html.templateParameters` 配置
   chunks: [entryName],
-  minify: { // 基于 `output.minify` 和 `output.disableMinimize` 生成
+  minify: {
+    // 基于 `output.minify` 生成
     removeComments: false,
     useShortDoctype: true,
     keepClosingSlash: true,
@@ -37,7 +38,7 @@ const defaultOptions = {
 SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
 :::
 
-通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 或 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的配置项。
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的配置项。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/tools/lightningcss-loader.mdx

@@ -6,7 +6,6 @@ title: lightningcssLoader
 
 - **类型：** `Rspack.LightningcssLoaderOptions | Function | boolean`
 - **默认值：** `false`
-- **打包工具：** `仅支持 rspack`
 
 通过 `tools.lightningcssLoader` 可以设置 [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) 的选项。
 

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

@@ -24,7 +24,7 @@ import SWC from '@site-docs/components/swc.mdx';
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
-export default defineConfig<'rspack'>({
+export default defineConfig({
   tools: {
     swc: {
       jsc: {
@@ -67,45 +67,3 @@ export default {
 如果你遇到了以上问题，通常可行的解决方法是将 Modern.js 和 SWC 插件都升级到最新版本。
 
 详情可参考 [Rsbuild - SWC 插件版本](https://rsbuild.rs/zh/guide/basic/configure-swc#swc-%E6%8F%92%E4%BB%B6%E7%89%88%E6%9C%AC)。
-
-## 在 Webpack 模式下使用
-
-import EnableSWC from '@site-docs/components/enableSwc.mdx';
-
-<EnableSWC />
-
-### 配置项
-
-你可以通过 `tools.swc` 配置项来设置 SWC 编译行为。
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc: {
-      jsMinify: {
-        compress: {},
-        mangle: true,
-      },
-    },
-  },
-});
-```
-
-当然也可以使用函数进行更灵活的配置，或者修改某些默认配置。
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc(config, { setConfig }) {
-      // 用于 mobx 中 decorator 编译
-      setConfig(config, 'jsc.transform.useDefineForClassFields', true);
-    },
-  },
-});
-```
-
-完整配置项请参考 [SWC 插件配置](/plugin/official/cli-plugins/plugin-swc.html#配置)。

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

@@ -43,15 +43,6 @@ export default defineConfig({
 });
 ```
 
-当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `defineConfig` 指定 `<'rspack'>` 泛型：
-
-```diff title=modern.config.ts
-- export default defineConfig({
-+ export default defineConfig<'rspack'>({
-  // ...
-});
-```
-
 #### modern.config.js
 
 如果你在开发一个非 TypeScript 项目，可以使用 `.js` 格式的配置文件：
@@ -95,9 +86,9 @@ export default defineConfig(({ env, command }) => ({
 该函数接受以下入参：
 
 - `env`：对应 `process.env.NODE_ENV` 的值。
-  - 当运行 `modern dev` 或 `modern start` 时，`env` 的值为 `development`。
+  - 当运行 `modern dev` 时，`env` 的值为 `development`。
   - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
-- `command`：对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
+- `command`：对应当前运行的命令，如 `dev`、`build`、`serve`。
 
 #### 导出异步函数
 
@@ -159,7 +150,6 @@ $ modern build -c modern.prod.config.js
 #### 注意事项
 
 - 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示错误。
-- `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
 
 ### 本地调试配置
 
@@ -197,11 +187,11 @@ export default defineConfig({
 
 在使用 `modern.config.local.ts` 时，请注意以下事项：
 
-- `modern.config.local.ts` 文件仅会在执行 `modern dev` 或 `modern start` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 命令时被加载，当执行 `modern build` 时不会被加载。
 - `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
 - 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
 
-```bash title=".gitingore"
+```bash title=".gitignore"
 modern.config.local.*
 ```
 
@@ -263,12 +253,12 @@ const config: AppUserConfig = {
 };
 ```
 
-当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `AppUserConfig` 指定 `<'rspack'>` 泛型：
+当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `AppUserConfig` 指定 `` 泛型：
 
 ```ts title="modern.config.ts"
 import type { AppUserConfig } from '@modern-js/app-tools';
 
-const config: AppUserConfig<'rspack'> = {
+const config: AppUserConfig = {
   tools: {
     rspack: {},
   },
@@ -284,11 +274,11 @@ const config: AppUserConfig<'rspack'> = {
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
-import { statePlugin } from '@modern-js/plugin-state';
+import { xxPlugin } from '@modern-js/plugin-xx';
 
 export default defineConfig({
   plugins: [
-    statePlugin({
+    xxPlugin({
       /** 在此处添加参数 */
     }),
   ],

package/docs/zh/guides/_meta.json

@@ -29,5 +29,9 @@
     "name": "troubleshooting",
     "label": "troubleshooting"
   },
-  "deprecated"
+  {
+    "type": "dir",
+    "name": "upgrade",
+    "label": "从 Modern.js 2.0 升级"
+  }
 ]

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

@@ -1,5 +1,4 @@
 [
-  "rspack-start",
   {
     "type": "dir",
     "name": "bff",
@@ -23,5 +22,11 @@
     "label": "server-monitor",
     "collapsed": true
   },
+  {
+    "type": "dir",
+    "name": "international",
+    "label": "国际化",
+    "collapsed": true
+  },
   "web-server"
 ]

package/docs/zh/guides/advanced-features/bff/cross-project.mdx

@@ -7,8 +7,9 @@ import { PackageManagerTabs } from '@theme';
 
 ## BFF 生产端
 
-升级 Modern.js 相关依赖到 x.64.4 及以上版本，通过配置即可启用跨项目调用能力。你可以将已启用 BFF 能力的项目视为 BFF 生产端，也可以单独创建独立的 BFF 应用。
+你可以将已启用 BFF 能力的项目视为 BFF 生产端，也可以单独创建独立的 BFF 应用。
 当执行 `dev` 或 `build`，都会自动生成供消费端使用的产物，包括：
+
 - `dist/client` 目录下的接口函数
 - `dist/runtime` 目录下的运行时配置函数
 - `package.json` 中 `exports` 定义接口函数出口
@@ -24,27 +25,20 @@ import { PackageManagerTabs } from '@theme';
 export default defineConfig({
   bff: {
     crossProject: true,
-  }
+  },
 });
 ```
 
-
 2. 生成 SDK 类型文件
 
 为一体化调用 SDK 提供类型提示，需要在 `TypeScript` 的 `tsconfig.json` 文件中打开 `declaration` 选项，配置如下：
 
 ```ts title="tsconfig.json"
 "compilerOptions": {
-    "declaration": true,
+  "declaration": true,
 }
 ```
 
-### 创建 BFF 应用
-
-import CreateApi from "@site-docs/components/create-bff-api-app"
-
-<CreateApi/>
-
 ## BFF 消费端
 
 :::info
@@ -92,13 +86,13 @@ configure({
 
 ```ts title="src/routes/page.tsx"
 import { configure } from '${package_name}/runtime';
-import { configure as innerConfigure } from '@modern-js/runtime/bff';
+import { configure as innerConfigure } from '@modern-js/plugin-bff/client';
 import axios from 'axios';
 
 configure({
-    setDomain() {
-        return 'https://your-bff-api.com';
-    },
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
 });
 
 innerConfigure({
@@ -115,6 +109,4 @@ innerConfigure({
     return res.data;
   },
 });
-
-
 ```

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

@@ -4,21 +4,35 @@
 
 Modern.js 支持用户通过 [Middleware](/guides/advanced-features/web-server.html#middleware) 的方式来自由扩展 BFF Server。
 
-
 ## 使用中间件
 
-开发者可以在 `server/modern.server.ts` 中通过 配置 middlewares 来使用中间件。下面介绍如何手写一个 BFF 中间件，添加权限校验：
+:::tip 版本一致性
+在使用中间件之前，需要先安装 `@modern-js/server-runtime` 依赖。请确保 `@modern-js/server-runtime` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/server-runtime`：
+
+```bash
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<版本号>
+```
+
+:::
 
+开发者可以在 `server/modern.server.ts` 中通过配置 middlewares 来使用中间件。下面介绍如何手写一个 BFF 中间件，添加权限校验：
 
 ```ts title="server/modern.server.ts"
 import {
   type MiddlewareHandler,
   defineServerConfig,
+  getCookie,
 } from '@modern-js/server-runtime';
 
 const requireAuthForApi: MiddlewareHandler = async (c, next) => {
   if (c.req.path.startsWith('/api') && c.req.path !== '/api/login') {
-    const sid = c.req.cookie('sid');
+    const sid = getCookie(c, 'sid');
     if (!sid) {
       return c.json({ code: -1, message: 'need login' }, 400);
     }
@@ -32,17 +46,20 @@ export default defineServerConfig({
       name: 'require-auth-for-api',
       handler: requireAuthForApi,
     },
-  ]
+  ],
 });
-
 ```
 
-
 然后添加一个普通的 BFF 函数 `api/lambda/hello.ts`：
 
 ```ts title="api/lambda/hello.ts"
-export default async () => {
-  return 'Hello Modern.js';
+import { useHonoContext } from '@modern-js/plugin-bff/server';
+
+export const get = async () => {
+  return {
+    code: 0,
+    message: 'Hello Modern.js',
+  };
 };
 ```
 

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

@@ -12,7 +12,7 @@ Modern.js 以 [Hono.js](https://hono.dev/) 作为 BFF 和 Server 运行时框架
 在 BFF 函数中，有时需要获取请求上下文，来处理更多逻辑。此时，你可以通过 `useHonoContext` 来获取：
 
 ```ts title="api/lambda/hello.ts"
-import { useHonoContext } from '@modern-js/plugin-bff/hono'
+import { useHonoContext } from '@modern-js/plugin-bff/server'
 export const get = async () => {
   const c = useHonoContext();
   console.info(`access url: ${c.req.url}`);