@modern-js/main-doc 3.0.0-alpha.2 → 3.0.0

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -237,7 +237,7 @@ export default function DashboardPage() {
 
 ### 旧 CSR 项目
 
-如果是 CSR 项目，且项目中使用了 EdenX 的 data loader，开启 RSC 后，data loader 默认是在服务端执行，这意味着需要先把所有的 `.data.ts` 文件改为`.data.client.ts`，才能和之前的行为保持一致。
+如果是 CSR 项目，且项目中使用了 Modern.js 的 data loader，开启 RSC 后，data loader 默认是在服务端执行，这意味着需要先把所有的 `.data.ts` 文件改为`.data.client.ts`，才能和之前的行为保持一致。
 
 ### 使用 Streaming SSR 的项目
 

package/docs/zh/guides/basic-features/routes/config-routes.mdx

@@ -19,7 +19,7 @@ sidebar_position: 3
 
 ## 基本用法
 
-在 `src` 或每个入口目录下，你可以定义一个 `modern.routes.[tj]s` 文件，通过该文件，你可以对路由进行配置：
+在 `src` 或每个入口目录下，你可以定义一个 `modern.routes.ts` 文件，通过该文件，你可以对路由进行配置：
 
 ```ts
 import { defineRoutes } from '@modern-js/runtime/config-routes'
@@ -34,11 +34,11 @@ export default defineRoutes(({ route, layout, page, $ }, fileRoutes) => {
 ### 函数签名说明
 
 `defineRoutes` 接受一个回调函数，该回调函数有两个参数：
-1. `routeFunctions`: 包含 `route`、`layout`、`page`、`$` 函数的对象
-2. `fileRoutes`: 约定式路由生成的路由配置数组
+1. `routeFunctions`：包含 `route`、`layout`、`page`、`$` 函数的对象
+2. `fileRoutes`：约定式路由生成的路由配置数组
 
 路由函数的基本签名：
-- 第一个参数：相对于 `modern.routes.[tj]s` 的文件路径
+- 第一个参数：相对于 `modern.routes.ts` 的文件路径
 - 第二个参数：路由路径（可选，必须是字符串）
 - 第三个参数：子路由数组（可选）
 
@@ -61,13 +61,13 @@ Modern.js 提供了四个主要的路由配置函数：
 :::info
 
 - `route`、`layout`、`page`、`$` 等函数的第一个参数（组件文件路径）必须指向当前项目中的真实文件，暂不支持 `node_modules` 及 Monorepo 下其他仓库中的文件
-- 不支持使用路径别名（例如 `@/pages/...`、`~/pages/...` 等）；请使用相对于 `modern.routes.[tj]s` 的相对路径。
+- 不支持使用路径别名（例如 `@/pages/...`、`~/pages/...` 等），请使用相对于 `modern.routes.ts` 的相对路径。
 
 :::
 
 ### `route` 函数
 
-`route` 函数是通用的路由配置函数，会根据是否有子路由自动决定生成页面路由还是布局路由，可以代替 `layout`, `page`, `$`等函数。
+`route` 函数是通用的路由配置函数，会根据是否有子路由自动决定生成页面路由还是布局路由，可以代替 `layout`、`page`、`$`等函数。
 
 ```ts
 export default defineRoutes(({ route }, fileRoutes) => {
@@ -228,10 +228,10 @@ export default defineRoutes(({ page }, fileRoutes) => {
 
 ## 路由相关文件自动查找
 
-配置式路由会自动查找组件的配套文件，无需手动配置。对于 `modern.routes.[tj]s` 中指定的任意组件文件，Modern.js 会自动查找以下配套文件：
+配置式路由会自动查找组件的配套文件，无需手动配置。对于 `modern.routes.ts` 中指定的任意组件文件，Modern.js 会自动查找以下配套文件：
 
 ```ts
-// modern.routes.[tj]s
+// modern.routes.ts
 export default defineRoutes(({ route }, fileRoutes) => {
   return [
     route("pages/profile.tsx", "profile"),
@@ -417,10 +417,10 @@ npx modern routes
 
 报告中除了基本的路由信息外，还会显示每个路由找到的相关文件：
 
-- **`data`**: 服务端数据加载文件（`.data.ts`），用于在服务端获取数据
-- **`clientData`**: 客户端数据加载文件（`.data.client.ts`），用于在客户端重新获取数据
-- **`error`**: 错误边界文件（`.error.tsx`），用于处理路由渲染错误
-- **`loading`**: 加载状态组件文件（`.loading.tsx`），用于显示数据加载中的状态
-- **`config`**: 路由配置文件（`.config.ts`），用于配置路由元数据
+- **`data`**：服务端数据加载文件（`.data.ts`），用于在服务端获取数据
+- **`clientData`**：客户端数据加载文件（`.data.client.ts`），用于在客户端重新获取数据
+- **`error`**：错误边界文件（`.error.tsx`），用于处理路由渲染错误
+- **`loading`**：加载状态组件文件（`.loading.tsx`），用于显示数据加载中的状态
+- **`config`**：路由配置文件（`.config.ts`），用于配置路由元数据
 
 这些字段都是可选的，只有在找到对应文件时才会在报告中显示。通过查看这些字段，你可以快速了解每个路由的完整文件结构。

package/docs/zh/guides/basic-features/testing/jest.mdx

@@ -12,7 +12,7 @@ import { PackageManagerTabs } from '@theme';
   pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
 }} />
 
-随后，你可以运行以下命令，这将自动在项目中初始化 Jest，并生成一个基础的 `jest.config.[jt]s` 配置：
+随后，你可以运行以下命令，这将自动在项目中初始化 Jest，并生成一个基础的 `jest.config.ts` 配置：
 
 <PackageManagerTabs command={{
   npm: "npm init jest@latest",

package/docs/zh/guides/basic-features/testing/rstest.mdx

@@ -0,0 +1,94 @@
+# Rstest
+
+Rstest 是由 Rspack 团队开发的测试框架，基于 Rspack 构建，具有极快的测试执行速度。
+
+在 Modern.js 中使用 Rstest 需要先安装依赖，可以执行以下命令：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{
+  npm: "npm install -D @rstest/core jsdom @testing-library/react @testing-library/dom",
+  yarn: "yarn add -D @rstest/core jsdom @testing-library/react @testing-library/dom",
+  pnpm: "pnpm install -D @rstest/core jsdom @testing-library/react @testing-library/dom",
+  bun: "bun add -D @rstest/core jsdom @testing-library/react @testing-library/dom"
+}} />
+
+接下来，你需要创建一个 Rstest 配置文件 `rstest.config.ts`，内容如下：
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  environment: 'jsdom',
+});
+```
+
+更多关于 Rstest 配置的信息，可以参考 [Rstest 配置文档](https://rstest.rs/config)。
+
+你可以选择性的将 `rstest` 命令添加到 `package.json` 中：
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "rstest"
+  }
+}
+```
+
+运行该命令后，Rstest 会自动监听你的文件变化，并重新运行用例。
+
+## 创建单元测试
+
+首先，创建一个简单的页面用于测试：
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+添加测试用例，检测页面中是否有预期的文本：
+
+```tsx title="__tests__/page.test.tsx"
+import { expect, test } from '@rstest/core';
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import Page from '../routes/page';
+
+test('Page', () => {
+  render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
+});
+```
+
+上述用例中，我们从 `@modern-js/runtime/router` 引入了 `<Router>` 组件，这是因为 React Router 在渲染部分路由相关组件时，必须要有对应的上下文。
+
+:::note
+直接在 Modern.js 应用中运行时，`<Router>` 组件会自动注入。
+:::
+
+## 运行测试用例
+
+执行上述 `test` 命令，运行测试用例：
+
+```bash
+✓ src/__tests__/page.test.tsx (1)
+  ✓ Page
+
+Test Files  1 passed (1)
+    Tests  1 passed (1)
+  Duration  500ms
+
+PASS  Waiting for file changes...
+```

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

@@ -100,8 +100,8 @@ Modern.js 支持三种入口类型，每种类型都有不同的使用场景和
 Modern.js 会自动扫描目录，识别符合条件的入口。一个目录被认定为入口需要满足以下**三个条件之一**：
 
 1. **具有 `routes/` 目录** → 约定式路由入口
-2. **具有 `App.[jt]sx?` 文件** → 自控式路由入口
-3. **具有 `entry.[jt]sx?` 文件** → 自定义入口
+2. **具有 `App.tsx?` 文件** → 自控式路由入口
+3. **具有 `entry.tsx?` 文件** → 自定义入口
 
 import EntryScanLogic from '@site-docs/components/entry-scan-logic.mdx';
 
@@ -148,7 +148,7 @@ src/
 
 ### 自控式路由
 
-如果入口中存在 `App.[jt]sx?` 文件，该入口就是自控式路由。这种方式给开发者完全的路由控制权。
+如果入口中存在 `App.tsx?` 文件，该入口就是自控式路由。这种方式给开发者完全的路由控制权。
 
 ```bash
 .
@@ -186,7 +186,7 @@ export default () => {
 
 :::
 
-如果入口中存在 `entry.[jt]sx` 文件，则 Modern.js 不再控制应用的渲染流程，你可以在 `entry.[jt]sx` 文件中调用 `createRoot` 和 `render` 函数，完成应用入口逻辑。
+如果入口中存在 `entry.tsx` 文件，则 Modern.js 不再控制应用的渲染流程，你可以在 `entry.tsx` 文件中调用 `createRoot` 和 `render` 函数，完成应用入口逻辑。
 
 ```tsx title="src/entry.tsx"
 import { createRoot } from '@modern-js/runtime/react';
@@ -316,7 +316,7 @@ export default defineConfig({
 
 5. **什么叫多页应用（Multi-Page Application）？**
 
-多页应用的 “页面” 指的是静态的 HTML 文件。
+多页应用的 **页面** 指的是静态的 HTML 文件。
 一般可以将任何包含多个入口、多个 HTML 文件产物的网页应用称为多页应用。
 狭义的多页应用可能不包含客户端路由、仅通过 `<a>` 之类的标签元素进行 HTML 静态页面之间的跳转，但实践中上多页应用也经常需要为其入口配置客户端路由以满足不同需求。
 

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

@@ -16,8 +16,6 @@ Modern.js 能为开发者提供极致的**开发体验（Development Experience
 - 🚀 **Rust 构建**：Modern.js 使用 Rsbuild/Rspack 作为构建工具，编译飞快。
 - 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
 - 🏠 **一体化**：开发与生产环境 Web Server 逻辑一致，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
-- 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
-- 🌏 **周边生态**：自研状态管理、微前端、模块打包等周边需求。
 - 🕸 **约定式路由**：使用基于文件约定的路由，帮助开发者快速搭建应用。
 
 ## 和其他框架的对比
@@ -26,15 +24,13 @@ Modern.js 能为开发者提供极致的**开发体验（Development Experience
 
 Next.js 是社区中最流行的 React 框架之一，由 Vercel 开发。
 
-Next.js 默认使用了 React Server Components，这意味着**你需要在服务端渲染你的 Web 应用，并为服务器产生的开销付费**；并且 Server Components 目前不是一项稳定的技术，社区中很多流行的 React 库尚未完成对 RSC 的适配。在目前阶段，你可能需要使用 Next.js 旧版的 Pages Router 来避免 Server Components 带来的问题。
-
 当你想构建一个单页面应用（SPA），并通过客户端渲染时，Next.js 可能不是一个好的选择，因为它的很多功能都是围绕 Server 优先来设计的。如果你需要使用客户端渲染，只能通过 Next.js 提供的 "static exports" 来使用有限的功能。
 
-而 Modern.js 将客户端渲染（CSR）和服务端渲染（SSR）视为同样重要的场景。当你创建一个 Modern.js 应用时，它默认是在客户端渲染的，你不需要了解 Server Components 的用法和局限性。你也可以在任何有需要的时候开启 SSR，甚至可以为一部分页面开启 SSR，整个过程是完全渐进式的。请注意，Modern.js 目前不支持 Server Components，我们会持续观察它的潜力，并在合适的时候支持它。
+Modern.js 将客户端渲染（CSR）和服务端渲染（SSR）视为同样重要的场景。当你创建一个 Modern.js 应用时，它默认是在客户端渲染的，你也可以在任何有需要的时候开启 SSR 或 Server Component，甚至可以为一部分页面开启 SSR，整个过程是完全渐进式的。
 
 ### Umi
 
-Umi 是中文社区中非常流行的 React 框架，也是蚂蚁集团的底层前端框架。Modern.js 和 Umi 有许多相似之处，比如都支持插件系统、约定式路由、微生成器等。
+Umi 是蚂蚁集团的底层前端框架。Modern.js 和 Umi 有许多相似之处，比如都支持插件系统、约定式路由、微生成器等。
 
 **Modern.js 和 Umi 的主要区别在于构建优化方式不同**。Umi 采用了 MFSU 技术来提升构建速度，而 Modern.js 则使用 Rspack 来提升 5 ~ 10 倍构建速度。在我们看来，类似 Rspack 这样的 Rust 工具更符合前端工具链的长期发展趋势，它可以在性能、稳定性和生态兼容性之间取得较好的平衡。
 

package/docs/zh/guides/troubleshooting/dependencies.mdx

@@ -77,7 +77,7 @@ Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/r
 Type '{}' is not assignable to type 'ReactNode'.
 ```
 
-出现这个问题的原因是 React 18+ 与 React 16/17 中的 ReactNode 类型定义不同，如果项目中出现多个不同 `@types/react` 版本，就会出现 ReactNode 类型冲突，导致以上报错。
+出现这个问题的原因是 React 18/19 与 React 16/17 中的 ReactNode 类型定义不同，如果项目中出现多个不同 `@types/react` 版本，就会出现 ReactNode 类型冲突，导致以上报错。
 
 解决方法为将项目中的 `@types/react` 和 `@types/react-dom` 锁定在统一的版本上，比如 `v19`。