@modern-js/main-doc 2.20.0 → 2.21.0

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -58,3 +58,40 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 :::tip
 从 webpack 迁移至 Rspack 时，存在一些构建能力和配置上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
 :::
+
+## Rspack 和 Modern.js 的版本关系
+
+通常情况下，Modern.js 内会集成 Rspack 的最新版本，通过 `npx modern upgrade` 即可将当前项目中的 Modern.js 相关依赖以及内置的 Rspack 更新至最新版本。
+
+但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
+
+当你执行 dev / build 命令时，Modern.js 会自动打印当前使用的 Rspack 版本：
+
+![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/img_v2_dfcf051f-21db-4741-a108-d9f7a82c3abg.png)
+
+#### 修改内置 Rspack 版本
+
+可以使用 pnpm / yarn / npm 等包管理工具自带的依赖升级功能来将 Rspack 强制升级到指定版本。
+
+以 pnpm 为例，可通过 `overrides` 以下依赖更新 Rspack 版本:
+
+```json title=package.json
+{
+  "pnpm": {
+    "overrides": {
+      "@rspack/core": "nightly",
+      "@rspack/dev-client": "nightly",
+      "@rspack/dev-middleware": "nightly",
+      "@rspack/plugin-html": "nightly",
+      "@rspack/postcss-loader": "nightly"
+    }
+  }
+}
+```
+
+:::tip Nightly 版本介绍
+每天，Rspack 会自动构建基于最新代码的 nightly 版本，用于测试和及早发现错误。
+通常情况下，这些版本是可用的。如果发现问题，我们会及时进行修复。但是，如果 Rspack 有一些 break change，需要 Modern.js 同步修改代码，那么我们建议等待下一个 Modern.js 版本再进行更新。
+:::
+
+如果想了解其他包管理工具锁定依赖版本的示例，可以参考：[锁定子依赖](/guides/get-started/upgrade.html#%E9%94%81%E5%AE%9A%E5%AD%90%E4%BE%9D%E8%B5%96)。

package/docs/zh/guides/basic-features/data-fetch.mdx

@@ -14,7 +14,7 @@ Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过
 Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以有一个同名的 `loader` 文件，该 `loader` 文件需要导出一个函数，函数会在组件渲染之前执行，为路由组件提供数据。
 
 :::info
-Modern.js v1 支持通过 [useLoader](#useloader旧版) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
+Modern.js v1 支持通过 [useLoader](#useloader（旧版）) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
 
 :::
 
@@ -22,7 +22,7 @@ Modern.js v1 支持通过 [useLoader](#useloader旧版) 获取数据，这已经
 
 路由组件如 `layout.ts` 或 `page.ts`，可以定义同名的 `loader` 文件，`loader` 文件中导出一个函数，该函数提供组件所需的数据，然后在路由组件中通过 `useLoaderData` 函数获取数据，如下面示例：
 
-```
+```bash
 .
 └── routes
     ├── layout.tsx
@@ -66,19 +66,19 @@ export default async (): Promise<ProfileData> => {
 在 SSR 环境下，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
 
 :::info
-在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 loader 的纯粹，只做数据获取的场景。
+在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 `loader` 的纯粹，只做数据获取的场景。
 
 :::
 
-当在客户端导航时，基于 Modern.js 的[约定式路由](/guides/basic-features/routes)，所有的 loader 函数会并行执行（请求），即当访问 `/user/profile` 时，`/user` 和 `/user/profile` 下的 loader 函数都会并行执行（请求），以提高客户端的性能。
+当在客户端导航时，基于 Modern.js 的[约定式路由](/guides/basic-features/routes)，所有的 `loader` 函数会并行执行（请求），即当访问 `/user/profile` 时，`/user` 和 `/user/profile` 下的 loader 函数都会并行执行（请求），以提高客户端的性能。
 
 ### `loader` 函数
 
 `loader` 函数有两个入参：
 
-#### `Params`
+#### `params`
 
-当路由文件通过 `[]` 时，会作为[动态路由](/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 loader 函数：
+当路由文件通过 `[]` 时，会作为[动态路由](/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 `loader` 函数：
 
 ```tsx
 // routes/user/[id]/page.loader.ts
@@ -149,7 +149,7 @@ async function loader() {
 
 ### 错误处理
 
-在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 loader 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/guides/basic-features/routes#错误处理) 组件：
+在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 `loader` 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/guides/basic-features/routes#错误处理) 组件：
 
 ```tsx
 // routes/user/profile/page.loader.ts
@@ -178,14 +178,14 @@ export default ErrorBoundary;
 
 ### 获取上层组件的数据
 
-很多场景下，子组件需要获取到祖先组件 loader 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
+很多场景下，子组件需要获取到祖先组件 `loader` 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
 
 ```tsx
 // routes/user/profile/page.tsx
 import { useRouteLoaderData } from '@modern-js/runtime/router';
 
 export default function UserLayout() {
-  // 获取 routes/user/layout.loader.ts 中 loader 返回的数据
+  // 获取 routes/user/layout.loader.ts 中 `loader` 返回的数据
   const data = useRouteLoaderData('user/layout');
   return (
     <div>
@@ -198,7 +198,7 @@ export default function UserLayout() {
 
 `userRouteLoaderData` 接受一个参数 `routeId`，在使用约定式路由时，Modern.js 会为你自动生成`routeId`，`routeId` 的值是对应组件相对于 `src/routes` 的路径，如上面的例子中，子组件想要获取 `routes/user/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `user/layout`。
 
-在多 entry（MPA） 场景下，`routeId` 的值需要加上对应 entry 的 name，entry name 非指定情况下一般是 entry 目录名，如以下目录结构：
+在多入口（MPA） 场景下，`routeId` 的值需要加上对应入口的名称，入口名称非指定情况下一般是入口的目录名，如以下目录结构：
 
 ```bash
 .
@@ -211,7 +211,7 @@ export default function UserLayout() {
                 └── layout.tsx
 ```
 
-如果想获取 `entry1/routes/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `entry1_layout`。
+如果想获取 `entry1/routes/layout.tsx` 中 `loader` 返回的数据，`routeId` 的值就是 `entry1_layout`。
 
 ### (WIP)Loading UI
 
@@ -341,11 +341,11 @@ export default async (): Promise<ProfileData> => {
 
 ### 常见问题
 
-1. loader 和 BFF 函数的关系
+1. `loader` 和 BFF 函数的关系
 
-在 CSR 项目中，loader 在客户端执行，在 loader 可以直接调用 BFF 函数进行接口请求。
+在 CSR 项目中，`loader` 在客户端执行，在 `loader` 可以直接调用 BFF 函数进行接口请求。
 
-在 SSR 项目中，每个 loader 也是一个服务端接口，我们推荐使用 loader 替代 http method 为 `get` 的 BFF 函数，作为接口层，避免多一层转发和执行。
+在 SSR 项目中，每个 `loader` 也是一个服务端接口，我们推荐使用 `loader` 替代 http method 为 `get` 的 BFF 函数，作为接口层，避免多一层转发和执行。
 
 
 ## useLoader（旧版）

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

@@ -18,7 +18,7 @@ Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，
 
 Modern.js 支持了业界流行的约定式路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
 
-```
+```bash
 /user/johnny/profile                  /user/johnny/posts
 +------------------+                  +-----------------+
 | User             |                  | User            |
@@ -154,7 +154,7 @@ export default () => {
 
 通过 `[]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
 
-```
+```bash
 └── routes
     ├── [id]
     │   └── page.tsx
@@ -173,7 +173,7 @@ export default () => {
 
 通过 `[$]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
 
-```
+```bash
 └── routes
     ├── user
     │   └── [id$]
@@ -199,7 +199,7 @@ export default () => {
 
 例如以下目录结构：
 
-```
+```bash
 └── routes
     ├── $.tsx
     ├── blog
@@ -222,7 +222,7 @@ params['*']; // => 'aaa/bbb'
 
 当目录名以 \_\_ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
 
-```
+```bash
 .
 └── routes
     ├── __auth
@@ -245,7 +245,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 因此 Modern.js 支持了通过 `.` 来分割路由片段，代替文件目录。例如，当需要 `/user/profile/2022/edit` 时，可以直接创建如下文件：
 
-```
+```bash
 └── routes
     ├── user.profile.[id].edit
     │      └── page.tsx
@@ -281,7 +281,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 当定义 `loading.tsx` 时，就相当于以下布局：
 
-```tsx title="当路由为 / 时"
+```tsx title=当路由为"/"时
 <Layout>
   <Suspense fallback={<Loading />}>
     <Page />
@@ -289,7 +289,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 </Layout>
 ```
 
-```tsx title="当路由为 /blog 时"
+```tsx title=当路由为"/blog"时
 <Layout>
   <Suspense fallback={<Loading />}>
     <BlogPage />
@@ -297,7 +297,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 </Layout>
 ```
 
-```tsx title="当路由为 /blog/123 时"
+```tsx title=当路由为"/blog/123"时
 <Layout>
   <Suspense fallback={<Loading />}>
     <BlogIdPage />
@@ -306,8 +306,8 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 ```
 
 :::info
-当目录的 layout 组件不存在时，该目录下的 loading 组件也不会生效。
-Modern.js 建议必须有根 layout 和根 loading。
+当目录的 Layout 组件不存在时，该目录下的 Loading 组件也不会生效。
+Modern.js 建议必须有根 Layout 和根 Loading。
 
 :::
 
@@ -317,7 +317,7 @@ Modern.js 建议必须有根 layout 和根 loading。
 
 ### 路由重定向
 
-可以通过创建 [`data loader`](/guides/basic-features/data-fetch) 文件做路由的重定向，如有文件 `routes/user/page.tsx`，想对这个文件对应的路由做重定向，可以创建 `routes/user/page.loader.ts` 文件：
+可以通过创建 [`Data Loader`](/guides/basic-features/data-fetch) 文件做路由的重定向，如有文件 `routes/user/page.tsx`，想对这个文件对应的路由做重定向，可以创建 `routes/user/page.loader.ts` 文件：
 
 ```ts title="routes/user/page.loader.ts"
 import { redirect } from '@modern-js/runtime/router';
@@ -335,13 +335,13 @@ export default () => {
 
 `routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。
 
-当有路由目录下存在该组件时，组件渲染出错会被 ErrorBoundary 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
+当有路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
 
 `<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
 
 {/* Todo API 路由 */}
 
-在 `<ErrorBoundary>` 组件内，可以使用 [useRouteError](/apis/app/runtime/router/router#useparams) 获取的错误的具体信息：
+在 `<ErrorBoundary>` 组件内，可以使用 [useRouteError](/apis/app/runtime/router/router#userouteerror) 获取的错误的具体信息：
 
 ```tsx
 import { useRouteError } from '@modern-js/runtime/router';
@@ -359,7 +359,7 @@ export default ErrorBoundary;
 
 ### 运行时配置
 
-在每个根 `Layout` 组件中(`routes/layout.ts`)，可以动态地定义应用运行时配置：
+在每个根 `Layout` 组件中(`routes/layout.ts`)，可以动态地定义运行时配置：
 
 ```tsx title="src/routes/layout.tsx"
 // 定义运行时配置
@@ -447,29 +447,29 @@ export const init = (context: RuntimeContext) => {
 ### 预加载
 
 在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片，当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
-这种情况下你可以通过定义 `loading` 组件，在静态资源加载完成前，展示一个自定义的 `loading` 组件。
+这种情况下你可以通过定义 `Loading` 组件，在静态资源加载完成前，展示一个自定义的 `Loading` 组件。
 
 为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载， `prefetch` 属性有三个可选值：
 
-```
+```tsx
 <Link prefetch="intent" to="page">
 ```
 
 :::info
 - 该功能目前仅在 Webpack 项目中支持，Rspack 项目暂不支持。
-- 对数据的预加载目前只会预加载 SSR 项目中 [data loader](/guides/basic-features/data-fetch) 中返回的数据。
+- 对数据的预加载目前只会预加载 SSR 项目中 [Data Loader](/guides/basic-features/data-fetch) 中返回的数据。
 
 :::
 
 - `none`， 默认值，不会做 prefetch，没有任何额外的行为。
-- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 data loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
-- `render`，当 Link 组件渲染时，就会加载对应的分片和 data loader 中定义的数据。
+- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
+- `render`，当 Link 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
 
 #### 常见问题
 
 1. 使用 `render` 和不根据路由做静态资源分片的区别？
 
-- 使用 `render` 可以指定哪些路由在首屏时，进行加载，同时你可以通过对渲染的控制，仅当 Link 组件进入到可视区域时，才对 Link 组件进行渲染。
+- 使用 `render` 可以指定哪些路由在首屏时，进行加载，同时你可以通过对渲染的控制，仅当 `Link` 组件进入到可视区域时，才对 `Link` 组件进行渲染。
 - 使用 `render`，仅在空闲时对静态资源进行加载，不会与首屏静态资源抢占网络。
 - 在 SSR 场景下，也会对数据进行预取。
 
@@ -484,7 +484,7 @@ import Practice from '@site-docs/components/routes-practice'
 
 ## 自控式路由
 
-以 `src/App.tsx` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发，例如：
+以 `src/App.tsx` 为约定的入口，Modern.js 不会对路由做额外的操作，开发者可以自行使用 [React Router 6](https://reactrouter.com/en/main) 的 API 进行开发，例如：
 
 ```ts title="src/App.tsx"
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';

package/docs/zh/guides/topic-detail/framework-plugin/hook-list.mdx

@@ -2,6 +2,7 @@
 title: Hook 列表
 sidebar_position: 8
 ---
+
 # Hook 列表
 
 在 Modern.js 中暴露了三类插件：CLI、Runtime、Server。下面列举下各类中的 Hook：
@@ -166,7 +167,6 @@ export default (): CliPlugin => ({
 });
 ```
 
-
 ### `commands`
 
 - 功能：为 command 添加新的命令
@@ -260,9 +260,9 @@ export default (): CliPlugin => ({
 ### `afterDev`
 
 - 功能：运行 dev 主流程的之后的任务
-- 执行阶段：`dev` 命令运行时，项目启动完成之后执行
+- 执行阶段：运行 `dev` 命令时，每一次编译完成后执行
 - Hook 模型：AsyncWorkflow
-- 类型：`AsyncWorkflow<void, unknown>`
+- 类型：`AsyncWorkflow<{ isFirstCompile: boolean }, unknown>`
 - 使用示例：
 
 ```ts
@@ -279,6 +279,24 @@ export default (): CliPlugin => ({
 });
 ```
 
+`afterDev` 会在每一次编译完成后执行，你可以通过 `isFirstCompile` 参数来判断是否为首次编译：
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  setup(api) {
+    return {
+      afterDev: ({ isFirstCompile }) => {
+        if (isFirstCompile) {
+          // do something
+        }
+      },
+    };
+  },
+});
+```
+
 ### `beforeCreateCompiler`
 
 - 功能：在中间件函数中可以拿到创建 Webpack Compiler 的 Webpack 配置
@@ -438,7 +456,7 @@ import type { CliPlugin } from '@modern-js/core';
 export default (): CliPlugin => ({
   setup(api) {
     return {
-      modifyEntryImports({ entrypoint, exportStatement }) {
+      modifyEntryExport({ entrypoint, exportStatement }) {
         return {
           entrypoint,
           exportStatement: [`export const foo = 'test'`, exportStatement].join(
@@ -778,7 +796,7 @@ export default (): Plugin => ({
           );
         };
         return next({
-          App: hoistNonReactStatics(AppWrapper, App)
+          App: hoistNonReactStatics(AppWrapper, App),
         });
       },
     };

package/package.json

@@ -15,27 +15,27 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.20.0",
+  "version": "2.21.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.20.0"
+    "@modern-js/builder-doc": "^2.21.0"
   },
   "devDependencies": {
     "classnames": "^2",
     "clsx": "^1.2.1",
     "react": "^18",
     "react-dom": "^18",
-    "ts-node": "^10",
-    "typescript": "^4",
+    "ts-node": "^10.9.1",
+    "typescript": "^5",
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.20.0",
-    "@modern-js/doc-tools": "2.20.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.20.0"
+    "@modern-js/builder-doc": "2.21.0",
+    "@modern-js/doc-tools": "2.21.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.21.0"
   },
   "scripts": {
     "dev": "modern dev",