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

package/docs/zh/guides/concept/entries.mdx

@@ -0,0 +1,323 @@
+---
+sidebar_position: 1
+---
+
+# 页面入口
+
+通过本章节，你可以了解到 Modern.js 中的入口约定，以及如何自定义入口。
+
+## 什么是入口
+
+**入口（Entry）指的是一个页面的起始模块。**
+
+在 Modern.js 应用中，每一个入口对应一个独立的页面，也对应一条服务端路由。默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，同时也支持通过配置项来自定义入口。
+
+Modern.js 提供的很多配置项都是以入口为维度进行划分的，比如页面标题、HTML 模板、页面 Meta 信息、是否开启 SSR/SSG、服务端路由规则等。如果你希望了解更多关于入口的技术细节，请参考[深入了解](#深入了解)章节的内容。
+
+## 单入口与多入口
+
+Modern.js 初始化的应用是单入口的，应用结构如下：
+
+```
+.
+├── src
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── package.json
+├── modern.config.ts
+└── tsconfig.json
+```
+
+在 Modern.js 应用中，你可以很方便的将单入口切换成多入口。手动创建多入口需要以下步骤：
+
+import NewEntryTooltip from '@site-docs/components/new-entry-tooltip.mdx';
+
+<NewEntryTooltip />
+
+1. **将原入口代码移动到以 `package.json` 中 `name` 命名的目录下**
+
+   假设 `package.json` 中的 `name` 为 `myapp`，需要将 `src/routes/` 目录移动到 `src/myapp/routes/`：
+
+```bash
+# 创建新目录
+mkdir -p src/myapp
+# 移动原入口代码
+mv src/routes src/myapp/routes
+```
+
+2. **创建新的入口目录**
+
+   创建新的入口目录，例如 `new-entry`：
+
+```bash
+# 创建新入口目录
+mkdir -p src/new-entry/routes
+```
+
+3. **在新入口目录下创建必要的文件**
+
+   在新入口的 `routes/` 目录下创建基础文件：
+
+```bash
+# 创建基础文件（可根据需要调整内容）
+touch src/new-entry/routes/index.css
+touch src/new-entry/routes/layout.tsx
+touch src/new-entry/routes/page.tsx
+```
+
+完成上述步骤后，`src/` 目录结构如下：
+
+```bash
+.
+├── myapp    # 原入口
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── new-entry # 新入口
+    └── routes
+        ├── index.css
+        ├── layout.tsx
+        └── page.tsx
+```
+
+Modern.js 会将与 `package.json` 文件中 `name` 字段同名的入口作为主入口，主入口的路由为 `/`，其他入口的路由为 `/{entryName}`。比如，`package.json` 中的 `name` 为 `myapp` 时，`src/myapp` 会作为应用的主入口。
+
+你可以执行 `pnpm run dev` 启动开发服务，此时可以看到新增了一条名为 `/new-entry` 的路由，并且原有页面的路由并未发生变化。
+
+:::note
+**单入口/多入口** 和 **SPA/MPA** 的概念并不等价。前者是关于如何配置和打包应用，而后者是组织前端应用的模式，每个入口都可以是 SPA 或非 SPA 的。
+:::
+
+## 入口类型
+
+Modern.js 支持三种入口类型，每种类型都有不同的使用场景和特点。选择合适的入口类型可以帮助你更好地组织代码。
+
+### 如何识别入口
+
+Modern.js 会自动扫描目录，识别符合条件的入口。一个目录被认定为入口需要满足以下**三个条件之一**：
+
+1. **具有 `routes/` 目录** → 约定式路由入口
+2. **具有 `App.tsx?` 文件** → 自控式路由入口
+3. **具有 `entry.tsx?` 文件** → 自定义入口
+
+import EntryScanLogic from '@site-docs/components/entry-scan-logic.mdx';
+
+<EntryScanLogic />
+
+:::tip 自定义扫描目录
+你可以通过 [source.entriesDir](/configure/app/source/entries-dir) 修改识别入口的目录。
+
+:::
+
+import EntryMode from '@site-docs/components/entry-mode.mdx';
+
+<EntryMode />
+
+接下来我们详细介绍每种入口类型的使用方法。
+
+### 约定式路由
+
+如果入口中存在 `routes/` 目录，我们称该入口为约定式路由。Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。例如：
+
+```bash
+src/
+└── routes/
+    ├── layout.tsx    # 布局组件（可选）
+    ├── page.tsx      # 首页组件（/ 路由）
+    ├── about/
+    │   └── page.tsx  # 关于页面（/about 路由）
+    └── blog/
+        ├── page.tsx  # 博客列表页（/blog 路由）
+        └── [id]/
+            └── page.tsx  # 博客详情页（/blog/:id 路由）
+```
+
+组件对应关系
+
+| 文件                        | 路由        | 说明               |
+| --------------------------- | ----------- | ------------------ |
+| `routes/layout.tsx`         | 全局布局    | 所有页面的外层容器 |
+| `routes/page.tsx`           | `/`         | 首页               |
+| `routes/about/page.tsx`     | `/about`    | 关于页面           |
+| `routes/blog/[id]/page.tsx` | `/blog/:id` | 动态路由页面       |
+
+详细内容可以参考[路由方案](/guides/basic-features/routes/routes#约定式路由)。
+
+### 自控式路由
+
+如果入口中存在 `App.tsx?` 文件，该入口就是自控式路由。这种方式给开发者完全的路由控制权。
+
+```bash
+.
+├── src
+│   └── App.tsx
+```
+
+以 `src/App.tsx` 为约定的入口，Modern.js 不会对路由做额外的操作，开发者可以使用 [React Router v7](https://reactrouter.com/en/main) 的 API 设置客户端路由，或不设置客户端路由。例如以下代码，在应用中自行设置了客户端路由：
+
+```tsx title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
+
+:::note
+我们推荐开发者使用约定式路由，Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化，并且提供了开箱即用的 SSR 能力。而在使用自控路由时，这些能力都需要开发者自行封装。
+:::
+
+### 自定义入口
+
+默认情况下，使用约定式路由或自控式路由时，Modern.js 会自动完成渲染。如果你希望自定义这个行为，可以通过自定义入口文件的方式来实现。
+
+:::tip
+自定义入口可以和约定式路由及自控式路由入口共存，自定义项目初始化的逻辑。
+
+:::
+
+如果入口中存在 `entry.tsx` 文件，则 Modern.js 不再控制应用的渲染流程，你可以在 `entry.tsx` 文件中调用 `createRoot` 和 `render` 函数，完成应用入口逻辑。
+
+```tsx title="src/entry.tsx"
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+// 创建根组件
+const ModernRoot = createRoot();
+
+// 渲染到 DOM
+render(<ModernRoot />);
+```
+
+上述代码中，`createRoot` 函数返回的组件为 `routes/` 目录生成或 `App.tsx` 导出的组件，`render` 函数用于处理渲染与挂载组件。例如，你希望在渲染前执行某些异步任务，可以这样实现：
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+  // some async request
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+如果你不想使用 Modern.js 任何运行时能力，也可以自行将组件挂载到 DOM 节点上，例如:
+
+```js title=src/entry.tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+const container = document.getElementById('root');
+
+if (container) {
+  const root = createRoot(container);
+  root.render(<App />);
+}
+```
+
+在该模式下，**将无法使用 Modern.js 框架的运行时能力**，比如：
+
+- 约定式路由，即基于 `src/routes` 下文件的路由
+- 服务端渲染（SSR）
+- 国际化能力（i18n）
+- 模块联邦能力（Module Federation）
+
+## 在配置文件中指定入口
+
+在某些情况下，你可能需要自定义入口配置，而不是使用 Modern.js 提供的入口约定。
+
+比如你需要将一个非 Modern.js 应用迁移到 Modern.js，它并不是按照 Modern.js 的目录结构来搭建的。如果你要将它改成 Modern.js 约定的目录结构，会存在一定的迁移成本。这种情况下，你就可以使用自定义入口。
+
+Modern.js 提供了以下配置项，你可以在 [modern.config.ts](/configure/app/usage) 中配置它们：
+
+- [source.entries](/configure/app/source/entries)：用于设置自定义的入口对象。
+- [source.disableDefaultEntries](/configure/app/source/disable-default-entries)：用于关闭 Modern.js 默认的入口扫描行为。当你使用自定义入口时，应用的部分结构可能会恰巧命中 Modern.js 约定的目录结构，但你可能不希望 Modern.js 为你自动生成入口配置，开启该选项可以避免这个问题。
+
+### 示例
+
+下面是一个自定义入口的例子，你也可以查看相关配置项的文档来了解更多用法。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      // 指定一个名为 'my-entry' 的入口
+      'my-entry': {
+        // 入口模块的路径
+        entry: './src/my-page/index.tsx',
+        // 关闭 Modern.js 自动生成入口代码的行为
+        disableMount: true,
+      },
+    },
+    // 禁用入口扫描行为
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## 深入了解
+
+页面通常与 HTML 产物对应，即每增加一个入口最终就会在产物中生成一份对应的 HTML 文件。入口引入的模块会在编译打包后生成多个 Chunk 产物，例如对于 JavaScript 模块最终可能会生成数个类似 `dist/static/js/index.ea39u8.js` 的文件产物。
+
+需要注意区分入口、路由等概念之间的关系：
+
+- **入口**：包含多个用于启动时执行的模块。
+- **客户端路由**：在 Modern.js 中通常由 `react-router` 实现，通过 History API 判断浏览器当前 URL 决定加载和显示哪个 React 组件。
+- **服务端路由**：由服务器根据请求 URL 决定返回什么内容。对于传统多页应用，不同 URL 通常会直接返回不同的 HTML 页面。对于使用客户端路由的单页应用，服务器一般会将非静态资源请求统一回退到入口 HTML，再由前端接管后续路由匹配与页面渲染
+
+它们的对应关系如下：
+
+- 每个网站项目可以包含多个入口
+- 每个入口包含若干个模块（源码文件）
+- 每个入口通常对应一个 HTML 文件产物和若干其它产物。
+- 每个 HTML 文件可以包含多个客户端路由方案（比如在页面中同时使用 `react-router` 和 `@tanstack/react-router`）。
+- 每个 HTML 文件可以被多个服务端路由对应。
+- 每个 HTML 文件可以包含多个客户端路由，当访问单入口应用的不同路由时实际使用的是同一个 HTML 文件。
+
+## 常见问题
+
+1. **`react-router` 定义的每个客户端路由会分别生成一个 HTML 文件吗？**
+
+不会。每个入口通常只会生成一个 HTML 文件，单个入口中如果定义多个客户端路由系统会共用这一个 HTML 文件。
+
+2. **约定式路由的 `routes/` 目录下每个 `page.tsx` 文件都会生成一个 HTML 文件吗？**
+
+不是。约定式路由是基于 `react-router` 实现的客户端路由方案，其约定 `routes/` 目录下每个 `page.tsx` 文件都会对应生成一个 `react-router` 的客户端路由。`routes/` 本身作为一个页面入口，对应最终产物中的一个 HTML 文件。
+
+3. **服务端渲染（SSR）的项目是否会构建多份 HTML 产物？**
+
+在使用服务端渲染应用时并不必须在编译时生成一份 HTML 产物，它可以只包含用于渲染的服务端 JavaScript 产物。此时 `react-router` 将在服务端运行和调度路由，并在每次请求时渲染并响应 HTML 内容。
+
+而 Modern.js 在编译时仍会为每个入口生成包含 HTML 文件的完整的客户端产物，用于在服务端渲染失败时降级为客户端渲染使用。
+
+另一个特殊情况是使用静态站点生成（SSG）的项目，即使是使用约定式路由搭建的单入口 SSG 应用，Modern.js 也会在 Rspack 的流程外为每个 `page.tsx` 文件生成一份单独的 HTML 文件。
+
+需要注意的是即使开启服务端渲染，React 通常仍需要执行水合阶段并在前端执行 `react-router` 的路由。
+
+4. **单入口应用是否存在输出多个 HTML 文件的例外情况？**
+
+你可以自行配置 [html-rspack-plugin](https://rspack.rs/zh/plugins/rspack/html-rspack-plugin#%E7%94%9F%E6%88%90%E5%A4%9A%E4%B8%AA-html-%E6%96%87%E4%BB%B6) 为每个入口生成多个 HTML 产物，或使多个入口共用一个 HTML 产物。
+
+5. **什么叫多页应用（Multi-Page Application）？**
+
+多页应用的 **页面** 指的是静态的 HTML 文件。
+一般可以将任何包含多个入口、多个 HTML 文件产物的网页应用称为多页应用。
+狭义的多页应用可能不包含客户端路由、仅通过 `<a>` 之类的标签元素进行 HTML 静态页面之间的跳转，但实践中上多页应用也经常需要为其入口配置客户端路由以满足不同需求。
+
+相反地，通过 `react-router` 定义多个路由的单入口应用因为只生成一个 HTML 文件产物，所以被称为单页应用（Single Page Application）。

package/docs/zh/guides/concept/server.mdx

@@ -0,0 +1,35 @@
+# Web 服务器
+
+Modern.js 为应用提供了内置的 Web 服务器，可以被运行在任何拥有 Node.js 的容器环境中。无论是在本地开发环境中执行 `dev` 命令，或是执行 `build && serve` 命令运行生成环境产物，或是官方的部署方案，都是通过这个 Web 服务器来托管应用。
+
+## 底层依赖
+
+Modern.js 基于 [Hono 框架](https://hono.dev/) 搭建了自己的 Web 服务器。Hono 是一个小型、简单且超快速的基于 Web 标准的框架，它能在任何 JavaScript 运行时上运行。
+
+## 开发 & 生产
+
+Modern.js 开发环境和生产环境的 Web 服务器流程是完全同构的，你无需担心开发环境和生产环境的差异。
+
+在 [构建工具](/guides/concept/builder) 一节我们提到，Modern.js 底层构建能力由 Rsbuild 提供，而部分开发环境的服务端能力是与构建工具耦合的，例如 HMR。Modern.js 需要复用 Rsbuild Dev Server 的能力。
+
+在开发环境，Modern.js 直接使用了 Rsbuild 提供的中间件，包含 HMR、Proxy 等开发阶段需要的能力。同时，Modern.js 在这之上提供了 Mock、路由、渲染等能力：
+
+![Server](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/web-server-modern.jpeg)
+
+因此，在 Modern.js 中开发环境只是在生产环境上增加了中间件。生产环境的所有能力，在开发环境中也同样适用，两者不会产生割裂。
+
+:::tip
+静态资源文件能够直接被 Modern.js 的服务器托管，但在生产环境中，强烈推荐将这些内容上传到 CDN。
+:::
+
+## 在 CI 环境中运行
+
+Modern.js 支持在任何 Node.js 环境运行构建产物。在 CI 环境中，通常情况下已经安装了应用全部的依赖。
+
+你可以执行 [`modern build`](/apis/app/commands#modern-build) 来构建应用，执行 [`modern serve`](/apis/app/commands#modern-serve) 命令来运行 Web 服务器，启动 Modern.js 应用。
+
+## 在生产环境中运行
+
+在部署到生产环境时，产物体积应该尽可能小，而上述在 CI 中运行的方案，会保留原项目的所有产物。因此在生产环境，不推荐通过上述命令运行应用。
+
+Modern.js 提供了独立的部署方案，当运行 [`modern deploy`](/apis/app/commands#modern-deploy) 命令时，产物中会包含可运行 Web 服务器的入口文件。

package/docs/zh/guides/get-started/_meta.json

@@ -0,0 +1,8 @@
+[
+  "introduction",
+  "ultramodern",
+  "quick-start",
+  "upgrade",
+  "glossary",
+  "tech-stack"
+]

package/docs/zh/guides/get-started/glossary.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 4
+---
+
+# 名词解释
+
+## BFF
+
+BFF 是 "Backend For Frontend"（前端的后端） 的缩写。它是一种架构模式，表示为前端应用程序创建一个专门的后台服务。
+
+BFF 服务作为前端应用程序和服务端 API 之间的中介，可以为前端提供定制的 API 供其使用。这允许前端开发者对需要的数据和功能有更多的控制，而不必依赖后端服务提供相应的能力。
+
+## Bundler
+
+import Bundler from '@site-docs/components/bundler.mdx';
+
+<Bundler />
+
+## CSR
+
+CSR 是 "Client-Side Rendering"（客户端渲染）的缩写。它表示页面是在浏览器中通过 JavaScript 渲染的，数据获取、模板和路由等逻辑都在浏览器端完成，而不是在服务器上。
+
+在 CSR 中，服务器会向浏览器端发送一个空的 HTML 外壳和一些 JavaScript 脚本，然后由浏览器端从服务器的 API 中拉取数据，并将动态内容渲染到页面中。
+
+## Module Federation
+
+import ModuleFederation from '@site-docs/components/module-federation.mdx';
+
+<ModuleFederation />
+
+## Rsbuild
+
+import Rsbuild from '@site-docs/components/rsbuild.mdx';
+
+<Rsbuild />
+
+## Rspack
+
+import Rspack from '@site-docs/components/rspack.mdx';
+
+<Rspack />
+
+## SSR
+
+SSR 是 "Server-Side Rendering"（服务器端渲染）的缩写。它表示由服务器生成网页的 HTML，并将其发送给客户端，而不是只发送一个空的 HTML 外壳，并依赖 JavaScript 来生成页面内容。
+
+在传统的客户端渲染中，服务器会向客户端发送一个空的 HTML 外壳和一些 JavaScript 脚本，然后从服务器的 API 中获取数据，并用动态内容填充页面。这会导致页面的初始加载时间较慢，不利于用户体验和 SEO。
+
+使用 SSR 后，服务器会生成已经包含动态内容的 HTML，并将其发送给客户端。这使得首屏加载速度更快，并对 SEO 更加友好，因为搜索引擎可以爬取到渲染后的页面。
+
+## SSG
+
+SSG 是 "Static Site Generation"（静态网站生成）的缩写。它表示网页被预先渲染成静态的 HTML，然后直接提供给客户端，而不需要服务器实时生成 HTML。
+
+在传统的 SSR 中，每当用户请求一个页面时，服务器就会实时生成 HTML。有了 SSG，HTML 可以在构建过程中被提前生成，并被托管在 CDN 或其他静态资源服务中。
+
+与传统的 SSR 相比，SSG 可以提供更快的加载速度以及更少的服务端开销，因为不需要维护一个服务器来实时生成 HTML。然而，SSG 不适合需要动态内容的网站，因为 HTML 是在构建过程中生成的，不支持实时更新。
+
+## SWC
+
+import SWC from '@site-docs/components/swc.mdx';
+
+<SWC />

package/docs/zh/guides/get-started/introduction.mdx

@@ -0,0 +1,45 @@
+---
+title: 介绍
+sidebar_position: 1
+---
+
+# Modern.js 介绍
+
+**Modern.js 是一个基于 React 的渐进式 Web 开发框架**。在字节跳动内部，我们将 Modern.js 封装为上层框架，并支撑了数千个 Web 应用的研发。
+
+Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
+
+在开发 React 应用过程中，开发者通常需要去为某些功能去设计实现方案，或是使用其他的库、框架来解决这些问题。Modern.js 支持 React 应用所需要的所有配置和工具，并内置**额外的功能和优化**。开发者可以使用 React 构建应用的 UI，然后逐步采用 Modern.js 的功能来解决常见的应用需求，如路由、数据获取、状态管理等。
+
+它主要包含以下特性：
+
+- 🚀 **Rust 构建**：Modern.js 使用 Rsbuild/Rspack 作为构建工具，编译飞快。
+- 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
+- 🏠 **一体化**：开发与生产环境 Web Server 逻辑一致，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
+- 🕸 **约定式路由**：使用基于文件约定的路由，帮助开发者快速搭建应用。
+
+## 和其他框架的对比
+
+### Next.js
+
+Next.js 是社区中最流行的 React 框架之一，由 Vercel 开发。
+
+当你想构建一个单页面应用（SPA），并通过客户端渲染时，Next.js 可能不是一个好的选择，因为它的很多功能都是围绕 Server 优先来设计的。如果你需要使用客户端渲染，只能通过 Next.js 提供的 "static exports" 来使用有限的功能。
+
+Modern.js 将客户端渲染（CSR）和服务端渲染（SSR）视为同样重要的场景。当你创建一个 Modern.js 应用时，它默认是在客户端渲染的，你也可以在任何有需要的时候开启 SSR 或 Server Component，甚至可以为一部分页面开启 SSR，整个过程是完全渐进式的。
+
+### Umi
+
+Umi 是蚂蚁集团的底层前端框架。Modern.js 和 Umi 有许多相似之处，比如都支持插件系统、约定式路由、微生成器等。
+
+**Modern.js 和 Umi 的主要区别在于构建优化方式不同**。Umi 采用了 MFSU 技术来提升构建速度，而 Modern.js 则使用 Rspack 来提升 5 ~ 10 倍构建速度。在我们看来，类似 Rspack 这样的 Rust 工具更符合前端工具链的长期发展趋势，它可以在性能、稳定性和生态兼容性之间取得较好的平衡。
+
+此外，Modern.js 的服务端能力更加丰富，包括完备的 SSR 能力、一体化 BFF 开发能力和自定义 Web Server 支持。这些能力经过了字节跳动大量线上应用的验证，可以直接用于生产环境。
+
+### Remix
+
+请参考 [Modern.js vs Remix](https://github.com/web-infra-dev/modern.js/discussions/4872)。
+
+## 下一步
+
+如果你希望了解 Modern.js v3 与 UltraModern.js v3 的兼容优先差异，请阅读 [UltraModern.js](/guides/get-started/ultramodern)。

package/docs/zh/guides/get-started/quick-start.mdx

@@ -0,0 +1,90 @@
+---
+title: 快速上手
+sidebar_position: 2
+---
+
+# 快速上手
+
+## 环境准备
+
+import Prerequisites from '@site-docs/components/prerequisites';
+
+<Prerequisites />
+
+## 创建项目
+
+import InitApp from '@site-docs/components/init-app';
+
+<InitApp />
+
+## 启动项目
+
+import DebugApp from '@site-docs/components/debug-app';
+
+<DebugApp />
+
+## 使用配置
+
+通过 `@modern-js/create` 创建的 Modern.js 项目中，会默认生成 `modern.config.ts` 文件。
+
+你可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools()],
+});
+```
+
+重新执行 `pnpm run dev`，在浏览器 Network 菜单中，可以发现项目已经在服务端完成了页面渲染。
+
+## 核心 npm 包
+
+在新创建的工程中，默认会安装 `@modern-js/app-tools` npm 包，它是 Modern.js 框架的核心包，主要提供以下能力：
+
+- 提供 `modern dev`, `modern build` 等常用的 CLI 命令。
+- 集成 Rsbuild，提供构建能力。
+- 集成 Modern.js Server，提供开发和生产服务器相关能力。
+
+`@modern-js/app-tools` 是基于 Modern.js 的插件体系实现的，本质上是一个插件，因此你需要在配置文件的 `plugins` 字段中注册 `appTools`：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [appTools()],
+});
+```
+
+## 构建项目
+
+import BuildOutput from '@site-docs/components/build-output';
+
+<BuildOutput />
+
+## 本地验证
+
+在项目中执行 `pnpm run serve` 即可在本地验证构建产物是否正常运行：
+
+```bash
+$ pnpm run serve
+
+  Modern.js Framework
+
+info    Starting production server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+在浏览器中打开 `http://localhost:8080/`，内容应该和 `pnpm run dev` 时一致。
+
+## 部署
+
+import Deploy from '@site-docs/components/deploy';
+
+<Deploy />

package/docs/zh/guides/get-started/tech-stack.mdx

@@ -0,0 +1,91 @@
+---
+sidebar_position: 4
+---
+
+# 技术栈
+
+Modern.js 框架默认集成了一些社区中流行的库和开发工具。
+
+在这篇文档中，你可以了解到 Modern.js 框架涉及的主要技术栈，以及一些可选的库和工具。
+
+## UI 库
+
+Modern.js 使用 [React 19](https://react.dev/) 来构建用户界面，同时也兼容 React 18。
+
+Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue，可以参考 [Rsbuild - Vue](https://v2.rsbuild.rs/zh/guide/framework/vue)。
+
+## 路由
+
+Modern.js 提供两套一方路由方案：
+
+- 默认使用 [React Router 7](https://reactrouter.com/en/main)，通过 `@modern-js/runtime/router` 导出 API。
+- 支持 [TanStack Router](https://tanstack.com/router)，通过 `@modern-js/plugin-tanstack/runtime` 导出 API。
+
+创建项目时，可通过以下命令选择 TanStack Router：
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack
+```
+
+Modern.js 支持约定式路由、自控式路由或其他路由方案，请参考 [页面入口](/guides/concept/entries) 进行选择。
+
+## 包管理器
+
+Modern.js 可以与社区中任意的包管理器搭配使用，比如 [npm](https://www.npmjs.com/package/npm)、[yarn](https://classic.yarnpkg.com/lang/en/)、[pnpm](https://pnpm.io/) 或 [Bun](https://bun.sh/)。
+
+我们推荐使用 pnpm 来获得更快的安装速度。
+
+## 打包工具
+
+Modern.js 使用 [Rspack](https://rspack.rs/) 来打包你的 Web 应用。
+
+## 转译工具
+
+Modern.js 使用 [SWC](https://swc.rs/) 作为 JS 转译工具，将 TypeScript 或 JSX 转义为可以在浏览器上运行的 JavaScript 代码，并进行语法降级。
+
+在启用 Rspack 构建时，`babel-loader` 默认不会被启用。如需添加 [Babel](https://babeljs.io/) 插件，可通过 [`babel plugin`](https://v2.rsbuild.rs/plugins/list/plugin-babel#babel-plugin) 配置，此时会产生额外的编译开销，在一定程度上拖慢 Rspack 构建速度。
+
+## 压缩工具
+
+在生产环境构建时，Modern.js 使用 [SWC](https://swc.rs/) 压缩 JS 代码。
+
+## CSS 转换
+
+Modern.js 使用 [PostCSS](https://postcss.org/) 来转换 CSS 代码，并默认开启 [autoprefixer](https://github.com/postcss/autoprefixer) 来补全 CSS 前缀。
+
+Modern.js 支持 [启用 Lightning CSS](/configure/app/tools/lightningcss-loader)，使用 Lightning CSS 降级 CSS 语法。
+
+Modern.js 支持 [启用 Tailwind CSS](/guides/basic-features/css/tailwindcss)，并同时兼容 Tailwind CSS v3 和 v4 版本。
+
+## CSS 预处理器
+
+Modern.js 支持 [Sass](https://sass-lang.com/)、[Less](https://lesscss.org/) 和 [Stylus](https://stylus-lang.com/) 三种 CSS 预处理器：
+
+- 默认支持 Sass 和 Less，开箱即用。
+- 可选支持 Stylus，请参考 [Stylus 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-stylus) 来使用。
+
+## CSS Modules
+
+Modern.js 对 [CSS Modules](https://github.com/css-modules/css-modules) 提供了开箱即用的支持，内部基于 [css-loader](https://www.npmjs.com/package/css-loader) 实现。
+
+请参考 [使用 CSS Modules](/guides/basic-features/css/css-modules) 来使用。
+
+## CSS-in-JS
+
+Modern.js 支持使用 [styled-components](https://styled-components.com/)，请参考 [使用 CSS-in-JS](/guides/basic-features/css/css-in-js) 来使用。
+
+如果你需要使用其他 CSS-in-JS 方案，可以自行集成到你的项目中。
+
+## 组件库
+
+Modern.js 可以与社区中任意的 React 组件库搭配使用，比如 [MUI](https://mui.com/)、[Ant Design](https://ant.design/)、[Arco Design](https://github.com/arco-design/arco-design)、[Semi Design](https://semi.design/)、[Radix UI](https://www.radix-ui.com/) 等。
+
+## 组件开发
+
+Modern.js 支持使用 [Storybook](https://storybook.js.org/) 来开发 UI 组件。该功能为可选功能，请参考 [使用 Storybook](/guides/basic-features/debug/using-storybook) 启用。
+
+## Node.js 框架
+
+import TechStackNodeFramework from '@site-docs/components/tech-stack-node-framework';
+
+<TechStackNodeFramework />