@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/zh/guides/basic-features/{routes.mdx → routes/routes.mdx}

@@ -2,9 +2,9 @@
 sidebar_position: 2
 ---
 
-# 路由
+# 路由基础
 
-Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，提供了基于文件约定的路由能力，并支持了业界流行的约定式路由模式：**嵌套路由**。当入口被识别为 [约定式路由](/guides/concept/entries.html#约定式路由) 时，Modern.js 会自动基于文件系统，生成对应的路由结构。
+Modern.js 的路由基于 [React Router 7](https://reactrouter.com/en/main)，提供了基于文件约定的路由能力，并支持了业界流行的约定式路由模式：**嵌套路由**。当入口被识别为 [约定式路由](/guides/concept/entries.html#约定式路由) 时，Modern.js 会自动基于文件系统，生成对应的路由结构。
 
 :::note
 
@@ -49,7 +49,7 @@ Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，
 
 ```tsx title=routes/page.tsx
 export default () => {
-  return <div>Hello world</div>
+  return <div>Hello world</div>;
 };
 ```
 
@@ -68,7 +68,6 @@ export default () => {
 - `/`
 - `/user`
 
-
 ### Layout
 
 `<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件，它们表示对应路由片段的布局，使用 `<Outlet>` 表示子组件。
@@ -87,7 +86,7 @@ export default () => {
 
 :::note
 
-`<Outlet>` 是 React Router 6 中提供的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet)。
+`<Outlet>` 是 React Router v7 中提供的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet)。
 
 :::
 
@@ -190,7 +189,6 @@ function Blog() {
 export default Blog;
 ```
 
-
 ## 通配路由
 
 如果在某个子目录下存在 `$.tsx` 文件，该文件会作为通配路由组件，当没有匹配的路由时，会渲染该路由组件。
@@ -239,9 +237,9 @@ import { useParams } from '@modern-js/runtime/router';
 function Blog() {
   // 当 path 是 `/blog/aaa/bbb` 时
   const params = useParams();
-  console.log(params) // ---> { '*': 'aaa/bbb' }
+  console.log(params); // ---> { '*': 'aaa/bbb' }
 
-  return <div>current blog URL is {params["*"]}</div>;
+  return <div>current blog URL is {params['*']}</div>;
 }
 export default Blog;
 ```
@@ -351,7 +349,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 ```ts title="routes/user/page.data.ts"
 import { redirect } from '@modern-js/runtime/router';
 
-export const loader = () => {
+export const loader = async () => {
   const user = await getUser();
   if (!user) {
     return redirect('/login');
@@ -484,89 +482,17 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 - `render`，当 `<Link>` 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
 
 :::details 值为 render 和不做路由分片的区别
+
 - `render` 加载路由分片的时机是可控的，只有在 `<Link>` 组件进入视窗时才触发，可以通过控制 `<Link>` 组件的渲染位置来控制分片加载时机。
 - `render` 仅在空闲时对静态资源进行加载，不占用重要模块的加载时间。
 - 除了预加载路由分片，`render` 在 SSR 项目中还会发起数据预取。
 
 :::
 
-
 import Motivation from '@site-docs/components/convention-routing-motivation';
 
 <Motivation />
 
-## 升级到 react-router v7
-
-React Router v7 相比 React Router v6 减少了包体积（小约 15%），提供了更高效的路由匹配算法，对 React 19 和 TypeScript 也提供了更好的支持，
-相比 React Router v6 breaking change 非常少，同时 Modern.js 也对两个版本做了兼容，只需在项目中安装并注册相应的插件即可无缝升级。
-
-:::info
-
-更多 react router v6 到 react router v7 的变更，请查看[文档](https://reactrouter.com/upgrading/v6#upgrade-to-v7)
-
-:::
-
-### 环境要求
-
-React Router v7 对环境有一定要求：
-
-- Node.js 20+
-- React 18+
-- React DOM 18+
-
-### 安装插件
-
-首先，安装 Modern.js 的 React Router v7 插件：
-
-```bash
-pnpm add @modern-js/plugin-router-v7
-```
-
-### 配置插件
-
-在 `modern.config.ts` 中注册插件：
-
-```ts title="modern.config.ts"
-import { routerPlugin } from '@modern-js/plugin-router-v7';
-
-export default {
-  runtime: {
-    router: true,
-  },
-  plugins: [routerPlugin()],
-};
-```
-
-### 修改代码
-
-在 react router v7 中，不需要再使用 `defer` API 了，直接在 data loader 中返回数据即可：
-
-```ts title="routes/page.data.ts"
-import { defer } from '@modern-js/runtime/router';
-
-export const loader = async ({ params }) => {
-  // 推荐的 v7 风格
-  const user = fetchUser(params.id)
-  return { user };
-
-  // v6 风格，Modern.js 做了兼容，仍然可以继续使用
-  return defer({ data: 'hello' });
-};
-```
-
-react router v7 同样废弃了 `json` API：
-
-```ts title="routes/page.data.ts"
-export const loader = async ({ params }) => {
-  // 推荐的 v7 风格
-  return { data: 'hello' };
-
-  // v6 风格，Modern.js 做了兼容，仍然可以继续使用
-  return json({ data: 'hello' });
-};
-```
-
-
 ## 常见问题
 
 1. 为什么要提供 `@modern-js/runtime/router` 来导出 React Router API ?
@@ -582,35 +508,3 @@ export const loader = async ({ params }) => {
 如果应用中必须直接使用 React Router 包的 API，例如部分路由行为被封装在统一的 npm 包中，那应用可以通过设置 [`source.alias`](/configure/app/source/alias)，将 `react-router` 和 `react-router-dom` 统一指向项目的依赖，避免两个版本的 React Router 同时存在的问题。
 
 :::
-
-2. 关于 `config` 函数和 `init` 函数的说明
-
-:::warning 不推荐使用
-
-Modern.js 早期版本支持在路由 layout 文件中通过导出 `config` 函数和 `init` 函数进行运行时配置和执行初始化操作。这些方式目前仍然**被支持**，但我们**强烈推荐**使用 [Runtime 配置文件](/configure/app/runtime/0-intro) 和 [Runtime 插件](/plugin/introduction.html#runtime-插件) 实现对应功能。
-
-:::
-
-**config**
-
-在路由组件中，你可以通过导出 `config` 函数来添加动态 Runtime 配置：
-
-```tsx
-// routes/layout.tsx
-export const config = () => {
-  return {
-    // 动态 Runtime 配置
-  };
-};
-```
-
-**init**
-
-在路由组件中，你可以通过导出 `init` 函数来执行预渲染逻辑：
-
-```tsx
-// routes/layout.tsx
-export const init = () => {
-  // 初始化逻辑
-};
-```

package/docs/zh/guides/basic-features/static-assets/json-files.mdx

@@ -4,7 +4,7 @@ sidebar_position: 12
 
 # 引用 JSON 文件
 
-Modern.js 支持在代码中引用 JSON 文件，也支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/en/) 文件并将其转换为 JSON 格式。
+Modern.js 默认支持在代码中引用 JSON 文件。可以通过 Rsbuild 插件来支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/en/) 文件并将其转换为 JSON 格式。
 
 ## JSON 文件
 
@@ -38,7 +38,16 @@ import { name } from './example.json';
 
 YAML 是一种数据序列化语言，通常用于编写配置文件。
 
-你可以直接在 JavaScript 中引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
+你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { pluginYaml } from '@rsbuild/plugin-yaml';
+
+export default defineConfig({
+  plugins: [pluginYaml()],
+});
+```
 
 ### 示例
 
@@ -76,7 +85,16 @@ declare module '*.yml' {
 
 TOML 是一种语义明显、易于阅读的配置文件格式。
 
-你可以直接在 JavaScript 中引用 `.toml` 文件，它会被自动转换为 JSON 格式。
+你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml) 来支持引用 `.toml` 文件，它会被自动转换为 JSON 格式。
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { pluginToml } from '@rsbuild/plugin-toml';
+
+export default defineConfig({
+  plugins: [pluginToml()],
+});
+```
 
 ### 示例
 

package/docs/zh/guides/basic-features/static-assets.mdx

@@ -28,7 +28,7 @@ SVG 图片是一种特殊情况，Modern.js 提供了 SVG 转 React 组件的能
 // 引用 static 目录下的 logo.png 图片
 import logo from './static/logo.png';
 
-export default = () => <img src={logo} />;
+export default () => <img src={logo} />;
 ```
 
 也支持使用[路径别名](/guides/basic-features/alias.html)来引用：
@@ -36,7 +36,7 @@ export default = () => <img src={logo} />;
 ```tsx
 import logo from '@/static/logo.png';
 
-export default = () => <img src={logo} />;
+export default () => <img src={logo} />;
 ```
 
 ## 在 CSS 文件中引用

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

@@ -12,7 +12,7 @@ import { PackageManagerTabs } from '@theme';
 
 ```ts
 import { defineConfig } from 'cypress'
- 
+
 export default defineConfig({
   e2e: {
     setupNodeEvents(on, config) {},
@@ -57,13 +57,13 @@ describe('Navigation', () => {
   it('should navigate to the about page', () => {
     // Start from the index page
     cy.visit('http://localhost:8080/')
- 
+
     // Find a link with an href attribute containing "about" and click it
     cy.get('a[href*="about"]').click()
- 
+
     // The new url should include "/about"
     cy.url().should('include', '/about')
- 
+
     // The new page should contain an h1 with "About"
     cy.get('h1').contains('About')
   })
@@ -92,4 +92,4 @@ DevTools listening on ws://127.0.0.1:55203/devtools/browser/xxxxx
 
 Cypress 会打开一个无头浏览器，按照提示你可以找到对应的测试文件，并自动运行 E2E 测试：
 
-![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)
+![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)

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

@@ -6,17 +6,17 @@ Jest 是一个 JavaScript 测试框架，它主要和 React Testing Library 一
 
 import { PackageManagerTabs } from '@theme';
 
-<PackageManagerTabs command={{ 
-  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom", 
-  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom", 
+<PackageManagerTabs command={{
+  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
+  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
   pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
 }} />
 
-随后，你可以运行以下命令，这将自动在项目中初始化 Jets，并生成一个基础的 `jest.config.[jt]s` 配置：
+随后，你可以运行以下命令，这将自动在项目中初始化 Jest，并生成一个基础的 `jest.config.[jt]s` 配置：
 
-<PackageManagerTabs command={{ 
-  npm: "npm init jest@latest", 
-  yarn: "yarn create jest@latest", 
+<PackageManagerTabs command={{
+  npm: "npm init jest@latest",
+  yarn: "yarn create jest@latest",
   pnpm: "pnpm create jest@latest"
 }} />
 
@@ -28,9 +28,9 @@ import { PackageManagerTabs } from '@theme';
 
 相比于其他的测试框架，Jest 在构建层面需要更多的配置，例如处理 JSX 和 ESM 语法，因此首先需要安装一些额外的依赖：
 
-<PackageManagerTabs command={{ 
-  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript", 
-  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript", 
+<PackageManagerTabs command={{
+  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
+  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
   pnpm: "pnpm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript"
 }} />
 
@@ -78,7 +78,7 @@ module.exports = {
 
 ## 编写测试用例
 
-现在，你可以开始编写测试用了，首先在 `package.json` 中添加一个 `test` 命令：
+现在，你可以开始编写测试用例了，首先在 `package.json` 中添加一个 `test` 命令：
 
 ```json title="package.json"
 {
@@ -145,4 +145,4 @@ Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        0.959 s, estimated 1 s
-```
+```

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

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # 构建工具
 
-Modern.js 构建是基于 [Rsbuild](https://rsbuild.rs/) 实现的，并支持在 Webpack 和 Rspack 两种打包工具间无缝切换。
+Modern.js 构建是基于 [Rsbuild](https://rsbuild.rs/) 实现的，使用 Rspack 作为打包工具。
 
 :::tip 什么是 Rsbuild
 Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，更易用、开箱即用。
@@ -14,14 +14,29 @@ Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，
 
 从构建的角度看，Modern.js 分为三层架构，从上到下依次是：
 
-- 研发框架：Modern.js（开源）和 EdenX（内部）。
+- 研发框架：Modern.js。
 - 构建工具：Rsbuild。
-- 打包工具：Webpack 和 Rspack。
+- 打包工具：Rspack。
 
-<img
-  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/build-layers-02193.png"
-  style={{ width: '100%', maxWidth: '540px' }}
-/>
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    Framework("研发框架: Modern.js")
+    BuildTool("构建工具: Rsbuild")
+    Bundler("打包工具: Rspack")
+
+    Framework --> BuildTool
+    BuildTool --> Bundler
+
+    style Framework fill:#FDE68A,stroke:#F59E0B,stroke-width:2px
+    style BuildTool fill:#86EFAC,stroke:#10B981,stroke-width:2px
+    style Bundler fill:#93C5FD,stroke:#3B82F6,stroke-width:2px
+
+`}
+
+</Mermaid>
 
 ## 构建文档
 
@@ -33,9 +48,9 @@ Rsbuild 的文档地址为：https://rsbuild.rs/
 
 ## 构建插件
 
-在 Modern.js 中，你可以注册 Webpack 插件、Rspack 插件或 Rsbuild 插件：
+在 Modern.js 中，你可以注册 Rspack 插件或 Rsbuild 插件：
 
-- Webpack / Rspack 插件：通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置。
+- Rspack 插件：通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置。
 - Rsbuild 插件：通过 [builderPlugins](/configure/app/builder-plugins) 配置。
 
 ## 构建能力