@modern-js/main-doc 2.36.0 → 2.37.0

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

@@ -265,7 +265,7 @@ export default function UserLayout() {
           <div>
             <span>{userInfo.name}</span>
             <span>{userInfo.age}</span>
-            <Outlet>
+            <Outlet/>
           </div>
         )}>
         </Await>
@@ -281,6 +281,55 @@ For details on how to use the Await component, please refer to [Await](https://r
 For details on how to use defer, please refer to [defer](https://reactrouter.com/en/main/guides/deferred).
 :::
 
+### Data Cache
+
+In routing navigation, Modern.js will only load the data of the changed part of the route.
+For example, the current route is `a/b`, and the Data Loader corresponding to the `a` path has been executed.
+When jumping from `/a/b` to `/a/c`, the Data Loader corresponding to `a` path will not be re-executed,
+and the Data Loader corresponding to `c` path will execute and fetch the data.
+
+It is mean that Modern.js will only load the data for the routing change portion of the data load,
+and this default optimization strategy avoids invalid duplicate data requests.
+
+You may ask, how to update the data of the `a` path corresponding to the Data Loader?
+
+In Modern.js, Modern.js will reload the data of the corresponding routing path in the following cases:
+
+1. After [Data Action](/guides/basic-features/data/data-write.md) is triggered
+2. The search params on the url have changed.
+3. The link clicked by the user is the same as the URL of the current page.
+4. The [`shouldRevalidate`](#/shouldrevalidate) function is defined in the routing component, which returns true
+
+:::info
+If you define the [`shouldRevalidate`](#/shouldrevalidate) function on the route, the function will be checked first to determine whether the data needs to be reloaded.
+:::
+
+### `shouldRevalidate`
+
+In each routing component (`layout.tsx`, `page.tsx`, `$.tsx`), we can export a `shouldRevalidate` function, which is triggered each time a route changes in the project. This function controls which routes' data are reloaded, and when it returns true, the data for the corresponding route is reloaded. data of the corresponding route will be reloaded.
+
+```ts title="routes/user/layout.tsx"
+import type { ShouldRevalidateFunction } from '@modern-js/runtime/router';
+export const shouldRevalidate: ShouldRevalidateFunction = ({
+  actionResult,
+  currentParams,
+  currentUrl,
+  defaultShouldRevalidate,
+  formAction,
+  formData,
+  formEncType,
+  formMethod,
+  nextParams,
+  nextUrl,
+}) => {
+  return true;
+};
+```
+
+:::info
+For more details about the `shouldRevalidate` function, please refer to [react-router](https://reactrouter.com/en/main/route/should-revalidate)
+:::
+
 ### Incorrect usage
 
 1. The `loader` can only return serializable data. In the SSR environment, the return value of the `loader` function will be serialized as a JSON string and then deserialized into an object on the client side. Therefore, the `loader` function cannot return non-serializable data (such as functions).

package/docs/en/tutorials/first-app/c07-container.mdx

@@ -186,10 +186,6 @@ import { Helmet } from '@modern-js/runtime/head';
 import { useModel } from '@modern-js/runtime/model';
 import { List } from 'antd';
 import Item from '../components/Item';
-import { Helmet } from '@modern-js/runtime/head';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import Item from '../components/Item';
 import contacts from '../models/contacts';
 
 function Contacts({

package/docs/en/tutorials/first-app/c08-entries.mdx

@@ -125,7 +125,7 @@ export default defineConfig({
       'landing-page': process.env.NODE_ENV !== 'production',
     },
   },
-};
+});
 ```
 
 So far, the prototype of our point of contact list application is almost complete 👏👏👏.

package/docs/zh/guides/basic-features/data/{data-fetch.md → data-fetch.mdx}

@@ -219,6 +219,7 @@ export function UserLayout() {
 
 如果想获取 `entry1/routes/layout.tsx` 中 `loader` 返回的数据，`routeId` 的值就是 `entry1_layout`。
 
+
 ### (WIP)Loading UI
 
 :::info
@@ -277,7 +278,50 @@ defer 的具体用法请查看 [defer](https://reactrouter.com/en/main/guides/de
 
 :::
 
-{/* TODO 缓存相关 */}
+### 数据缓存
+
+在路由导航时，Modern.js 只会加载路由变化的部分的数据，如当前路由是 `a/b`，`a` 路径对应的 Data Loader 已经执行过，当从 `/a/b` 跳转到 `/a/c`时，`a` 路径对应的 Data Loader 不会重新执行，`c` 路径对应的 Data Loader 会执行，并获取了数据。
+
+即 Modern.js 在数据加载时，只会加载路由变化部分的数据，这种默认的优化策略避免了无效重复数据的请求。
+
+你可能会问，如何更新 `a` 路径对应 Data Loader 的数据？
+
+在 Modern.js 中，以下几种情况，Modern.js 会重新加载对应路由路径的数据：
+
+1. 在 [Data Action](/guides/basic-features/data/data-write.md) 触发后
+2. URL 上搜索参数发生了变化
+3. 用户点击的链接与当前页面的 URL 相同
+4. 在路由组件中定义了 [`shouldRevalidate`](#/shouldrevalidate) 函数，该函数返回 true
+
+:::info
+如果你在路由上定义了 [`shouldRevalidate`](#/shouldrevalidate) 函数，会先检查该函数，判断是否需要重新加载数据。
+:::
+
+### `shouldRevalidate`
+
+在每个路由组件(`layout.tsx`，`page.tsx`, `$.tsx`)中，我们可以导出一个 `shouldRevalidate` 函数，在每次项目中的路由变化时，这个函数会触发，该函数可以控制要重新加载哪些路由中的数据，当这个函数返回 true， 对应路由的数据就会重新加载。
+
+```ts title="routes/user/layout.tsx"
+import type { ShouldRevalidateFunction } from '@modern-js/runtime/router';
+export const shouldRevalidate: ShouldRevalidateFunction = ({
+  actionResult,
+  currentParams,
+  currentUrl,
+  defaultShouldRevalidate,
+  formAction,
+  formData,
+  formEncType,
+  formMethod,
+  nextParams,
+  nextUrl,
+}) => {
+  return true;
+};
+```
+
+:::info
+`shouldRevalidate` 函数的更多信息可以参考 [react-router](https://reactrouter.com/en/main/route/should-revalidate)
+:::
 
 ### 错误用法
 

package/docs/zh/tutorials/first-app/c07-container.mdx

@@ -186,10 +186,6 @@ import { Helmet } from '@modern-js/runtime/head';
 import { useModel } from '@modern-js/runtime/model';
 import { List } from 'antd';
 import Item from '../components/Item';
-import { Helmet } from '@modern-js/runtime/head';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import Item from '../components/Item';
 import contacts from '../models/contacts';
 
 function Contacts({

package/docs/zh/tutorials/first-app/c08-entries.mdx

@@ -125,7 +125,7 @@ export default defineConfig({
       'landing-page': process.env.NODE_ENV !== 'production',
     },
   },
-};
+});
 ```
 
 到底为止，我们的联系人列表应用的雏形就基本完成了 👏👏👏。

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.36.0",
+  "version": "2.37.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.36.0"
+    "@modern-js/sandpack-react": "2.37.0"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.36.0"
+    "@modern-js/builder-doc": "^2.37.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -35,12 +35,12 @@
     "ts-node": "^10.9.1",
     "typescript": "^5",
     "fs-extra": "^10",
-    "rspress": "1.0.0-beta.3",
-    "@rspress/shared": "1.0.0-beta.3",
+    "rspress": "1.0.2",
+    "@rspress/shared": "1.0.2",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.36.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.36.0"
+    "@modern-js/builder-doc": "2.37.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.37.0"
   },
   "scripts": {
     "dev": "rspress dev",