@modern-js/main-doc 2.9.0 → 2.11.0

package/docs/zh/blog/updates/2022-0708-updates.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 99
+---
+
+# 2022 年 7 ~ 8 月更新内容
+
+> 发表于 2022.09.05
+
+Modern.js 7 ~ 8 月的最新版本为 v1.17.0，本双月的主要更新有：
+
+- **支持 React 18**：完成框架和插件对 React 18 的适配。
+- **包版本统一**：Modern.js 所有组成包的版本号进行统一，提供升级命令。
+- **模块工程支持 bundle 构建**：模块工程类型的项目，支持对产物做 bundle 构建。
+- **Reduck v1.1**：发布 Reduck v1.1，使用文档全面更新。
+
+## 支持 React 18
+
+Modern.js 框架和相关插件完成对 React 18 的适配。现在，只需要将项目中的 `react`、`react-dom` 两个包的版本，升级到最新的 React 18 大版本，就可以使用 React 18 的新功能。
+
+注意，使用 `@modern-js/create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
+
+另外，SSR 流式渲染功能，目前尚在开发中，暂不支持。
+
+## Modern.js 包版本统一
+
+之前，组成 Modern.js 的各个包的版本号并不统一，Modern.js 自身的版本和这些包的版本缺少明确的对应关系。这不仅增加了我们的维护成本，而且给用户的使用和升级带来了很多困扰。
+
+从 v1.15.0 版本开始，Modern.js 自身的版本号和所有组成包的版本号，进行了统一。例如，Modern.js v1.15.0，意味着所有组成包的版本号也是 v1.15.0。 每次发布新版本，Modern.js 所有包都会使用统一的版本号执行发布。 Github 上仓库的 [tag](https://github.com/modern-js-dev/modern.js/tags) 编号和 Modern.js 所有组成包的版本号是一一对应的。
+
+我们提供了专门的升级工具： `@modern-js/upgrade`，可以自动升级 Modern.js 到当前的最新版本。使用方式为，在项目根路径下执行：
+
+```bash
+npx @modern-js/upgrade
+```
+
+## 模块工程支持 bundle 构建
+
+模块工程（ `@modern-js/module-tools` ）对底层实现进行重构，新增 [`output.buildConfig`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/) 配置，用于提供更加丰富的构建功能。
+
+新的模块工程项目，不仅支持对产物做 bundless 构建，也支持 bundle 构建。通过配置 `buildConfig` 下的 [`buildType`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/build-type) ，即可进行 bundle 构建：
+
+```ts
+// modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  output: {
+    buildConfig: {
+      buildType: 'bundle', // 采用 bundle 构建
+    },
+  },
+});
+```
+
+`buildConfig` 下还支持 [`bundleOptions`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/bundle-options) 配置，可以对构建行为做更多的自定义：如设置产物文件名、是否进行代码分片、设置代码压缩方式等。
+
+## Reduck v1.1
+
+Reduck 作为 Modern.js 的第一方状态管理方案，发布 v1.1 版本，增加对 React 18 Concurrent Rendering 的支持，并对开发体验和功能稳定性做了大量优化。
+
+新增 API：
+
+- [`useStore`](https://modernjs.dev/v1/docs/apis/app/runtime/model/use-store) ：可以在组件内获取当前组件树共享的 Store，满足在组件外访问 Model 的场景需求。
+- [`handleEffect`](https://modernjs.dev/v1/docs/apis/app/runtime/model/handle-effect)：一个工具函数，可以极大地简化异步数据获取的逻辑代码。
+- [`connect`](https://modernjs.dev/v1/docs/apis/app/runtime/model/connect)： HOC 风格的 API，用于访问 Model。
+
+开发体验方面，优化 Reduck 组成包的组织结构，减少用户侧依赖数量，现在只需要引入 `@modern-js-reduck/react` 一个包（Modern.js 中 Reduck 功能已内置，无需手动引入包）；优化 API 的 TS 类型定义，改进类型信息的自动推导，整体达到 TS 支持开箱即用。
+
+此外，对 Reduck [使用文档](https://modernjs.dev/v1/docs/guides/features/model/quick-start) 和 [API 文档](https://modernjs.dev/v1/docs/apis/app/runtime/model/model_) 做了全面更新，提供了更加丰富和详尽的内容。
+
+## 其他更新
+
+### 命令和配置
+
+**新增命令**
+
+- [`upgrade`](https://modernjs.dev/v1/docs/apis/app/commands/upgrade)：自动升级 Modern.js 版本。功能同执行 `npx @modern-js/upgrade` 命令。
+- [`inspect`](https://modernjs.dev/v1/docs/apis/app/commands/inspect)：通过该命令可以输出当前项目使用的完整 webpack 配置。
+- [`gen-release-note`](https://modernjs.dev/v1/docs/apis/module/commands/gen-release-note)：自动根据当前仓库的 [changesets](https://github.com/changesets/changesets) 信息生成发布日志。此外，我们提供了[包版本管理专题文档](https://modernjs.dev/v1/docs/guides/features/changesets/introduce)，方便大家更好的认识和使用 changesets 及相关功能。
+
+**新增配置**
+
+- [`source.preEntry`](https://modernjs.dev/v1/docs/apis/app/config/source/pre-entry)：用于配置全局脚本，这段脚本会早于页面的代码执行。
+
+### BFF
+
+- 新增 [`afterLambdaRegisted`](https://modernjs.dev/v1/docs/apis/app/runtime/bff-server/after-lambda-registed) hook。用于使用 Express 框架时，在 BFF 函数注册路由之后执行。可以用来添加错误处理逻辑，新增路由等。
+- 优化使用 Express 框架开发场景下的热更新性能。在比较大的项目中，BFF 函数更改，热更新也可以在几十毫秒内完成。
+
+### SSR
+
+- SSR 产物添加 Sourcemap，优化服务端调试 SSR 代码的体验。
+
+### Web Server
+
+- 支持按入口设置响应头，使用方式请参考[文档](https://modernjs.dev/v1/docs/apis/app/config/server/routes#自定义响应头)。

package/docs/zh/blog/updates/2022-0910-updates.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 98
+---
+
+# 2022 年 9 ~ 10 月更新内容
+
+> 发表于 2022.11.01
+
+Modern.js 9 ~ 10 月的最新版本为 v1.21.0，本双月的主要更新有：
+
+- **支持 pnpm v7**：完成框架对 pnpm v7 的支持。
+- **服务端增加 Typescript 作为 ts 文件编译器**。
+
+## 支持 pnpm v7
+
+Modern.js 框架完成了对 pnpm v7 的变更适配。
+
+使用 `npx @modern-js/create@modern-1` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
+`strict-peer-dependencies=false` 配置，避免安装时由于 `peerDependencies` 缺失导致安装依赖失败问题。
+同时适配 `release`、`deploy` 命令对 pnpm v7 的支持。
+
+pnpm v7 在命令传参方面姿势发生了变化，需注意：
+
+在使用 pnpm 调用 `package.json` 中的命令时，如果需要传递参数至 pnpm，需要将参数放到命令前。
+
+例如使用 pnpm `--filter` 参数执行 prepare 命令：
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+如果需要传递参数至命令，需要将参数放到命令后。
+
+例如，在如下 `package.json` 配置中：
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+执行 command 命令时携带参数方式为：
+
+```bash
+pnpm run command --options
+```
+
+## 服务端增加 Typescript 作为 ts 文件编译器
+
+在 Modernjs 之前的版本中，我们为了保证前后端编译器的统一，使用了 Babel 作为前后端默认的编译器，并保持相同的编译逻辑，但随着使用的项目增多，我们发现在一些服务端常用的语法场景下，Babel 编译 ts 有一些问题。
+
+因此，我们将服务端编译 ts 的编译器由 Babel 改为了 Typescript，在别名解析逻辑上与 Babel 版本保持一致，同样支持使用 `tsconfig.json` 或者插件设置别名。
+
+在执行 build 命令时，已默认使用 Typescript 编译，并默认开启了类型校验，很多项目在 9、10 双月已经在使用。
+
+执行 dev 命令时，如果希望使用 Typescript 编译，需要安装 `ts-node`，`tsconfig-paths` 到 `devDependencies`，否则默认仍然使用 Babel 编译。在 Modern.js 2.0 中，我们将使用 ts-node 作为默认的编译器。
+
+## 其他更新
+
+### 配置更新
+
+- 支持在 `tools.webpackChain` 中获取 `HtmlWebpackPlugin` 对象，使用方式请参考[文档](https://modernjs.dev/v1/docs/apis/app/config/tools/webpack-chain#htmlwebpackplugin)。
+
+### 底层依赖升级
+
+- husky 升级至 v8
+
+使用 `npx @modern-js/create@modern-1` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
+
+在初次安装依赖时需要执行 `npx husky install` 进行 husky 初始化，默认项目会在 prepare 命令中完成，如果 husky 配置未生效，可通过手动执行完成 husky 配置。
+
+## 功能预告
+
+Modern.js 团队目前除了正常开发维护 Modern 1.0 外，正在全力打造 Modern.js 2.0。
+
+Modern.js 2.0 将带来新的构建体系，除了支持使用稳定的 webpack 进行构建，还即将支持将底层构建工具切换为自研的 Rust bundler，提供更流畅的编译速度。
+
+Modern.js 2.0 将基于 [React-Router v6](https://reactrouter.com) 推荐嵌套路由作为新的路由方式；将默认支持 React 18 并提供 Streaming SSR 的支持，使用户体验更加流畅。

package/docs/zh/blog/updates/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "更新内容",
+  "position": 2,
+  "collapsed": false
+}

package/docs/zh/blog/updates/v2-release-note.mdx

@@ -0,0 +1,250 @@
+---
+sidebar_label: Modern.js v2 发布
+sidebar_position: 97
+---
+
+# Modern.js v2 发布：支持 Rspack 构建
+
+> 发表于 2023.03.16
+
+大家好，很高兴地向大家宣布，Modern.js v2 版本已经正式发布了！
+
+**Modern.js 是字节跳动 Web Infra 团队开源的一套 Web 工程体系**。在开源以来的一年多时间里，Modern.js 保持稳定的迭代节奏，数十位贡献者参与了开发，累计提交 2000+ 个 Pull Request，并支持了 Rspack 构建、嵌套路由、流式渲染等新特性。
+
+在这篇文章里，我们会和大家一起聊一聊 Modern.js 在过去一年多时间里的变化。
+
+![Modern.js v2 官网](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/Framework-Home.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>
+  Modern.js v2 官网
+</div>
+
+## 背景
+
+首先介绍一下我们为什么要做 Modern.js v2 版本，主要有以下几个原因：
+
+1. **下沉更多能力**：在字节跳动内部，Web Infra 团队整合了多个 Web 开发框架和解决方案，收敛技术栈，将通用能力下沉到底层的 Modern.js 工程体系中。
+2. **拥抱 Rust 生态**：随着社区中更多的前端工具链基于 Rust 重写，Modern.js 正在积极拥抱这一变化，将底层工具逐步替换为 Rust 实现。
+3. **底层依赖升级**：为了对 Modern.js 的底层依赖进行大版本升级，包括 React v18、React Router v6 等，从而引入流式渲染、嵌套路由等新能力。
+4. **定位调整**：从 2021 年开源以来，社区中的伙伴们给予我们很多有价值的反馈，这帮助我们对 Modern.js 的定位和架构进行更多地思考（详见下文）。
+
+以上因素促使我们完成了 Modern.js v2 版本。
+
+## 定位
+
+在 v2 版本中，我们重新明确了 Modern.js 的定位：**Modern.js 是字节跳动 Web 工程体系的开源版本，它提供多个解决方案，来帮助开发者解决不同研发场景下的问题。**
+
+目前我们开源了三个解决方案，分别面向 Web 应用开发场景、npm 包开发场景和文档站开发场景：
+
+![Modern.js 解决方案](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/Solutions.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>
+  Modern.js 解决方案
+</div>
+
+作为 Modern.js 工程体系的一部分，以上每个解决方案都可以被单独使用，并且各自部署了独立的文档站点。开发者可以按需选择其中的一个或多个解决方案来使用。
+
+在代码层面，这三个解决方案按照统一的研发规范迭代，并复用同一套插件机制，因此，它们提供的研发体验也较为一致。大家如果对内部实现感兴趣，可以在 GitHub 上的 [Modern.js 仓库](https://github.com/web-infra-dev/modern.js) 中找到它们的源代码。
+
+下面让我们来了解一下这三个解决方案提供的最新能力。
+
+## Modern.js 框架
+
+**Modern.js 框架是一个基于 React 的渐进式 Web 开发框架**。在字节跳动内部，我们将 Modern.js 封装为上层框架，并支撑了数千个 Web 应用的研发。
+
+> 由于 Modern.js 框架的使用最为广泛，在下文中，我们会省略「框架」，直接称其为 Modern.js。
+
+在 Modern.js 落地的过程中，我们收到很多业务同学提出的诉求，包括构建性能、框架的灵活性和可扩展性、页面加载性能等方面，相信社区中的开发者也会面临相似的问题。
+
+为了更好地满足这些诉求，Modern.js v2 提供了以下特性：
+
+- 通过引入 Rust 构建工具 —— Rspack 来提升构建性能。
+- 通过渐进式设计来保证框架的灵活性。
+- 通过插件系统来提供更好的可扩展性。
+- 通过嵌套路由来改善开发效率、优化加载性能。
+
+### Rspack 构建模式
+
+**Modern.js v2 提供开箱即用的双构建工具支持**，开发者可以在成熟的 Webpack 和更快的 Rspack 之间进行切换。大家对 Rspack 可能还不太了解，Rspack 是由字节跳动开源的 Web 构建工具，基于 Rust 语言开发，具有高性能、可定制、兼容 Webpack 生态等特性。
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/rspack-logo.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>Rspack Logo</div>
+
+相较于 Webpack，Rspack 的构建性能有明显提升，除了 Rust 带来的语言优势，这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证，**Rspack 可以给 Modern.js 项目带来 5 ～ 10 倍编译性能的提升。**
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/rspack-benchmark.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>Rspack Benchmark</div>
+
+**Modern.js 已支持在 Rspack 模式下使用框架的 70% 功能和配置项**，包括服务器端渲染（SSR），静态站点生成（SSG）、嵌套路由、CSS Modules 和 Tailwind CSS 等功能。除了功能，Modern.js 在 Rspack 模式下的配置项也与 Webpack 模式基本一致，在我们的实际验证中，一个小型项目花几分钟就可以平滑切换到 Rspack 模式。
+
+目前，Rspack 项目以及 Modern.js 的 Rspack 模式仍在快速迭代中。在未来几个月内，我们将逐步对齐 Webpack 模式和 Rspack 模式的绝大多数功能和配置，使更多项目能从 Webpack 平滑地过渡到 Rspack。
+
+> Rspack 已于 2023.03.10 号正式开源，你也可以在非 Modern.js 的项目中直接使用 Rspack 进行构建。如果你对 Rspack 感兴趣，请阅读 [「Rspack 正式发布了」](https://www.rspack.dev/zh/blog/announcement.html)来了解更多。
+
+### 渐进式设计
+
+大家对 Modern.js 框架的第一印象可能是「一个大而全的框架」，但事实上，为了避免变得臃肿，**Modern.js 采取了渐进式设计**，将所有功能建立在灵活的插件系统之上，因此具备按需启用和可插拔的能力。
+
+Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 modern new 命令一键开启，并自动安装相关依赖。
+
+![modern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>modern new 命令</div>
+
+比如：
+
+- 对于基础的开发场景，项目中只需安装 Modern.js 的 CLI 工具 `@modern-js/app-tools`，即具备了开发调试、生产构建的能力。
+- 当你需要在应用中增加一些 BFF 接口时，可以执行 modern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/bff-plugins.png)
+
+目前，你可以通过 `modern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new.png)
+
+### 插件系统
+
+开发者在实际项目中使用 Web 研发框架时，除了使用开箱即用的能力，也会有很强的定制化诉求。因此，Modern.js 设计了一套灵活的插件系统来满足这一点。
+
+Modern.js 可以划分为三个核心部分：**CLI 工具、服务端和运行时**。其中，CLI 工具负责提供 CLI 命令和打包构建能力；服务端提供 SSR、BFF 等能力；运行时提供状态管理、路由等能力。
+
+![Modern.js 核心模块](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-parts.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>
+  Modern.js 核心模块
+</div>
+
+我们为这三者分别设计了插件：
+
+- **CLI 插件**：对应 CLI 工具，负责控制 CLI 命令、打包构建流程。
+- **Server 插件**：对应服务端，用于处理服务端的生命周期以及客户端请求。
+- **Runtime 插件**：对应运行时，用于处理 React 组件渲染逻辑。
+
+这三种插件使用统一的 Hook 模型，并提供丰富的插件 API。比如，你可以使用插件做到：
+
+- 注册自定义的 CLI 命令
+- 修改 Rspack、PostCSS、Less、Sass 等基础工具的配置
+- 修改运行时需要渲染的 React 组件
+- 自定义控制台日志
+- 自定义 Node.js 服务器框架
+- ...
+
+在字节跳动内部，我们借助这些插件 API，结合公司内的基建和平台，封装出内部的企业级框架。如果你需要对 Modern.js 框架进行深度定制，也可以借助这些插件 API 来完成。
+
+> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/guides/topic-detail/framework-plugin/introduction.html)文档。
+
+### 嵌套路由
+
+**Modern.js v2 基于 React Router v6 提供了新的路由方式 —— 嵌套路由（Nested Routes）。**
+
+如果大家了解过 Remix 或 Next.js 13，应该对嵌套路由不陌生了。嵌套路由与 Modern.js v1 提供的约定式路由相似，也是一种基于文件系统的路由。
+
+在 Modern.js v2 中，我们约定在 `src/routes` 目录下的文件，在应用启动时会自动生成对应的路由结构，页面的路由与文件结构是相呼应的，并且可以为资源加载带来一些性能优化。
+
+Modern.js 的嵌套路由包含以下功能：
+
+- **资源加载**：基于路由结构，并行加载多级路由资源，子组件资源加载不再受父组件渲染影响。并且将路由资源进一步细分，保证路由跳转时的最小资源加载。
+- **共享布局**：在路由之间轻松共享 UI，同时保持状态，并避免多余的重新渲染。
+- **数据获取**：基于路由结构完成多级路由的数据并行获取。
+
+在 Modern.js v2 中，只需要配置 `runtime.router`，即可开启嵌套路由：
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/runtime-router.png)
+
+> 如果你对嵌套路由的细节感兴趣，请阅读[「Modern.js - 路由」](https://modernjs.dev/guides/basic-features/routes.html#%E8%B7%AF%E7%94%B1)文档。
+
+### 流式渲染
+
+**Modern.js v2 基于 React v18 的全新 API 支持了流式渲染（Streaming SSR）。**
+
+如果大家关注去年 React v18 的版本更新，可能会注意到它提供了新的 Server Side APIs，并对 Suspense 做了完整支持。在 Modern.js v2 中，我们通过 React Router v6 暴露的能力，在框架层面支持了流式渲染。
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/suspense.png)
+
+流式渲染利用 HTTP 的能力，允许将页面的 HTML 分割成较小的块，并逐步将这些块从服务器发送到客户端。页面无需等待所有数据加载完成，即可呈现完整用户界面，因此与数据无关的局部内容能够更早地显示出来。
+
+在 Modern.js v2 中，只需要配置 `server.ssr.mode`，即可开启流式渲染：
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/enable-streaming.png)
+
+> 如果你想在 Modern.js 中使用 SSR 和流式渲染，请阅读[「 Modern.js 服务端渲染（SSR）」](https://modernjs.dev/guides/advanced-features/ssr.html)文档。
+
+## Modern.js Module
+
+Modern.js Module 是我们针对 npm 包开发场景提供的解决方案，它为开发者提供了专业的 npm 包开发工具，能够更轻松地构建、调试和发布一个 npm 包。
+
+![Modern.js Module 首页](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/module-home.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>
+  Modern.js Module 首页
+</div>
+
+Modern.js Module 的核心能力包括：
+
+- **构建能力**：基于 esbuild 实现的构建工具，提供类型生成能力，能够高度定制构建产物。
+- **调试能力**：基于 Storybook 调试项目，可以测试代码功能、验证构建产物可用性。
+- **测试能力**：集成 Jest 测试能力，能够开箱即用地编写你的测试代码。
+- **版本管理能力**：基于 Changeset 提供版本管理命令，涵盖从开发到发布的过程。
+- **扩展能力**：提供包含丰富 Hooks 的插件机制，支持扩展调试能力，或对流程进行自定义。
+
+### 基于 esbuild 构建
+
+在 v2 版本中，我们以 esbuild 为核心，扩展其插件机制，并结合 SWC 实现了一个通用的模块构建工具，它的特性包括：
+
+- **支持 bundle 和 bundleless 两种模式的构建**。你可以选择构建产物的形式 —— 是打包处理后的 bundle 产物，还是直接通过 transform 处理的 bundleless 产物。
+- **相较于 esbuild，提供更丰富的构建能力和插件 Hook**。例如，在样式方面，默认支持 Less、Sass、PostCSS 和 CSS Modules，并支持静态资源处理、SVGR 等常用能力。这些能力在 bundle 和 bundleless 模式下均可使用。
+
+在生成 TS 类型文件上，Modern.js Module v2 也支持新的方式：
+
+- **类型文件的 bundle 处理**：对生成的类型文件进行打包处理，生成一个单独的类型文件。
+- **类型文件里的别名处理**：对生成的类型文件里包含的别名路径进行转换。
+
+总的来说，相较于 v1 版本，Modern.js Module v2 提供了更完整的构建能力，同时构建效率也有明显提升。
+
+> 如果你对 Modern.js Module 感兴趣，请移步[「Modern.js Module 文档」](https://modernjs.dev/module-tools)来了解更多。
+
+## Modern.js Doc
+
+Modern.js Doc 是一个面向文档站场景的框架，它的目标是给开发者提供一个简单、高效、可扩展的文档站解决方案。
+
+![Modern.js Doc 官网介绍页](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/doc-tools.png)
+
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>
+  Modern.js Doc 官网介绍页
+</div>
+
+目前，Modern.js Doc 包含如下能力：
+
+- **基于 Rspack 构建**：项目构建和 HMR 速度飞快，提供愉悦的开发和生产部署体验。
+- **支持 MDX 语法**：在普通 Markdown 语法的基础上可以嵌入 React 组件和 JSX 语法。
+- **全文搜索**：内置开箱即用的全文搜索能力，基于 FlexSearch 实现。
+- **支持国际化**：提供多语言文档切换功能，且支持多语言内容搜索。
+- **自定义主题**：内置一套默认主题，你可以基于这套主题进行扩展，也可以从零定制一套自定义主题。
+- **插件机制**：提供丰富的插件钩子能力，让你能够充分自定义扩展框架功能。
+
+我们做 Modern.js Doc 的初心，是为了解决我们团队内的文档站搭建需求。随着 Modern.js Doc 的功能逐渐完整，我们也将它开放给社区使用，使它能发挥更大的价值。
+
+目前，Modern.js Doc 仍处于 beta 测试状态，相关源代码已经开放在 [Modern.js 仓库](https://github.com/web-infra-dev/modern.js) 中，并提供了基础的 [使用文档](https://modernjs.dev/doc-tools)。在未来，我们将继续投入，使之成为一个完成度更高的文档解决方案。
+
+## 致谢
+
+Modern.js 中的部分代码实现参考了社区中的开源项目，我们对这些项目表示衷心的感谢：
+
+- `@modern-js/bundle-require`: 修改自 [bundle-require](https://github.com/egoist/bundle-require)。
+- `@modern-js/plugin`: hook API 的实现参考了 [farrow-pipeline](https://github.com/farrow-js/farrow/tree/master/packages/farrow-pipeline)。
+- `@modern-js/builder`: moduleScope 和 fileSize 插件参考了 [create-react-app](https://github.com/facebook/create-react-app)，TsConfigPathsPlugin 参考了 [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin)。
+- `@modern-js/plugin-testing`: jest runner 参考了 [jest-cli](https://github.com/facebook/jest/blob/fdc74af37235354e077edeeee8aa2d1a4a863032/packages/jest-cli/src/cli/index.ts#L21)。
+- `@modern-js/doc-tools`: 部分样式参考了 [vitepress](https://github.com/vuejs/vitepress)。
+- `@modern-js/plugin-data-loader`: 部分实现参考了 [remix](https://github.com/remix-run/remix)。
+- `@modern-js/utils`: generateMetaTags 函数参考了 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)。
+
+## 最后
+
+现阶段 Modern.js 仍是一个很年轻的开源项目，在未来，我们将继续拥抱长期主义，持续打磨功能和文档，并以更透明的方式与社区共同协作。
+
+如果你有兴趣尝试一下 Modern.js，欢迎试用并留下你的反馈意见~
+
+- 官网：[modernjs.dev](https://modernjs.dev)
+- GitHub 仓库：[github.com/web-infra-dev/modern.js](https://github.com/web-infra-dev/modern.js)

package/docs/zh/configure/app/output/splitRouteChunks.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_label: splitRouteChunks
+---
+
+# output.splitRouteChunks
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+当使用约定式路由时，框架会根据路由对 js 和 css 进行拆分，以实现按需加载。如果你的项目不希望根据路由对 js 和 css 进行拆分，可以将该选项设置为 `false`。
+
+示例
+
+```ts
+export default {
+  output: {
+    splitRouteChunks: false,
+  },
+}
+```

package/docs/zh/configure/app/source/config-dir.mdx

@@ -1,8 +1,8 @@
 ---
-title: source.configDir
 sidebar_label: configDir
 ---
-# configDir
+
+# source.configDir
 
 - **类型：** `string`
 - **默认值：** `./config`

package/docs/zh/configure/app/source/design-system.mdx

@@ -1,11 +1,11 @@
 ---
-title: source.designSystem
 sidebar_label: designSystem
 ---
-# designSystem
+
+# source.designSystem
 
 - **类型：** `Object`
-- **默认值：**见下方配置详情。
+- **默认值：** 见下方配置详情。
 
 :::caution 注意
 需要先通过 `pnpm run new` 启用 Tailwind CSS 功能。

package/docs/zh/configure/app/source/disable-default-entries.mdx

@@ -1,22 +1,16 @@
 ---
-title: source.disableDefaultEntries
 sidebar_label: disableDefaultEntries
 ---
-# disableDefaultEntries
+
+# source.disableDefaultEntries
 
 - **类型：** `boolean`
 - **默认值：** `false`
 
-关闭根据项目目录结构自动识别应用构建入口的功能，默认情况下，Modern.js 会根据项目目录结构得到对应构建入口。
+用于关闭基于目录结构来自动识别页面入口的功能。
 
 :::info
-默认情况下，Modern.js 会根据项目目录结构得到对应入口信息。具体可参考[入口](/guides/concept/entries)。
-配置关闭改机制后，需要使用 [`source.entries`](/configure/app/source/entries) 配置自定义入口。
-
-:::
-
-:::warning 警告
-推荐按照 Modern.js 提供的目录规范组织代码可以更好使用框架的功能，避免一些冗余的配置。
+默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，具体可参考[入口](/guides/concept/entries)。
 
 :::
 
@@ -29,3 +23,10 @@ export default defineConfig({
   },
 });
 ```
+
+关闭默认行为后，你需要使用 [`source.entries`](/configure/app/source/entries) 配置自定义的入口。
+
+:::warning
+我们推荐使用 Modern.js 提供的目录规范来组织代码，从而更好地使用框架功能，避免一些冗余的配置。
+
+:::

package/docs/zh/configure/app/source/disable-entry-dirs.mdx

@@ -1,9 +1,8 @@
 ---
-title: source.disableEntryDirs
-
 sidebar_label: disableEntryDirs
 ---
-# disableEntryDirs
+
+# source.disableEntryDirs
 
 - **类型：** `string[]`
 - **默认值：** `[]`

package/docs/zh/configure/app/source/enable-async-entry.mdx

@@ -1,13 +1,13 @@
 ---
-title: source.enableAsyncEntry
 sidebar_label: enableAsyncEntry
 ---
-# enableAsyncEntry
+
+# source.enableAsyncEntry
 
 - **类型：** `boolean`
 - **默认值：** `false`
 
-该选项用于 webpack 模块联邦 (Module Federation）场景。
+该选项用于 webpack 模块联邦（Module Federation）场景。
 
 开启此选项后，Modern.js 会通过 Dynamic Import 来包裹自动生成的入口文件（asynchronous boundary），使页面代码可以消费模块联邦生成的远程模块。
 

package/docs/zh/configure/app/source/entries-dir.mdx

@@ -1,14 +1,13 @@
 ---
-title: source.entriesDir
-
 sidebar_label: entriesDir
 ---
-# entriesDir
+
+# source.entriesDir
 
 - **类型：** `string`
 - **默认值：** `./src`
 
-默认会根据 `src` 目录识别应用入口，可通过该选项自定义应用入口的识别目录。
+Modern.js 默认会扫描 `src` 目录来识别页面入口，你可以通过该选项自定义页面入口的识别目录。
 
 例如，当配置与目录结构如下时：
 
@@ -25,16 +24,16 @@ export default defineConfig({
 └── src
     └── pages
         ├── a
-        │   └── App.jsx
+        │   └── App.tsx
         └── b
-            └── App.jsx
+            └── App.tsx
 ```
 
-Modern.js 会根据 `./src/pages` 目录结构生成构建入口 `a` 和入口 `b`，结果如下：
+Modern.js 会扫描 `./src/pages` 目录，自动生成构建入口 `a` 和入口 `b`，结果如下：
 
 ```js
- {
-   a: './src/pages/a/App.jsx',
-   b: './src/pages/b/App.jsx'
- }
+const entry = {
+  a: './src/pages/a/App.tsx',
+  b: './src/pages/b/App.tsx',
+};
 ```