docs: add some break change docs

Author: yimingjfe

custom-server.md

@@ -28,6 +28,5 @@
     "type": "dir",
     "name": "troubleshooting",
     "label": "troubleshooting"
-  },
-  "deprecated"
+  }
 ]

packages/document/docs/en/guides/_meta.json

@@ -29,7 +29,6 @@
     "name": "troubleshooting",
     "label": "troubleshooting"
   },
-  "deprecated",
   {
     "type": "dir",
     "name": "upgrade",

packages/document/docs/en/guides/deprecated.md

@@ -1 +1 @@
-["overview", "config", "entry"]
+["overview", "config", "entry", "web-server", "other"]

packages/document/docs/zh/guides/_meta.json

@@ -389,6 +389,12 @@ resolve: {
 
 **变更内容**: 该配置已废弃，直接移除。
 
+
+### source.disableEntryDirs
+
+**变更内容**: 该配置已废弃，直接移除。
+
+
 ## tools
 
 ### tools.esbuild
@@ -502,7 +508,7 @@ dev: {
 
 // 改动后
 server: {
-  port: process.env.NODE_ENV === 'development' && 8080
+  port: process.env.NODE_ENV === 'development' ?  8080 : undefined
 }
 ```
 

packages/document/docs/zh/guides/deprecated.md

@@ -0,0 +1,58 @@
+# 其他重要变更
+
+本篇文档介绍从 Modern.js 2.0 升级到 3.0 时，其他重要的不兼容变更以及相关的迁移说明。
+
+## 不再支持 webpack 构建
+
+Modern.js 3.0 不再支持使用 webpack 作为构建工具，默认使用 Rspack 作为构建 bundler。Rspack 基于 Rust 实现，构建速度相比 webpack 有显著提升，同时与 webpack 配置高度兼容，大部分配置可以直接迁移。
+
+如果你的项目之前使用了 webpack 特定的配置或插件，需要检查项目中是否有 webpack 相关的自定义配置，并确认使用的 webpack 插件是否有 Rspack 对应版本。
+
+:::tip
+Rspack 与 webpack 配置高度兼容，大部分情况下无需修改即可使用。
+:::
+
+## 入口名称变化
+
+Modern.js 3.0 将项目默认入口名称改为 `index`，默认构建出的 HTML 文件为 `index.html`。`index.html` 是大多数 Web 服务器的默认首页文件，无需额外配置。
+
+如果你的项目部署配置中指定了特定的入口文件名，需要更新为 `index.html`。
+
+## 别名改动
+
+Modern.js 3.0 对部分运行时路径别名进行了调整，需要更新相关的导入路径。路径映射对照如下：
+
+| 旧版路径 | 新版路径 | 说明 |
+|---------|---------|------|
+| `@modern-js/runtime/bff` | `@modern-js/plugin-bff/runtime` | BFF 运行时路径 |
+| `@modern-js/runtime/server` | `@modern-js/server-runtime` | 服务端运行时路径 |
+
+## 不再支持 pages 目录的约定式路由
+
+Modern.js 3.0 不再支持 Modern.js 1.0 版本引入的 `pages` 目录的约定式路由，统一使用 `routes` 目录的约定式路由。
+
+如果你的项目使用了 `pages` 目录，需要将 `src/pages` 目录重命名为 `src/routes`，并更新项目中所有引用 `pages` 目录的导入路径。详细迁移步骤请参考 [约定式路由文档](/guides/basic-features/routes/routes)。
+
+## 使用 React Router v7
+
+Modern.js 3.0 默认使用 React Router v7 作为路由库。React Router v7 相比 v6 只有少量的 [不兼容变更](https://reactrouter.com/upgrading/v6)。
+
+如果需要使用 React Router v5 或 React Router v6，需要使用**自控式路由**模式。自控式路由允许你完全控制路由配置，不受 Modern.js 约定式路由的限制。
+
+## 使用 @modern-js/create 创建 Monorepo
+
+Modern.js 之前提供的 Monorepo 方案是基于 [pnpm Workspace](https://pnpm.io/workspaces) 实现的，并未提供实质性的 Monorepo 管理能力。在 [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0) 版本中，移除了使用 `@modern-js/create` 创建 Monorepo 项目的功能。推荐直接使用社区提供的 Monorepo 方案。
+
+## new 命令开启 test 能力
+
+Modern.js 之前提供的测试能力是基于 Jest 的简单封装。该封装导致 Jest 配置不直观、用户配置更加复杂等问题。在 [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0) 版本中，移除了在应用项目和模块项目中开启 test 功能的选项。推荐直接使用社区提供的测试方案。
+
+## Eslint 规则集
+
+Modern.js 之前提供了 ESLint 的完整规则集，涵盖了 @modern-js（针对 Node.js 项目的 Lint 规则）和 @modern-js-app（针对前端项目的 Lint 规则）。在 [v2.60.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.60.0) 版本中，我们正式移除了这些规则集。我们鼓励开发者根据自身需求选择合适的代码规范工具，直接使用 ESLint 并结合社区推荐的规则，或使用 Biome 以提升代码格式化的性能。
+
+
+
+
+
+

packages/document/docs/zh/guides/upgrade/_meta.json

@@ -0,0 +1,93 @@
+# 自定义 Web Server 变化
+
+本章节覆盖两类旧版自定义 Server API 的升级
+
+- **unstableMiddleware**
+- **Hook**
+
+这两种写法在旧版中互斥，迁移时请根据项目实际使用的能力选择对应路径。
+
+
+## unstableMiddleware
+
+### 核心差异
+
+- **文件结构**：`server/index.ts` → `server/modern.server.ts`
+- **导出方式**：`unstableMiddleware` 数组 → `defineServerConfig`
+- **Context API**：Modern.js Server Context → Hono Context（`c.req`/`c.res`）
+- **中间件执行**：旧版可不调用 `next()`，新版必须调用后续链路才会执行
+- **响应方式**：`c.response.raw()` → `c.text()` / `c.json()`
+
+### 文件与导出
+
+```typescript
+// 旧版 - server/index.ts
+export const unstableMiddleware: UnstableMiddleware[] = [middleware1, middleware2];
+
+// 新版 - server/modern.server.ts
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [
+    { name: 'middleware1', handler: middleware1 },
+    { name: 'middleware2', handler: middleware2 },
+  ],
+});
+```
+
+### 类型与 next 调用
+
+```typescript
+// 旧版
+import type { UnstableMiddleware, UnstableMiddlewareContext } from '@modern-js/server-runtime';
+const middleware: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
+  return c.response.raw('response'); // 不调用 next 也会继续渲染
+};
+
+// 新版
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+const middleware: MiddlewareHandler = async (c, next) => {
+  await next(); // 必须调用
+  return c.text('response');
+};
+```
+
+### Context API 对照
+
+| 旧版 API               | 新版 API                 | 说明            |
+| -------------------- | ---------------------- | ------------- |
+| `c.request.cookie`   | `getCookie(c, 'key')`  | Cookie 读取      |
+| `c.req.cookie()`     | `getCookie(c, 'key')`  | Hono v4 已废弃    |
+| `c.request.pathname` | `c.req.path`           | 请求路径          |
+| `c.request.host`     | `c.req.header('Host')` | 请求主机          |
+| `c.request.query`    | `c.req.query()`        | 查询参数          |
+| `c.request.headers`  | `c.req.header()`       | 请求头           |
+| `c.response.status`  | `c.status()`           | 响应状态码         |
+| `c.response.set`     | `c.res.headers.set`    | 设置响应头         |
+| `c.response.raw`     | `c.text` / `c.json`    | 响应体           |
+
+
+## afterRender Hook
+
+`afterRender` 仅用于页面渲染完成后的 HTML 处理。
+
+```typescript
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+const renderMiddleware: MiddlewareHandler = async (c, next) => {
+  await next(); // 先等待页面渲染
+  const { res } = c;
+  const html = await res.text();
+
+  const modified = html
+    .replace('<head>', '<head><meta name="author" content="ByteDance">')
+    .replace('<body>', '<body><div id="loading">Loading...</div>')
+    .replace('</body>', '<script>console.log("Page loaded")</script></body>');
+
+  c.res = c.body(modified, { status: res.status, headers: res.headers });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [{ name: 'custom-content-injection', handler: renderMiddleware }],
+});
+```