@modern-js/main-doc 2.67.2 → 2.67.3

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/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,7 +134,8 @@ 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).
 :::
 
 
@@ -213,6 +219,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 +231,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 +293,48 @@ 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/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/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` 不会生效。
+
 :::
 
 例如以下目录结构：
@@ -498,7 +506,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.3",
   "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.3"
   },
   "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",