@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/guides/upgrade/entry.mdx

@@ -0,0 +1,463 @@
+# 入口变更
+
+本章节介绍 Modern.js 从 2.0 升级到 3.0 时，页面入口相关的变更内容。
+
+## 概述
+
+Modern.js 3.0 对入口机制进行了优化和简化，主要变更包括：
+
+- **入口文件命名变更**：自定义入口文件从 `index.tsx` 改为 `entry.tsx`
+- **Bootstrap 函数替换**：使用新的 `createRoot` 和 `render` API
+- **运行时配置迁移**：`App.config` 和 `routes/layout` 的 `config` 导出需要迁移
+- **初始化逻辑迁移**：`App.init` 和 `routes/layout` 的 `init` 导出需要改为运行时插件
+
+## 入口类型识别
+
+在开始迁移前，首先需要识别你的项目使用的入口类型。
+
+### 入口识别条件
+
+Modern.js 会扫描目录并识别符合以下**任一条件**的入口：
+
+1. **具有 `routes/` 目录** → 约定式路由入口
+2. **具有 `App.tsx?` 文件** → 自控式路由入口
+3. **具有 `index.tsx?` 文件（2.0）或 `entry.tsx?` 文件（3.0）**→ 自定义入口
+
+### 单入口 vs 多入口
+
+**单入口应用**：默认扫描 `src/` 目录
+
+```bash
+src/
+├── routes/        # 或者
+├── App.tsx        # 或者
+└── index.tsx      # 2.0 版本
+```
+
+**多入口应用**：扫描 `src/` 目录下的一级子目录
+
+```bash
+src/
+├── entry1/
+│   └── routes/    # 每个子目录都是一个入口
+└── entry2/
+    └── App.tsx
+```
+
+:::tip
+你可以通过 [source.entriesDir](/configure/app/source/entries-dir) 配置修改入口扫描目录。
+:::
+
+## 迁移步骤
+
+本小节中的迁移操作都是仅当项目中实际存在对应用法时才需要执行，例如 `bootstrap` 函数、`App.config/App.init`、`routes/layout.tsx` 中的 `config/init` 函数等。
+
+### 1. 自定义入口文件重命名
+
+如果你的项目使用了自定义入口文件（`index.tsx`），需要将其重命名为 `entry.tsx`。
+
+**2.0 版本：**
+
+```bash
+src/
+└── index.tsx
+```
+
+**3.0 版本：**
+
+```bash
+src/
+└── entry.tsx
+```
+
+### 2. Bootstrap 函数迁移
+
+如果你的入口文件导出了一个接收 `App` 和 `bootstrap` 参数的函数，需要改用新的 API。
+
+**2.0 版本：**
+
+```tsx title="src/index.tsx"
+export default (App: React.ComponentType, bootstrap: () => void) => {
+  // 执行初始化操作
+  initSomething().then(() => {
+    bootstrap();
+  });
+};
+```
+
+**3.0 版本：**
+
+```tsx title="src/entry.tsx"
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+// 创建根组件
+const ModernRoot = createRoot();
+
+// 执行初始化操作
+async function beforeRender() {
+  await initSomething();
+}
+
+// 渲染应用
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+:::info 说明
+
+- `createRoot()` 返回的组件对应 `routes/` 目录生成或 `App.tsx` 导出的组件
+- `render()` 函数用于处理渲染与挂载组件
+
+:::
+
+### 3. App.config 迁移
+
+如果你在 `App.tsx` 中定义了 `App.config`，需要将其迁移到运行时配置文件中。
+
+**2.0 版本：**
+
+```tsx title="src/App.tsx"
+const App = () => {
+  return <div>Hello</div>;
+};
+
+App.config = {
+  router: {
+    supportHtml5History: true,
+  },
+};
+
+export default App;
+```
+
+**3.0 版本：**
+
+在入口同级目录创建 `modern.runtime.ts`：
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  router: {
+    supportHtml5History: true,
+  },
+});
+```
+
+:::warning 注意
+Modern.js 3.0 不再支持在 `modern.config.ts` 中配置 runtime，必须使用 `modern.runtime.ts` 文件。
+:::
+
+### 4. App.init 迁移
+
+如果你在 `App.tsx` 中定义了 `App.init`，需要将其改为运行时插件。
+
+**2.0 版本：**
+
+```tsx title="src/App.tsx"
+const App = () => {
+  return <div>Hello</div>;
+};
+
+App.init = context => {
+  context.store = createStore();
+  context.request = (url: string) => fetch(url);
+};
+
+export default App;
+```
+
+**3.0 版本：**
+
+```ts title="src/modern.runtime.ts"
+import type { RuntimePlugin } from '@modern-js/runtime';
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+const initPlugin = (): RuntimePlugin => ({
+  name: 'init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.store = createStore();
+        context.request = (url: string) => fetch(url);
+      },
+    };
+  },
+});
+
+export default defineRuntimeConfig({
+  plugins: [initPlugin()],
+});
+```
+
+### 5. routes/layout.tsx 中的 config 导出迁移
+
+如果你在 `routes/layout.tsx` 中导出了 `config` 函数，需要将其迁移到运行时配置文件。
+
+**2.0 版本：**
+
+```tsx title="src/routes/layout.tsx"
+export const config = () => {
+  return {
+    router: {
+      supportHtml5History: true,
+    },
+  };
+};
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**3.0 版本：**
+
+```tsx title="src/routes/layout.tsx"
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  router: {
+    supportHtml5History: true,
+  },
+});
+```
+
+### 6. routes/layout.tsx 中的 init 导出迁移
+
+如果你在 `routes/layout.tsx` 中导出了 `init` 函数，需要将其改为运行时插件。
+
+**2.0 版本：**
+
+```tsx title="src/routes/layout.tsx"
+export const init = context => {
+  context.request = (url: string) => fetch(url);
+};
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**3.0 版本：**
+
+```tsx title="src/routes/layout.tsx"
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+```ts title="src/modern.runtime.ts"
+import type { RuntimePlugin } from '@modern-js/runtime';
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+const initPlugin = (): RuntimePlugin => ({
+  name: 'init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.request = (url: string) => fetch(url);
+      },
+    };
+  },
+});
+
+export default defineRuntimeConfig({
+  plugins: [initPlugin()],
+});
+```
+
+## 多入口应用迁移注意事项
+
+对于多入口应用，需要在 `src/modern.runtime.ts` 中使用函数形式的配置，根据入口名称返回不同的运行时配置。
+
+### 配置方式
+
+**目录结构：**
+
+```bash
+src/
+├── modern.runtime.ts  # 统一的运行时配置文件
+├── entry1/
+│   └── routes/
+└── entry2/
+    └── App.tsx
+```
+
+**配置示例：**
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig(entryName => {
+  // 公共配置
+  const commonConfig = {
+    plugins: [commonPlugin()],
+  };
+
+  // 根据入口名称返回特定配置
+  if (entryName === 'entry1') {
+    return {
+      ...commonConfig,
+      router: {
+        supportHtml5History: true,
+      },
+      plugins: [...commonConfig.plugins, entry1Plugin()],
+    };
+  }
+
+  if (entryName === 'entry2') {
+    return {
+      ...commonConfig,
+      router: {
+        supportHtml5History: false,
+      },
+      plugins: [...commonConfig.plugins, entry2Plugin()],
+    };
+  }
+
+  // 默认配置
+  return commonConfig;
+});
+```
+
+:::info 说明
+
+- `entryName` 参数对应入口目录名称
+- 主入口（与 `package.json` 中 `name` 同名）：传入的是该目录名
+- 其他入口：传入的是入口目录名
+
+:::
+
+### 迁移注意事项
+
+1. **合并同一入口的配置**：如果同一入口下同时存在 `App.config/App.init` 和 `routes/layout.tsx` 的 `config/init`，需要将它们合并到 `src/modern.runtime.ts` 文件中对应入口的配置里
+
+2. **多个插件并列配置**：多个运行时插件可以在 `plugins` 数组中并列配置
+
+3. **清理旧代码**：迁移完成后，记得删除原文件中的：
+   - `App.config` 属性
+   - `App.init` 方法
+   - `routes/layout.tsx` 中的 `config` 导出
+   - `routes/layout.tsx` 中的 `init` 导出
+
+### 迁移示例
+
+假设你有一个 2.0 版本的多入口应用：
+
+**2.0 版本目录结构：**
+
+```bash
+src/
+├── main/
+│   ├── routes/
+│   │   └── layout.tsx  # 含 config 和 init
+│   └── App.tsx         # 含 App.config 和 App.init
+└── admin/
+    └── routes/
+        └── layout.tsx  # 含 config 和 init
+```
+
+**2.0 版本配置：**
+
+```tsx title="src/main/App.tsx"
+const App = () => <div>Main App</div>;
+
+App.config = {
+  router: { supportHtml5History: true },
+};
+
+App.init = context => {
+  context.mainData = 'main';
+};
+```
+
+```tsx title="src/admin/routes/layout.tsx"
+export const config = () => ({
+  router: { supportHtml5History: false },
+});
+
+export const init = context => {
+  context.adminData = 'admin';
+};
+```
+
+**3.0 版本迁移后：**
+
+```bash
+src/
+├── modern.runtime.ts  # 新增统一配置文件
+├── main/
+│   ├── routes/
+│   │   └── layout.tsx  # 移除 config 和 init
+│   └── App.tsx         # 移除 App.config 和 App.init
+└── admin/
+    └── routes/
+        └── layout.tsx  # 移除 config 和 init
+```
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+// main 入口的初始化插件
+const mainInitPlugin = (): RuntimePlugin => ({
+  name: 'main-init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.mainData = 'main';
+      },
+    };
+  },
+});
+
+// admin 入口的初始化插件
+const adminInitPlugin = (): RuntimePlugin => ({
+  name: 'admin-init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.adminData = 'admin';
+      },
+    };
+  },
+});
+
+export default defineRuntimeConfig(entryName => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        supportHtml5History: true,
+      },
+      plugins: [mainInitPlugin()],
+    };
+  }
+
+  if (entryName === 'admin') {
+    return {
+      router: {
+        supportHtml5History: false,
+      },
+      plugins: [adminInitPlugin()],
+    };
+  }
+
+  return {};
+});
+```
+
+## 相关链接
+
+- [页面入口](/guides/concept/entries)
+- [运行时配置](/configure/app/runtime/0-intro)
+- [Runtime 插件](/plugin/introduction.html#runtime-插件)
+- [source.entries 配置](/configure/app/source/entries)
+- [source.entriesDir 配置](/configure/app/source/entries-dir)

package/docs/zh/guides/upgrade/other.md

@@ -0,0 +1,190 @@
+# 其他重要变更
+
+本篇文档介绍从 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`。
+
+## API 引入路径
+
+Modern.js 3.0 对部分运行时进行了调整，需要更新相关的导入路径。路径映射对照如下：
+
+| 旧版路径 | 新版路径 | 说明 |
+|---------|---------|------|
+| `@modern-js/runtime/bff` | `@modern-js/plugin-bff/runtime` | BFF 运行时路径 |
+| `@modern-js/runtime/server` | `@modern-js/server-runtime` | 服务端运行时路径 |
+
+## useRuntimeContext 已废弃
+
+Modern.js 3.0 中，`useRuntimeContext` Hook 已被废弃，推荐使用 `use(RuntimeContext)` 或 `useContext(RuntimeContext)` 替代。
+
+**迁移示例**：
+
+```tsx
+// Modern.js 2.0
+import { useRuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const { context } = useRuntimeContext();
+
+  // isBrowser 在 context 内部
+  if (context.isBrowser === true) {
+    console.log('browser render');
+  }
+}
+```
+
+```tsx
+// Modern.js 3.0
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const { context, isBrowser } = use(RuntimeContext);
+  if (isBrowser === true) {
+    console.log('browser render');
+  }
+}
+```
+
+**主要变化**：
+
+- API 从 `useRuntimeContext()` 改为 `use(RuntimeContext)` 或 `useContext(RuntimeContext)`
+- `isBrowser` 从 `context.isBrowser` 移到返回值顶层
+- `context` 结构简化：只包含 `request` 和 `response`，不再包含 `logger`、`metrics` 等
+- 返回值新增 `initialData`、`routes` 等属性
+
+详细 API 文档请参考 [RuntimeContext 文档](/apis/app/runtime/core/runtime-context)。
+
+## 不再支持 pages 目录的约定式路由
+
+Modern.js 3.0 不再支持 Modern.js 1.0 版本引入的 `pages` 目录的约定式路由，统一使用 `routes` 目录的约定式路由。
+
+如果你的项目使用了 `pages` 目录，需要将 `src/pages` 目录重命名为 `src/routes`，并更新项目中所有引用 `pages` 目录的导入路径。详细迁移步骤请参考 [约定式路由文档](/guides/basic-features/routes/routes)。
+
+## SSR Mode 默认值变化
+
+Modern.js 3.0 将 `server.ssr.mode` 的默认值从 `'string'` 改为 `'stream'`。这意味着当启用 SSR 时，默认使用流式渲染（streaming rendering）而不是传统的字符串渲染。
+
+对于 React 18 及以上项目，把 `ssr.mode` 的值由 `'stream'` 改为 `'string'`，不对 Data Loader 中的代码进行修改或使用 Suspense 的话，从渲染结果上没有任何影响。如果你的项目依赖了 React17，请把 `ssr.mode` 的值手动设置为 `'string'`。
+
+
+## 使用 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 Module
+
+Modern.js 3.0 不再支持通过 `@modern-js/create` 创建 Monorepo 项目和 Modern.js Module 项目。
+
+**变更内容**：
+
+- 在 [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0) 版本中，移除了使用 `@modern-js/create` 创建 Monorepo 项目的功能
+- 在 [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0) 版本中，移除了使用 `@modern-js/create` 和 `modern new` 命令创建 Modern.js Module 项目的功能
+
+**处理方式**：
+
+- **Monorepo 项目**：Modern.js 之前提供的 Monorepo 方案是基于 [pnpm Workspace](https://pnpm.io/workspaces) 实现的，并未提供实质性的 Monorepo 管理能力。推荐直接使用社区提供的 Monorepo 方案，如 [Turborepo](https://turbo.build/)、[Nx](https://nx.dev/) 等。
+- **Modern.js Module 项目**：推荐使用 [Rslib](https://rslib.rs/) 来创建和管理 JavaScript 库和 UI 组件项目。Rslib 是基于 Rsbuild 的库开发工具，提供了简单直观的方式来创建 JavaScript 库。详细使用方式请参考 [Rslib 官方文档](https://rslib.rs/)。
+
+## new 命令和 upgrade 命令移除
+
+Modern.js 3.0 移除了 `modern new` 和 `modern upgrade` 命令，需要按照文档手动操作。
+
+**变更内容**：
+
+- `modern new` 命令在 Modern.js 3.0 中不再支持，无法通过命令添加入口或启用功能
+- `modern upgrade` 命令在 Modern.js 3.0 中不再支持，无法通过命令自动升级依赖
+
+**处理方式**：
+
+- **添加入口**：需要按照文档手动创建入口目录和文件。详细步骤请参考[页面入口文档](/guides/concept/entries)。
+- **启用功能**：需要按照对应功能的文档手动安装依赖和配置。例如启用 BFF 功能，需要安装 `@modern-js/plugin-bff` 插件并在 `modern.config.ts` 中配置。
+- **升级依赖**：需要手动更新 `package.json` 中所有 `@modern-js/**` 包的版本，然后重新安装依赖。详细步骤请参考[版本升级文档](/guides/get-started/upgrade)。
+
+:::info 说明
+移除这些命令的目的是让文档更贴合 AI Agent 的默认实现方式，不把操作做封装，使开发者能够更清晰地了解每个操作的具体步骤，也便于 AI Agent 根据文档直接执行相应的操作。
+:::
+
+## 不再内置 Arco/Antd 支持
+
+Modern.js 2.0 内置了对 [Arco Design](https://arco.design/) 和 [Ant Design](https://ant.design/) 的按需引入支持，3.0 版本不再内置该能力，需要用户自行配置 `source.transformImport`。
+
+如果项目中使用了 Arco Design 或 Ant Design，请手动添加对应的 `source.transformImport` 配置。
+
+**Arco Design 迁移示例**：
+
+```typescript
+export default {
+  source: {
+    transformImport: [
+      {
+        libraryName: '@arco-design/web-react',
+        libraryDirectory: 'es',
+        camelToDashComponentName: false,
+        style: 'css',
+      },
+      {
+        libraryName: '@arco-design/web-react/icon',
+        libraryDirectory: 'react-icon',
+        camelToDashComponentName: false,
+      },
+    ],
+  },
+};
+```
+
+**Ant Design 迁移示例**（antd v4 及以下版本）：
+
+```typescript
+export default {
+  source: {
+    transformImport: [
+      {
+        libraryName: 'antd',
+        libraryDirectory: 'es',
+        style: 'css',
+      },
+    ],
+  },
+};
+```
+
+:::tip
+antd v5 使用了 CSS-in-JS 方案，已原生支持按需加载，无需配置 `source.transformImport`。
+
+更多用法请参考 [Rsbuild - source.transformImport](https://v2.rsbuild.rs/config/source/transform-import)。
+:::
+
+## 移除 `node_modules` 解析重定向行为
+
+在 Modern.js v1 版本中，框架内部存在一个 hack，会将 `node_modules` 的模块解析路径强制指向项目根目录。在 Modern.js 3.0 中，我们移除了这一行为。
+
+这一做法并非标准实践，可能导致不可预期的依赖解析问题——例如，未在 `package.json` 中显式声明的依赖包可能仍能被解析，从而掩盖了缺失的依赖声明。
+
+如果你的项目依赖了这一行为，请确保所有需要的依赖都已在 `package.json` 中显式声明并安装到本地。
+
+## 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 以提升代码格式化的性能。
+
+
+
+
+
+

package/docs/zh/guides/upgrade/overview.mdx

@@ -0,0 +1,36 @@
+# 概述
+
+本文档将帮助您从 Modern.js 2.0 升级到 Modern.js 3.0。
+
+## 升级概览
+
+Modern.js 3.0 带来了多项重大改进和变化，主要包括：
+
+- **构建工具升级**：默认使用 [Rspack](https://rspack.dev) 构建，不再支持 Webpack，构建配置与 [Rsbuild](https://v2.rsbuild.rs) 对齐。
+- **React 生态升级**：全面支持 [React 19](https://react.dev/blog/2024/04/25/react-19) 和 [React Router v7](https://reactrouter.com)。
+- **插件系统重构**：重新设计插件 API，支持在 CLI、Runtime、Server 层通过自定义插件扩展框架能力。
+- **React Server Component**：支持在 [CSR](/guides/get-started/glossary#csr) 和 [SSR](/guides/basic-features/render/ssr) 项目中使用 React Server Component。
+- **国际化增强**：提供开箱即用的 [i18n 插件](/guides/advanced-features/international)，简化国际化开发流程。
+- **SSG 能力完善**：提供完整的[静态站点生成（SSG）](/guides/basic-features/render/ssg)支持。
+- **路由配置增强**：支持[配置式路由](/guides/basic-features/routes/config-routes)，可单独使用或与[约定式路由](/guides/basic-features/routes/routes)结合，提供更灵活的路由定义方式。
+
+
+## 升级前置检查
+
+在开始升级之前，请确认：
+
+1. 当前项目使用的是 Modern.js 2.0
+2. 确定使用的 react 版本是 17 及以上
+2. 确定使用的 node.js 版本是 18.20.8 及以上，推荐使用 node.js 22 以上版本
+
+
+## 获取帮助
+
+如果在升级过程中遇到任何问题，您可以通过以下方式获取帮助：
+
+- 查阅 [Modern.js 官方文档](https://modernjs.dev)
+- 在 [GitHub Issues](https://github.com/web-infra-dev/modern.js/issues) 中搜索相关问题或提交新的 issue
+- 加入 [Modern.js Discord 社区](https://discord.gg/modernjs)与其他开发者交流
+
+我们建议在提交 issue 时提供尽可能详细的信息，包括错误日志、配置文件和复现步骤，以便更快地解决问题
+