@modern-js/main-doc 2.67.2 → 2.67.4

package/docs/en/apis/app/hooks/src/routes.mdx

@@ -88,3 +88,73 @@ export default () => {
 `<Outlet>` is a new API in React Router 6. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::
+
+## Upgrading to React Router v7
+
+React Router v7 reduces bundle size (approximately 15% smaller) compared to React Router v6, provides a more efficient route matching algorithm, and offers better support for React 19 and TypeScript. There are very few breaking changes compared to React Router v6, and Modern.js has made both versions compatible, allowing for a seamless upgrade by simply installing and registering the appropriate plugin.
+
+:::info
+
+For more changes from React Router v6 to React Router v7, check the [documentation](https://reactrouter.com/upgrading/v6#upgrade-to-v7)
+
+:::
+
+### Requirements
+
+React Router v7 has certain environment requirements:
+
+- Node.js 20+
+- React 18+
+- React DOM 18+
+
+### Install the Plugin
+
+First, install the Modern.js React Router v7 plugin:
+
+```bash
+pnpm add @modern-js/plugin-router-v7
+```
+
+### Configure the Plugin
+
+Register the plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { routerPlugin } from '@modern-js/plugin-router-v7';
+
+export default {
+  runtime: {
+    router: true,
+  },
+  plugins: [routerPlugin()],
+};
+```
+
+### Code Changes
+
+In React Router v7, you no longer need to use the `defer` API; you can directly return data in the data loader:
+
+```ts title="routes/page.data.ts"
+import { defer } from '@modern-js/runtime/router';
+
+export const loader = async ({ params }) => {
+  // Recommended v7 style
+  const user = fetchUser(params.id)
+  return { user };
+
+  // v6 style, still compatible with Modern.js
+  return defer({ data: 'hello' });
+};
+```
+
+React Router v7 has also deprecated the `json` API:
+
+```ts title="routes/page.data.ts"
+export const loader = async ({ params }) => {
+  // Recommended v7 style
+  return { data: 'hello' };
+
+  // v6 style, still compatible with Modern.js
+  return json({ data: 'hello' });
+};
+```

package/docs/en/configure/app/output/filename.mdx

@@ -3,13 +3,20 @@ title: filename
 configName: output.filename
 ---
 
+:::warning
+
+In Modern.js `dev` command or use Modern.js server deployment, don't modify the html output filename. This will cause the page to be 404.
+
+In common, you don't need to modify the html filename. If you want modify `main.html` to `index.html`, using [source.mainEntryName](/configure/app/source/main-entry-name).
+
+:::
+
 # output.filename
 
 - **Type:**
 
 ```ts
 type FilenameConfig = {
-  html?: string;
   js?:
     | string
     | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
@@ -27,7 +34,6 @@ type FilenameConfig = {
 ```js
 // Development mode
 const devDefaultFilename = {
-  html: '[name].html',
   js: '[name].js',
   css: '[name].css',
   svg: '[name].[contenthash:8].svg',
@@ -39,7 +45,6 @@ const devDefaultFilename = {
 
 // Production mode
 const prodDefaultFilename = {
-  html: '[name].html',
   js: output.target === 'node' ? '[name].js' : '[name].[contenthash:8].js',
   css: '[name].[contenthash:8].css',
   svg: '[name].[contenthash:8].svg',

package/docs/en/configure/app/runtime/0-intro.mdx

@@ -2,12 +2,20 @@
 
 Modern.js runtime configuration should be centralized in the `src/modern.runtime.ts` file.
 
+:::warning
+
+Using the `src/modern.runtime.ts` configuration approach requires Modern.js version **MAJOR_VERSION.66.0** or higher.
+
+:::
+
 :::info
+
 If this file doesn't exist in your project yet, create it with the following command:
 
 ```bash
 touch src/modern.runtime.ts
 ```
+
 :::
 
 ## Basic Configuration
@@ -33,7 +41,7 @@ For multi-entry applications, `defineRuntimeConfig` can accept a function that r
 ```tsx
 import { defineRuntimeConfig } from '@modern-js/runtime';
 
-export default defineRuntimeConfig((entryName) => {
+export default defineRuntimeConfig(entryName => {
   if (entryName === 'main') {
     return {
       router: {
@@ -53,12 +61,11 @@ export default defineRuntimeConfig((entryName) => {
   };
 });
 ```
+
 :::tip
+
 Using the `src/modern.runtime.ts` configuration approach does not support exporting asynchronous functions, which is related to the rendering method of Modern.js. If you need to add asynchronous logic, please use the **[Runtime Plugin](/plugin/introduction.html#runtime-plugin)**.
-:::
 
-:::warning
-Using the `src/modern.runtime.ts` configuration approach requires Modern.js version **MAJOR_VERSION.66.0** or higher.
 :::
 
 import RuntimeCliConfig from '@site-docs/components/runtime-cli-config';
@@ -79,15 +86,23 @@ To improve maintainability, Modern.js introduced the unified `src/modern.runtime
 ```ts
 // modern.config.ts
 export default {
-  runtime: { /* ... */ },
-  runtimeByEntries: { /* ... */ },
+  runtime: {
+    /* ... */
+  },
+  runtimeByEntries: {
+    /* ... */
+  },
 };
 
 // App.config
-App.config = {/* ... */}
+App.config = {
+  /* ... */
+};
 
 // layout file
-export const config = () => { /* Dynamic configuration logic */ };
+export const config = () => {
+  /* Dynamic configuration logic */
+};
 ```
 
 ### Migration Recommendation

package/docs/en/configure/app/usage.mdx

@@ -13,10 +13,8 @@ Modern.js does not support configuring the same configuration item in both `pack
 
 **Runtime configuration** can be configured in the `src/modern.runtime.(ts|js|mjs)` file.
 
-{/* TODO server 配置文件更新 */}
 **Server Runtime configuration** can be configured in the `modern.server-runtime.config.(ts|js|mjs)` file in the root path.
 
-
 ## Compile Configuration
 
 ### Configuring in Configuration Files

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

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # Data Caching
 
-The `cache` function allows you to cache the results of data fetching or computation.
+The `cache` function allows you to cache the results of data fetching or computation, Compared to full-page [rendering cache](/guides/basic-features/render/ssr-cache), it provides more fine-grained control over data granularity and is applicable to various scenarios such as Client-Side Rendering (CSR), Server-Side Rendering (SSR), and API services (BFF).
 
 :::info
 X.65.5 and above versions are required
@@ -12,6 +12,15 @@ X.65.5 and above versions are required
 
 ## Basic Usage
 
+:::note
+
+If you use the `cache` function in BFF, you should import the cache funtion from `@modern-js/server-runtime/cache`
+
+`import { cache } from '@modern-js/server-runtime/cache'`
+
+:::
+
+
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -34,6 +43,8 @@ const loader = async () => {
   - `tag`: Tag to identify the cache, which can be used to invalidate the cache
   - `maxAge`: Cache validity period (milliseconds)
   - `revalidate`: Time window for revalidating the cache (milliseconds), similar to HTTP Cache-Control's stale-while-revalidate functionality
+  - `getKey`: Simplified cache key generation function based on function parameters
+  - `customKey`: Custom cache key function
 
 The type of the `options` parameter is as follows:
 
@@ -42,6 +53,12 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
+  customKey?: <Args extends any[]>(options: {
+    params: Args;
+    fn: (...args: Args) => any;
+    generatedKey: string;
+  }) => string | symbol;
 }
 ```
 
@@ -153,6 +170,204 @@ revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboard
 ```
 
 
+#### `getKey` Parameter
+
+The `getKey` parameter simplifies cache key generation, especially useful when you only need to rely on part of the function parameters to differentiate caches. It's a function that receives the same parameters as the original function and returns a string or number as the cache key:
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    // Here options might contain many configurations, but we only want to cache based on userId
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Only use the first parameter (userId) as the cache key
+    getKey: (userId, options) => userId,
+  }
+);
+
+// The following two calls will share the cache because getKey only uses userId
+await getUser(123, { language: 'en' });
+await getUser(123, { language: 'fr' }); // Cache hit, won't request again
+
+// Different userId will use different cache
+await getUser(456, { language: 'en' }); // Won't hit cache, will request again
+```
+
+You can also use Modern.js's `generateKey` function together with getKey to generate the cache key:
+
+:::info
+
+The `generateKey` function in Modern.js ensures that a consistent and unique key is generated even if object property orders change, guaranteeing stable caching.
+
+:::
+
+```ts
+import { cache, CacheTime, generateKey } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    getKey: (userId, options) => generateKey(userId),
+  }
+);
+```
+
+Additionally, `getKey` can also return a numeric type as a cache key:
+
+```ts
+const getUserById = cache(
+  fetchUserDataById,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Directly use the numeric ID as the cache key
+    getKey: (id) => id,
+  }
+);
+
+await getUserById(42); // Uses 42 as the cache key
+```
+
+#### `customKey` parameter
+
+The `customKey` parameter is used to customize the cache key. It is a function that receives an object with the following properties and returns a string or Symbol type as the cache key:
+
+- `params`: Array of arguments passed to the cached function
+- `fn`: Reference to the original function being cached
+- `generatedKey`: Cache key automatically generated by the framework based on input parameters
+
+:::info
+
+Generally, the cache will be invalidated in the following scenarios:
+1. The referenced cached function changes
+2. The function's input parameters change
+3. The maxAge condition is no longer satisfied
+4. The `revalidateTag` method has been called
+
+`customKey` can be used in scenarios where function references are different but shared caching is desired. If it's just for customizing the cache key, it is recommended to use `getKey`.
+
+:::
+
+This is very useful in some scenarios, such as when the function reference changes , but you want to still return the cached data.
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+// Different function references, but share the same cache via customKey
+const getUserA = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // Return a stable string as the cache key
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// Even if the function reference changes,
+// as long as customKey returns the same value, the cache will be hit
+const getUserB = cache(
+  (...args) => fetchUserData(...args), // New function reference
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // Return the same key as getUserA
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// You can also use Symbol as a cache key (usually used to share cache within the same application)
+const USER_CACHE_KEY = Symbol('user-cache');
+const getUserC = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: () => USER_CACHE_KEY,
+  }
+);
+
+// You can utilize the generatedKey parameter to modify the default key
+const getUserD = cache(
+  fetchUserData,
+  {
+    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+  }
+);
+```
+
+#### `onCache` Parameter
+
+The `onCache` parameter allows you to track cache statistics such as hit rate. It's a callback function that receives information about each cache operation, including the status, key, parameters, and result.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+// Track cache statistics
+const stats = {
+  total: 0,
+  hits: 0,
+  misses: 0,
+  stales: 0,
+  hitRate: () => stats.hits / stats.total
+};
+
+const getUser = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    onCache({ status, key, params, result }) {
+      // status can be 'hit', 'miss', or 'stale'
+      stats.total++;
+
+      if (status === 'hit') {
+        stats.hits++;
+      } else if (status === 'miss') {
+        stats.misses++;
+      } else if (status === 'stale') {
+        stats.stales++;
+      }
+
+      console.log(`Cache ${status} for key: ${String(key)}`);
+      console.log(`Current hit rate: ${stats.hitRate() * 100}%`);
+    }
+  }
+);
+
+// Usage example
+await getUser(1); // Cache miss
+await getUser(1); // Cache hit
+await getUser(2); // Cache miss
+```
+
+The `onCache` callback receives an object with the following properties:
+
+- `status`: The cache operation status, which can be:
+  - `hit`: Cache hit, returning cached content
+  - `miss`: Cache miss, executing the function and caching the result
+  - `stale`: Cache hit but data is stale, returning cached content while revalidating in the background
+- `key`: The cache key, which is either the result of `customKey` or the default generated key
+- `params`: The parameters passed to the cached function
+- `result`: The result data (either from cache or newly computed)
+
+This callback is only invoked when the `options` parameter is provided. When using the cache function without options, the `onCache` callback is not called.
+
+The `onCache` callback is useful for:
+- Monitoring cache performance
+- Calculating hit rates
+- Logging cache operations
+- Implementing custom metrics
+
 ### Storage
 
 Currently, both client and server caches are stored in memory.

package/docs/en/guides/basic-features/deploy.mdx

@@ -6,7 +6,7 @@ sidebar_position: 15
 
 Currently, Modern.js offers two deployment way:
 - You can host your application in a container that includes a Node.js environment on your own, which provides flexibility for the deployment of the application.
-- You can also deploy your application through a platform. Currently, Modern.js supports the [Netlify](https://www.netlify.com/) and [Vercel](https://vercel.com/).
+- You can also deploy your application through a platform. Currently, Modern.js officially supports deployment on [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/), and [Github pages](https://pages.github.com/).
 
 :::info
 Currently, Modern.js only supports running in a Node.js environment. Support for more runtime environments will be provided in the future.
@@ -110,6 +110,11 @@ Add the following content to `netlify.toml`:
   command = "modern deploy"
 ```
 
+:::info
+You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+
+:::
+
 Now, add a project to the Netlify platform and deploy it!
 
 ### Full Stack Project
@@ -129,14 +134,16 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 ```
 
 :::info
-Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
+1. Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
+2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+
 :::
 
 
 ### Monorepo
 
 :::info
-The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#Pure Frontend Project) to deploy.
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#pure-front-end-project-1) to deploy.
 :::
 
 For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
@@ -213,6 +220,11 @@ Commit your project to git, select Framework Preset as `Other` on the Vercel pla
 
 <img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
 
+:::info
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+
+:::
+
 ### Full Stack Project
 
 Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. These projects need to be deployed on **Vercel Functions**.
@@ -220,14 +232,12 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 In addition to configuring `vercel.json` in the same way as a [pure front-end project](#pure-front-end-project), there are two points to note for full-stack projects:
 
 1. Currently, Modern.js does not support deploying BFF projects on the Vercel platform. We will support it in future versions.
-2. When deploying on Vercel platform, the default node runtime is `20.x`, it is recommended to choose `18.x` when deploying full-stack projects,
-see [Serverless Function contains invalid runtime error](https://vercel.com/guides/serverless-function-contains-invalid-runtime-error), you can modify `package.json` to specify the version:
-```json title="package.json"
-"engines": {
-  "node": "18.x"
-}
-```
+2. The Node.js version for function execution is determined by the project configuration on the Vercel platform.
 
+:::info
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+
+:::
 
 ### Monorepo
 
@@ -284,6 +294,49 @@ Add the following content to the `packages/app/vercel.json` file:
 
 Just submit your code and deploy it using the Vercel platform.
 
+## Github Pages
+
+If you're creating a GitHub Pages for a repository without a custom domain, the page URL will follow this format: `http://<username>.github.io/<repository-name>`. Therefore, you need to add the following configuration in `modern.config.ts`:
+
+```
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  //...
+  server: {
+    baseUrl: "/<repository-name>"
+  },
+  output: {
+    assetPrefix: "/<repository-name>",
+  }
+});
+```
+
+GitHub Pages supports two deployment ways: branch deployment or GitHub Actions deployment.
+
+For branch deployment, follow these steps:
+
+1. In the GitHub repository, navigate to Settings > Pages > Source > Deploy from a branch
+2. Install the `gh-pages` as devDependency
+3. Add the following script to `package.json`
+```
+"scripts": {
+  //...
+  "deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"
+}
+```
+
+4. Run `npm run deploy:gh-pages`
+
+:::info
+1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
+2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
+
+:::
+
+For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+
+
 ## Using Self-Built Node.js Server
 
 Typically, we recommend using the built-in Node.js server of Modern.js to deploy applications. It supports hosting both pure frontend and full-stack projects, ensuring consistent performance in both development and production environments.

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

@@ -7,7 +7,9 @@ sidebar_position: 2
 Modern.js routing is based on [React Router 6](https://reactrouter.com/en/main), offering file convention-based routing capabilities and supporting the industry-popular **nested routing** pattern. When an entry is recognized as [conventional routing](/guides/concept/entries.html#conventional-routing), Modern.js automatically generates the corresponding routing structure based on the file system.
 
 :::note
+
 The routing mentioned in this section all refers to conventional routing.
+
 :::
 
 ## What is Nested Routing
@@ -38,7 +40,9 @@ In the `routes/` directory, subdirectory names are mapped to route URLs. Modern.
 - `layout.tsx`: This is the layout component and controls the layout of all sub-routes in its directory by using `<Outlet>` to represent child components.
 
 :::tip
+
 `.ts`, `.js`, `.jsx`, or `.tsx` file extensions can be used for the above convention files.
+
 :::
 
 ### Page
@@ -83,7 +87,9 @@ export default () => {
 ```
 
 :::note
+
 `<Outlet>` is an API provided by React Router 6. For more details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
 :::
 
 Under different directory structures, the components represented by `<Outlet>` are also different. To illustrate the relationship between `<Layout>` and `<Outlet>`, let's consider the following directory structure:
@@ -219,7 +225,7 @@ When you visit `/blog/a` and no routes match, the page will render the `routes/b
 </RootLayout>
 ```
 
-If you want `/blog` to match the `blog/$.tsx` file as well, you need to remove the `blog.tsx` file from the same directory and ensure there are no other sub-routes under `blog`.
+If you want `/blog` to match the `blog/$.tsx` file as well, you need to remove the `blog/layout.tsx` file from the same directory and ensure there are no other sub-routes under `blog`.
 
 Similarly, you can use [useParams](/apis/app/runtime/router/router#useparams) to capture the remaining part of the URL in the `$.tsx` component.
 
@@ -480,6 +486,8 @@ The `prefetch` attribute has three optional values:
 
 :::
 
+import Motivation from '@site-docs-en/components/convention-routing-motivation';
+
 <Motivation />
 
 ## FAQ
@@ -496,4 +504,34 @@ Additionally, when using conventional routing, make sure to use the API from `@m
 If you must directly use the React Router package's API (e.g., route behavior wrapped in a unified npm package), you can set [`source.alias`](/configure/app/source/alias) to point `react-router` and `react-router-dom` to the project's dependencies, avoiding the issue of two versions of React Router.
 :::
 
-import Motivation from '@site-docs-en/components/convention-routing-motivation';
+2. About `config` function and `init` function
+
+:::warning Not Recommended
+
+Modern.js early versions supported runtime configuration and initialization operations through `config` function and `init` function exported in route layout files. These methods are still **supported**, but we **strongly recommend** using the [Runtime Configuration File](/configure/app/runtime/0-intro) and [Runtime Plugin](/plugin/introduction.html#runtime-plugin) to implement the corresponding functions.
+
+:::
+
+**config**
+
+In route components, you can add dynamic Runtime configuration by exporting a `config` function:
+
+```tsx
+// routes/layout.tsx
+export const config = () => {
+  return {
+    // dynamic Runtime configuration
+  };
+};
+```
+
+**init**
+
+In route components, you can execute pre-rendering logic by exporting an `init` function:
+
+```tsx
+// routes/layout.tsx
+export const init = () => {
+  // initialization logic
+};
+```

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

@@ -148,7 +148,7 @@ info    Starting production server...
   > Network:  http://192.168.0.1:8080/
 ```
 
-Open `http://localhost:8000/` in the browser, and the content should be consistent with that of `pnpm run dev`.
+Open `http://localhost:8080/` in the browser, and the content should be consistent with that of `pnpm run dev`.
 
 ## Deployment
 

package/docs/zh/configure/app/output/filename.mdx

@@ -3,6 +3,14 @@ title: filename
 configName: output.filename
 ---
 
+:::warning
+
+在 Modern.js 开发阶段，或是使用 Modern.js 服务器部署应用时，应避免使用该配置修改 html 产物文件名，会导致页面 404。
+
+通常情况下，无需修改 html 产物文件名。常见的需求是将 `main.html` 修改为 `index.html`，请使用 [source.mainEntryName](/configure/app/source/main-entry-name)。
+
+:::
+
 # output.filename
 
 - **类型：**

package/docs/zh/configure/app/runtime/0-intro.mdx

@@ -2,6 +2,12 @@
 
 Modern.js 的运行时（Runtime）配置需集中在 `src/modern.runtime.ts` 文件中声明。
 
+:::warning
+
+使用 `src/modern.runtime.ts` 配置方式需要 Modern.js 版本 **MAJOR_VERSION.66.0** 或更高版本。
+
+:::
+
 :::info
 如果项目中还没有此文件，请执行以下命令创建：
 
@@ -59,9 +65,7 @@ export default defineRuntimeConfig(entryName => {
 使用 `src/modern.runtime.ts` 配置方式不支持导出异步函数，这与 Modern.js 的渲染方式有关。如果需要添加异步逻辑，请使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)**。
 :::
 
-:::warning
-使用 `src/modern.runtime.ts` 配置方式需要 Modern.js 版本 **MAJOR_VERSION.66.0** 或更高版本。
-:::
+
 
 import RuntimeCliConfig from '@site-docs/components/runtime-cli-config';
 

package/docs/zh/configure/app/usage.mdx

@@ -13,7 +13,6 @@ Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置
 
 **运行时配置**可以在 `src/modern.runtime.(ts|js|mjs)` 文件中配置。
 
-{/* TODO server 配置文件更新 */}
 **服务端运行时配置**可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
 
 ## 编译时配置

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

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # 数据缓存
 
-`cache` 函数可以让你缓存数据获取或计算的结果。
+`cache` 函数可以让你缓存数据获取或计算的结果，相比整页[渲染缓存](/guides/basic-features/render/ssr-cache)，它提供了更精细的数据粒度控制，并且适用于客户端渲染(CSR)、服务端渲染（SSR）、API 服务(BFF)等多种场景。
 
 :::info
 需要 x.65.5 及以上版本
@@ -12,6 +12,14 @@ sidebar_position: 4
 
 ## 基本用法
 
+:::note
+
+如果在 BFF 中使用 `cache` 函数，应该从 `@modern-js/server-runtime/cache` 导入相关函数
+
+`import { cache } from '@modern-js/server-runtime/cache'`
+
+:::
+
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -33,6 +41,8 @@ const loader = async () => {
   - `tag`: 用于标识缓存的标签，可以基于这个标签使缓存失效
   - `maxAge`: 缓存的有效期 (毫秒)
   - `revalidate`: 重新验证缓存的时间窗口（毫秒），与 HTTP Cache-Control 的 stale-while-revalidate 功能一致
+  - `getKey`: 简化的缓存键生成函数，根据函数参数生成缓存键
+  - `customKey`: 自定义缓存键生成函数，用于在函数引用变化时保持缓存
 
 `options` 参数的类型如下：
 
@@ -41,6 +51,12 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
+  customKey?: <Args extends any[]>(options: {
+    params: Args;
+    fn: (...args: Args) => any;
+    generatedKey: string;
+  }) => string | symbol;
 }
 ```
 
@@ -146,6 +162,193 @@ const getComplexStatistics = cache(
 revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
 ```
 
+#### `getKey` 参数
+
+`getKey` 参数用于自定义缓存键的生成方式，例如你可能只需要依赖函数参数的一部分来区分缓存。它是一个函数，接收与原始函数相同的参数，返回一个字符串作为缓存键：
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    // 这里 options 可能包含很多配置，但我们只想根据 userId 缓存
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // 只使用第一个参数（userId）作为缓存键
+    getKey: (userId, options) => userId,
+  }
+);
+
+// 下面两次调用会共享缓存，因为 getKey 只使用了 userId
+await getUser(123, { language: 'zh' });
+await getUser(123, { language: 'en' }); // 命中缓存，不会重新请求
+
+// 不同的 userId 会使用不同的缓存
+await getUser(456, { language: 'zh' }); // 不会命中缓存，会重新请求
+```
+
+你也可以使用 Modern.js 提供的 `generateKey` 函数配合 getKey 生成缓存的键：
+
+:::info
+
+Modern.js 中的 `generateKey` 函数确保即使对象属性顺序发生变化，也能生成一致的唯一键值，保证稳定的缓存
+
+:::
+
+```ts
+import { cache, CacheTime, generateKey } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    getKey: (userId, options) => generateKey(userId),
+  }
+);
+```
+
+
+#### `customKey` 参数
+
+`customKey` 参数用于定制缓存的键，它是一个函数，接收一个包含以下属性的对象，返回值必须是字符串或 Symbol 类型，将作为缓存的键：
+
+- `params`：调用缓存函数时传入的参数数组
+- `fn`：原始被缓存的函数引用
+- `generatedKey`：框架基于入参自动生成的原始缓存键
+
+:::info
+
+一般在以下场景，缓存会失效：
+1. 缓存的函数引用发生变化
+2. 函数的入参发生变化
+3. 不满足 maxAge
+4. 调用了 `revalidateTag`
+
+`customKey` 可以用在函数引用不同，但希望共享缓存的场景，如果只是自定义缓存键，推荐使用 `getKey`
+
+:::
+
+这在某些场景下非常有用，比如当函数引用发生变化时，但你希望仍然返回缓存的数据。
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+// 不同的函数引用，但是通过 customKey 可以使它们共享一个缓存
+const getUserA = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // 返回一个稳定的字符串作为缓存的键
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// 即使函数引用变了，只要 customKey 返回相同的值，也会命中缓存
+const getUserB = cache(
+  (...args) => fetchUserData(...args), // 新的函数引用
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => {
+      // 返回与 getUserA 相同的键
+      return `user-${params[0]}`;
+    },
+  }
+);
+
+// 即使 getUserA 和 getUserB 是不同的函数引用，但由于它们的 customKey 返回相同的值
+// 所以当调用参数相同时，它们会共享缓存
+const dataA = await getUserA(1);
+const dataB = await getUserB(1); // 这里会命中缓存，不会再次发起请求
+
+// 也可以使用 Symbol 作为缓存键（通常用于共享同一个应用内的缓存）
+const USER_CACHE_KEY = Symbol('user-cache');
+const getUserC = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: () => USER_CACHE_KEY,
+  }
+);
+
+// 可以利用 generatedKey 参数在默认键的基础上进行修改
+const getUserD = cache(
+  fetchUserData,
+  {
+    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+  }
+);
+```
+
+#### `onCache` 参数
+
+`onCache` 参数允许你跟踪缓存统计信息，例如命中率。这是一个回调函数，接收有关每次缓存操作的信息，包括状态、键、参数和结果。
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+// 跟踪缓存统计
+const stats = {
+  total: 0,
+  hits: 0,
+  misses: 0,
+  stales: 0,
+  hitRate: () => stats.hits / stats.total
+};
+
+const getUser = cache(
+  fetchUserData,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    onCache({ status, key, params, result }) {
+      // status 可以是 'hit'、'miss' 或 'stale'
+      stats.total++;
+
+      if (status === 'hit') {
+        stats.hits++;
+      } else if (status === 'miss') {
+        stats.misses++;
+      } else if (status === 'stale') {
+        stats.stales++;
+      }
+
+      console.log(`缓存${status === 'hit' ? '命中' : status === 'miss' ? '未命中' : '陈旧'}，键：${String(key)}`);
+      console.log(`当前命中率：${stats.hitRate() * 100}%`);
+    }
+  }
+);
+
+// 使用示例
+await getUser(1); // 缓存未命中
+await getUser(1); // 缓存命中
+await getUser(2); // 缓存未命中
+```
+
+`onCache` 回调接收一个包含以下属性的对象：
+
+- `status`: 缓存操作状态，可以是：
+  - `hit`: 缓存命中，返回缓存内容
+  - `miss`: 缓存未命中，执行函数并缓存结果
+  - `stale`: 缓存命中但数据陈旧，返回缓存内容同时在后台重新验证
+- `key`: 缓存键，可能是 `customKey` 的结果或默认生成的键
+- `params`: 传递给缓存函数的参数
+- `result`: 结果数据（来自缓存或新计算的）
+
+这个回调只在提供 `options` 参数时被调用。当使用无 options 的缓存函数时，不会调用 `onCache` 回调。
+
+`onCache` 回调对以下场景非常有用：
+- 监控缓存性能
+- 计算命中率
+- 记录缓存操作
+- 实现自定义指标
 
 ### 存储
 
@@ -164,3 +367,4 @@ configureCache({
   maxSize: CacheSize.MB * 10, // 10MB
 });
 ```
+

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

@@ -7,7 +7,7 @@ sidebar_position: 15
 目前，Modern.js 提供了两种部署方式：
 
 - 你可以将应用自行托管在包含 Node.js 环境的容器中，这为应用提供了部署的灵活性。
-- 你也可以通过平台部署应用，目前 Modern.js 官方支持了 [Netlify](https://www.netlify.com/) 和 [Vercel](https://vercel.com/) 平台。
+- 你也可以通过平台部署应用，目前 Modern.js 官方支持了 [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/) 和 [Github pages](https://pages.github.com/) 平台。
 
 :::info
 目前 Modern.js 仅支持在 Node.js 环境中运行，未来将提供更多运行时环境的支持。
@@ -26,6 +26,7 @@ MODERNJS_DEPLOY=netlify npx modern deploy
 在 Modern.js 官方支持的部署平台中部署时，无需指定环境变量。
 :::
 
+
 ## ModernJS 内置 Node.js 服务器
 
 ### 单仓库项目
@@ -107,6 +108,11 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
   command = "modern deploy"
 ```
 
+:::info
+你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+
+:::
+
 在 Netlify 平台上添加项目，部署即可。
 
 ### 全栈项目
@@ -126,10 +132,14 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```
 
 :::info
-目前 Modern.js 还不支持在 Netlify Edge Functions 进行部署，我们将在后续的版本中支持。
+1. 目前 Modern.js 还不支持在 Netlify Edge Functions 进行部署，我们将在后续的版本中支持。
+2. 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr)。
+
 :::
 
 
+
+
 ### Monorepo 项目
 
 :::info
@@ -207,6 +217,11 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 <img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
 
+:::info
+你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+
+:::
+
 ### 全栈项目
 
 全栈项目是指使用了自定义 Web Server、SSR、BFF 的项目，这些项目需要部署在 **Vercel Functions** 上。
@@ -214,12 +229,13 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 全栈项目除了按照[纯前端项目](#纯前端项目)的方式配置 `vercel.json` 外，有两点需要注意：
 
 1. 当前，Modern.js 还不支持在 Vercel 平台上部署 BFF 项目，我们将在后续的版本中支持。
-2. Vercel 平台部署时，默认 node 运行时为 `20.x`，部署全栈项目时建议选择 `18.x`，具体原因详见[Serverless Function contains invalid runtime error](https://vercel.com/guides/serverless-function-contains-invalid-runtime-error)，你可以修改 `package.json` 指定版本：
-```json title="package.json"
-"engines": {
-  "node": "18.x"
-}
-```
+2. 函数运行的 node.js 版本由项目在 Vercel 平台配置决定。
+
+
+:::info
+你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr)。
+
+:::
 
 ### Monorepo 项目
 
@@ -273,6 +289,38 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 提交你的代码，使用 Vercel 平台部署即可。
 
+## Github Pages
+
+如果你要为一个仓库常见 Github 页面，并且你没有自定义域名，则该页面的 URL 将会是以下格式：`http://<username>.github.io/<repository-name>`，所以需要在 `modern.config.ts` 中添加
+以下配置：
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  //...
+  server:{
+    baseUrl: "/<repository-name>"
+  },
+  output: {
+    assetPrefix: "/<repository-name>",
+  }
+});
+```
+
+Github Pages 支持两种部署方式，通过分支部署或通过 Github Actions 部署，如果通过分支部署，可以使用以下步骤：
+1. 在 github 仓库中，选择 `Settings > Pages > Source > Deploy from a branch`。
+2. 安装 `gh-pages` 依赖作为开发依赖。
+3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"`。
+4. 执行 `npm run deploy:gh-pages`。
+
+:::info
+1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，Modern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
+2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+
+:::
+
+如果通过 Github Actions 部署，可以选择 Settings > Pages > Source > GitHub Actions，并在项目中添加 workflow 文件，可参考[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+
 
 ## 自建 Node.js 服务器
 

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

@@ -7,7 +7,9 @@ sidebar_position: 2
 Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，提供了基于文件约定的路由能力，并支持了业界流行的约定式路由模式：**嵌套路由**。当入口被识别为 [约定式路由](/guides/concept/entries.html#约定式路由) 时，Modern.js 会自动基于文件系统，生成对应的路由结构。
 
 :::note
+
 本小节提到的路由，都是约定式路由。
+
 :::
 
 ## 什么是嵌套路由
@@ -84,7 +86,9 @@ export default () => {
 ```
 
 :::note
+
 `<Outlet>` 是 React Router 6 中提供的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet)。
+
 :::
 
 不同目录结构下，`<Outlet>` 所代表的组件也不同。为了方便介绍 `<Layout>` 与 `<Outlet>` 的关系，以下面的文件目录举例：
@@ -192,11 +196,15 @@ export default Blog;
 如果在某个子目录下存在 `$.tsx` 文件，该文件会作为通配路由组件，当没有匹配的路由时，会渲染该路由组件。
 
 :::note
+
 `$.tsx` 可以认为是一种特殊的 `<Page>` 组件，如果路由无法匹配，则 `$.tsx` 会作为 `<Layout>` 的子组件渲染。
+
 :::
 
 :::warning
+
 如果当前目录下不存在 `<Layout>` 组件时，则 `$.tsx` 不会生效。
+
 :::
 
 例如以下目录结构：
@@ -487,6 +495,78 @@ 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 ?
@@ -498,7 +578,39 @@ import Motivation from '@site-docs/components/convention-routing-motivation';
 在使用约定式路由的情况下，务必使用 `@modern-js/runtime/router` 中的 API，不直接使用 React Router 的 API。因为 Modern.js 内部会安装 React Router，如果应用中使用了 React Router 的 API，可能会导致两个版本的 React Router 同时存在，出现不符合预期的行为。
 
 :::note
+
 如果应用中必须直接使用 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/package.json

@@ -15,20 +15,20 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.67.2",
+  "version": "2.67.4",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.67.2"
+    "@modern-js/sandpack-react": "2.67.4"
   },
   "devDependencies": {
     "@rspress/shared": "1.43.11",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
-    "classnames": "^2",
+    "classnames": "^2.5.1",
     "clsx": "^1.2.1",
     "fs-extra": "^10",
     "react": "^18.3.1",