@modern-js/main-doc 2.17.1 → 2.17.2-alpha.1

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

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # index.[tj]s
 
-Entry identifier if App want use custom entry. In most case, [`App.[tj]sx`](/apis/app/hooks/src/app) hook file can already meet our needs.
+Entry identifier if App want use custom bootstrap. In most case, [`App.[tj]sx`](/apis/app/hooks/src/app) hook file can already meet our needs.
 
 When we need to add custom behavior before `bootstrap` or completely take over the webpack entry, we can place `index.[tj]s` in `src/` or entry directory. The following are discussed in two cases:
 

package/docs/en/apis/app/runtime/core/bootstrap.mdx

@@ -3,7 +3,7 @@ title: bootstrap
 ---
 # bootstrap
 
-Used to start and mount App, usually without manual calls. This API is only required when using [Custom App](/guides/concept/entries#自定义-app).
+Used to start and mount App, usually without manual calls. This API is only required when using [Custom Bootstrap](/guides/concept/entries#custom-bootstrap).
 
 ## Usage
 

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

@@ -163,7 +163,9 @@ You can set this to disable the default behavior of a client-side route:
 ```js
 export default defineConfig({
   output: {
-    preventDefault: ['/user'],
+    ssg: {
+      preventDefault: ['/user'],
+    },
   },
 });
 ```

package/docs/en/configure/app/source/entries.mdx

@@ -13,6 +13,7 @@ type Entries = Record<
   | {
       entry: string;
       disableMount?: boolean;
+      customBootstrap?: string;
     }
 >;
 ```
@@ -81,6 +82,7 @@ When the value is `Object`, the following properties can be configured:
 
 - `entry`: `string`, entry file path.
 - `disableMount`: `boolean = false`, turn off the entry-scanning behavior of Modern.js.
+- `customBootstrap`: `string = ''`, [Custom Bootstrap](/guides/concept/entries#custom-bootstrap) file path。
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';

package/docs/en/configure/app/tools/tailwindcss.mdx

@@ -24,9 +24,37 @@ const tailwind = {
 };
 ```
 
-When the value is of type `Object`, rhe configuration corresponding to [TailwindCSS](https://tailwindcss.com/docs/configuration) is merged with the default configuration through `Object.assign`.
+### Function Type
 
-When the value is of type `Function`, the object returned by the function is merged with the default configuration by `Object.assign`.
+When `tools.tailwindcss`'s type is Function, the default tailwindcss config will be passed in as the first parameter, the config object can be modified directly, or a value can be returned as the final result.
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tailwindcss(config) {
+      config.content.push('./some-folder/**/*.{js,ts}');
+    },
+  },
+};
+```
+
+### Object Type
+
+When `tools.tailwindcss`'s type is `Object`, the config will be shallow merged with default config by `Object.assign`.
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tailwindcss: {
+      plugins: [
+        require('@tailwindcss/forms'),
+        require('@tailwindcss/aspect-ratio'),
+        require('@tailwindcss/typography'),
+      ],
+    },
+  },
+};
+```
 
 ### Limitations
 

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

@@ -43,6 +43,15 @@ export default defineConfig({
 });
 ```
 
+When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify `<'rspack'>` generic type for `defineConfig`:
+
+```diff title=modern.config.ts
+- export default defineConfig({
++ export default defineConfig<'rspack'>({
+   //...
+});
+```
+
 ### modern.config.js
 
 If you are developing a non-TypeScript project, you can use the configuration file in .js format:
@@ -242,3 +251,29 @@ const mergedConfig = {
   },
 };
 ```
+
+## Configuration Type
+
+Modern.js exports `AppUserConfig` type, which corresponds to the type of Modern.js configuration object:
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig = {
+  tools: {
+    webpack: {},
+  },
+};
+```
+
+When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify `<'rspack'>` generic type for `defineConfig`:
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig<'rspack'> = {
+  tools: {
+    rspack: {},
+  },
+};
+```

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

@@ -27,8 +27,7 @@ When using Rspack as the bundler, the following Features are temporarily unavail
 
 - Micro Frontend
 - Storybook Devtool
-- Server Side Rendering + Conventional Routing
-- Static Site Generation + Conventional Routing
+- The usage of [useLoader](/guides/basic-features/data-fetch.html) in Client Side Rendering
 
 :::
 

package/docs/en/guides/advanced-features/ssg.mdx

@@ -86,7 +86,7 @@ After executing `pnpm run serve` to start the project, visit the page in the Net
 
 ### Self-controlled Routing
 
-**Self-controlled routing** is a custom routing through component code, which requires the application to run to obtain accurate routing information. Therefore, the SSG function cannot be used out of the box. At this time, the user needs to inform the Modern.js framework in advance which routes need to enable the SSG.
+**Self-controlled routing** is a routing through component code, which requires the application to run to obtain accurate routing information. Therefore, the SSG function cannot be used out of the box. At this time, the user needs to inform the Modern.js framework in advance which routes need to enable the SSG.
 
 For example, there is the following code, which contains multiple routes. When setting `output.ssg` to `true`, only the entry route '/' will be rendered by default:
 

package/docs/en/guides/advanced-features/testing.mdx

@@ -4,7 +4,7 @@ title: Testing
 ---
 # Testing
 
-Modern.js inherits the testing capabilities of [Jest](https://jestjs.io/) by default.
+Modern.js integrates the testing capabilities of [Jest](https://jestjs.io/) by default.
 
 First need to execute `pnpm run new` enable [unit test/integration test] features:
 

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

@@ -367,6 +367,22 @@ To further improve the user experience and reduce time of loading, Modern.js sup
 - `intent`, the value we recommend for most scenarios, will automatically start loading the corresponding resources and the data defined in the data loader when you mouse over the Link, and will automatically unload it when the mouse is moved away. In our tests, even a direct click can reduce the loading time by about 200ms.
 - `render`, when the Link component renders, it will load the corresponding resources and the data defined in the data loader.
 
+#### FAQ
+
+1. What is the difference between using `render` and not split chunks based on routes?
+
+- With `render` you can specify which routes are loaded on the first screen, and you can control the rendering so that Link components are rendered only when they are in the visible area.
+- With `render`, static resources are loaded only when they are idle and do not hog the network with first-screen static resources.
+- When using server side rendering, data is also prefetched.
+
+import Motivation from '@site-docs/components/convention-routing-movitation'
+
+<Motivation/>
+
+import Practice from '@site-docs-en/components/routes-practice'
+
+<Practice/>
+
 ## Self-controlled routing
 
 With `src/App.tsx` as the agreed entry, Modern.js will not do additional operations with multiple routes, developers can use the React Router 6 API for development by themselves, for example:
@@ -388,9 +404,12 @@ export default () => {
 
 :::note
 Modern.js has a series of resource loading and rendering optimizations to the default convention-based routing, and provides out-of-the-box SSR capabilities, when using self-directed routing, need to be packaged by the developer, and it is recommended that developers use convention-based routing.
-
 :::
 
+use self-controller routing, if the developer turns off the [`runtime.router`](/configure/app/runtime/router) configuration and uses `react-router-dom` directly, then you need to wrap the `Provider` according to the React Router documentation.
+
+```tsx title="src/App.tsx"
+
 ## Other
 
 By default, Modern.js turn on the built-in routing scheme, React Router.

package/docs/en/guides/concept/entries.mdx

@@ -98,27 +98,49 @@ Framework mode refers to the need to use the capabilities of the Modern.js frame
 
 #### Conventional Routing
 
-If there is a `routes/` directory in the entry, Modern.js will scan the files under `routes/` at startup, and automatically generate client-side routes (react-router) based on file conventions.
+If there is a `routes/` directory in the entry, Modern.js will scan the files under `routes/` at startup, and automatically generate client-side routes (react-router) based on file conventions. For example:
 
-For details, please refer to [routing](/guides/basic-features/routes).
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       └── page.tsx
+```
 
-#### Custom Routing
+For details, please refer to [routing](/guides/basic-features/routes#conventional-routing).
+
+#### Self-controlled Routing
 
 If there is an `App.[jt]sx?` file in the entry, the developer can freely set the client route in this file, or not set the client route.
 
-For details, please refer to [routing](/guides/basic-features/routes).
+```tsx
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
 
-#### Custom App
+For details, please refer to [routing](/guides/basic-features/routes#self-controlled-routing).
 
-If there is an `index.[jt]sx` file in the entry, and when the file exports functions by default, Modern.js will still generate the code wrapped by createApp according to the runtime settings. In the rendering process, the component wrapped by createApp is passed as a parameter to the function exported by the index file, so that developers can customize the component to be mounted on the DOM node, or add custom behavior before mounting. For example:
+#### Custom Bootstrap
 
-```tsx
-import ReactDOM from 'react-dom/client';
-import { bootstrap } from '@modern-js/runtime';
+If there is an `index.[jt]sx` file in the entry, and when the file defaults to exporting functions, Modern.js will pass the default bootstrap function as an imported parameter, and replace the default bootstrap with the exported function, so that developers can customize Mounting components to DOM nodes, or adding custom behavior before mounting. E.g:
 
-export default (App: React.ComponentType) => {
+```tsx
+export default (App: React.ComponentType, bootstrap: () => void) => {
   // do something before bootstrap...
-  bootstrap(App, 'root', undefined, ReactDOM);
+  initSomething().then(() => {
+    bootstrap();
+  })
 };
 ```
 
@@ -170,9 +192,9 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-Modern.js **not recommended** to use this method, this method loses some capabilities of the framework, such as the `runtime` configuration in the **`modern.config.js` file will no longer take effect**. But this method will be very useful when the project is migrated from other frameworks to Modern.js, such as CRA, or webpack that is manually built by yourself.
+Modern.js **not recommended** new project to use this method, this method loses some capabilities of the framework, such as the `runtime` configuration in the **`modern.config.js` file will no longer take effect**. But this method will be very useful when the project is migrated from other frameworks to Modern.js, such as CRA, or webpack that is manually built by yourself.
 
-## Custom Entry
+## Specify Entry Using Configuration
 
 Most existing projects are not built according to the directory convention of Modern.js. If you want to change to the directory structure agreed by Modern.js, there will be a certain migration cost.
 

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

@@ -611,7 +611,7 @@ export default (): CliPlugin => ({
 
 This adds a new Script tag to the HTML template.
 
-<!-- ## Server
+{/* ## Server
 
 :::note
 The Server plugin is currently not fully opened, and the API is not guaranteed to be stable. Use with caution.
@@ -691,7 +691,7 @@ export default (): ServerPlugin => ({
     };
   },
 });
-``` -->
+```*/}
 
 ## Runtime
 
@@ -762,7 +762,7 @@ export default (): Plugin => ({
 });
 ```
 
-<!-- ### `provide`
+{/* ### `provide`
 
 - Function: Modifies the Elements that need to be rendered.
 - Execution Stage: Rendering (SSR/CSR).
@@ -834,4 +834,4 @@ export default (): Plugin => ({
     };
   },
 });
-``` -->
+``` */}

package/docs/zh/apis/app/hooks/src/index_.mdx

@@ -4,7 +4,7 @@ sidebar_position: 4
 ---
 # index.[tj]s
 
-应用项目自定义路由入口标识。
+应用项目入口标识。
 
 通常情况下 [`src/App.[tj]sx, src/[entry]/App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论:
 

package/docs/zh/apis/app/runtime/core/bootstrap.mdx

@@ -3,7 +3,7 @@ title: bootstrap
 ---
 # bootstrap
 
-用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 App](/guides/concept/entries#自定义-app) 时，才需要使用该 API。
+用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 Bootstrap](/guides/concept/entries#自定义-bootstrap) 时，才需要使用该 API。
 
 ## 使用姿势
 

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

@@ -163,7 +163,9 @@ export default defineConfig({
 ```js
 export default defineConfig({
   output: {
-    preventDefault: ['/user'],
+    ssg: {
+      preventDefault: ['/user'],
+    },
   },
 });
 ```

package/docs/zh/configure/app/source/entries.mdx

@@ -13,6 +13,7 @@ type Entries = Record<
   | {
       entry: string;
       disableMount?: boolean;
+      customBootstrap?: string;
     }
 >;
 ```
@@ -83,6 +84,7 @@ export default defineConfig({
 
 - `entry`：`string`，入口文件路径。
 - `disableMount`：`boolean = false`，关闭 Modern.js 自动生成入口代码的行为。
+- `customBootstrap`： `string = ''`，指定[自定义 Bootstrap](/guides/concept/entries#自定义-bootstrap) 的文件路径。
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';

package/docs/zh/configure/app/tools/tailwindcss.mdx

@@ -26,12 +26,40 @@ const tailwind = {
 
 对应 [TailwindCSS](https://tailwindcss.com/docs/configuration) 的配置。
 
-当值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。
+### Function 类型
 
-当值为 `Function` 类型时，函数返回的对象与默认配置通过 `Object.assign` 合并。
+当 `tools.tailwindcss` 为 Function 类型时，默认配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个值作为最终结果：
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tailwindcss(config) {
+      config.content.push('./some-folder/**/*.{js,ts}');
+    },
+  },
+};
+```
+
+### Object 类型
+
+当 `tools.tailwindcss` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 浅合并。
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tailwindcss: {
+      plugins: [
+        require('@tailwindcss/forms'),
+        require('@tailwindcss/aspect-ratio'),
+        require('@tailwindcss/typography'),
+      ],
+    },
+  },
+};
+```
 
 ### 限制
 
 注意，该配置中不允许使用 `theme` 配置项，否则会构建失败。在 Modern.js 中，请使用 [source.designSystem](/configure/app/source/design-system) 作为 `Tailwind CSS Theme` 配置。
 
-其他的使用方式和 Tailwind CSS 一致: [快速传送门](https://tailwindcss.com/docs/configuration)。
+其他配置的使用方式和 Tailwind CSS 一致，请参考 [tailwindcss - Configuration](https://tailwindcss.com/docs/configuration)。

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

@@ -43,6 +43,15 @@ export default defineConfig({
 });
 ```
 
+当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `defineConfig` 指定 `<'rspack'>` 泛型：
+
+```diff title=modern.config.ts
+- export default defineConfig({
++ export default defineConfig<'rspack'>({
+  // ...
+});
+```
+
 ### modern.config.js
 
 如果你在开发一个非 TypeScript 项目，可以使用 .js 格式的配置文件：
@@ -242,3 +251,29 @@ const mergedConfig = {
   },
 };
 ```
+
+## 配置类型定义
+
+Modern.js 导出了 `AppUserConfig` 类型，对应 Modern.js 配置对象的类型：
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig = {
+  tools: {
+    webpack: {},
+  },
+};
+```
+
+当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `AppUserConfig` 指定 `<'rspack'>` 泛型：
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig<'rspack'> = {
+  tools: {
+    rspack: {},
+  },
+};
+```

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

@@ -28,8 +28,7 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 
 - 微前端（Micro Frontend）
 - Storybook 调试
-- 同时使用服务端渲染（SSR）和约定式路由的场景
-- 同时使用静态站点生成（SSG）和约定式路由的场景
+- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data-fetch.html)
 
 :::
 

package/docs/zh/guides/advanced-features/ssg.mdx

@@ -86,7 +86,7 @@ export default defineConfig({
 
 ### 在自控式路由中使用
 
-**自控式路由**是通过组件代码自定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。此时需要用户提前告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
+**自控式路由**是通过组件代码定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。此时需要用户提前告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
 
 例如有以下代码，包含多条路由，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`：
 

package/docs/zh/guides/advanced-features/testing.mdx

@@ -4,7 +4,7 @@ sidebar_position: 10
 
 # 测试
 
-Modern.js 默认继承了 [Jest](https://jestjs.io/) 的测试能力。
+Modern.js 默认集成了 [Jest](https://jestjs.io/) 的测试能力。
 
 我们首先需要执行 `pnpm run new` 启用「单元测试 / 集成测试」功能：
 

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

@@ -339,6 +339,15 @@ export default async (): Promise<ProfileData> => {
 
 4. 在服务端运行时，`loader` 函数会被打包为一个统一的 bundle，所以我们不推荐服务端的代码使用 `__filename` 和 `__dirname`。
 
+### 常见问题
+
+1. loader 和 bff 的关系
+
+在 CSR 项目中，loader 在客户端执行，在 loader 可以直接调用 bff 函数进行接口请求。
+
+在 SSR 项目中，每个 loader 也是一个服务端接口，我们推荐使用 loader 替代 http method 为 `get` 的 BFF 函数，作为接口层，避免多一层转发和执行。
+
+
 ## useLoader（旧版）
 
 **`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。

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

@@ -444,7 +444,7 @@ export const init = (context: RuntimeContext) => {
 };
 ```
 
-### Prefetch
+### 预加载
 
 在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片，当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
 这种情况下你可以通过定义 `loading` 组件，在静态资源加载完成前，展示一个自定义的 `loading` 组件。
@@ -462,9 +462,24 @@ export const init = (context: RuntimeContext) => {
 :::
 
 - `none`， 默认值，不会做 prefetch，没有任何额外的行为。
-- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 data loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是直接点击，也能减少大约 200ms 的加载时间。
+- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 data loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
 - `render`，当 Link 组件渲染时，就会加载对应的分片和 data loader 中定义的数据。
 
+#### 常见问题
+
+1. 使用 `render` 和不根据路由做静态资源分片的区别？
+
+- 使用 `render` 可以指定哪些路由在首屏时，进行加载，同时你可以通过对渲染的控制，仅当 Link 组件进入到可视区域时，才对 Link 组件进行渲染。
+- 使用 `render`，仅在空闲时对静态资源进行加载，不会与首屏静态资源抢占网络。
+- 在 SSR 场景下，也会对数据进行预取。
+
+import Motivation from '@site-docs/components/convention-routing-movitation'
+
+<Motivation/>
+
+import Practice from '@site-docs/components/routes-practice'
+
+<Practice/>
 
 
 ## 自控式路由
@@ -488,9 +503,10 @@ export default () => {
 
 :::note
 Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化，并且提供了开箱即用的 SSR 能力，而这些能力，在使用自控路由时，都需要开发者自行封装，推荐开发者使用约定式路由。
-
 :::
 
+使用自控式路由时，如果开发者关闭了 [`runtime.router`](/configure/app/runtime/router) 配置，并直接使用 `react-router-dom`，那还需要根据 React Router 文档自行包裹 `Provider`。
+
 ## 其他路由方案
 
 默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
@@ -513,19 +529,5 @@ export default defineConfig({
 });
 ```
 
-### 常见问题
-
-1. 产物中的代码是 es2015+ 的，期望产物中是 es5 的代码
-
-react-router^6 的目前默认产物是 es2020 的，如果需要产物中是 es5 的代码，可以配置 `source.include`，让 react-router 相关包经过 bundler 编译 ：
-
-```
-source: {
-  source: {
-    include: [/@remix-run\/router/, /react-router-dom/, /react-router/],
-  }
-}
-```
-
 
 

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

@@ -98,36 +98,55 @@ Modern.js 会将与 package.json 文件中 `name` 字段同名的入口作为主
 
 #### 约定式路由
 
-如果入口中存在 `routes/` 目录，Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。
+如果入口中存在 `routes/` 目录，Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。例如：
 
-详细内容可以参考[路由](/guides/basic-features/routes)。
-
-#### 自定义路由
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       └── page.tsx
+```
 
-如果入口中存在 `App.[jt]sx?` 文件，开发者可以在这个文件中自由的设置客户端路由，或者不设置客户端路由。
+上述目录中，`layout.tsx` 中导出的组件会作为最外层的组件，`page.tsx` 中导出的组件会作为 `/` 路由的组件。
 
-详细内容可以参考[路由](/guides/basic-features/routes)。
+详细内容可以参考[路由](/guides/basic-features/routes#约定式路由)。
 
-#### 自定义 App
+#### 自控式路由
 
-如果入口中存在 `index.[jt]sx` 文件，并且当文件默认导出函数时，Modern.js 还是会根据 runtime 的设置情况生成 createApp 包裹后的代码。在渲染过程中，将 createApp 包裹后的组件作为参数传递给 index 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+如果入口中存在 `App.[jt]sx?` 文件，开发者可以在这个文件中通过代码的方式，设置客户端路由，或者不设置客户端路由。
 
 ```tsx
-import ReactDOM from 'react-dom/client';
-import { bootstrap } from '@modern-js/runtime';
-
-export default (App: React.ComponentType) => {
-  // do something before bootstrap...
-  bootstrap(App, 'root', undefined, ReactDOM);
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
 };
 ```
 
-:::warning
-由于 bootstrap 函数需要兼容 React17 和 React18 的用法，调用 bootstrap 函数时需要手动传入 ReactDOM 参数。
+详细内容可以参考[路由](/guides/basic-features/routes#自控式路由)。
 
-:::
+#### 自定义 Bootstrap
+
+如果入口中存在 `index.[jt]sx` 文件，并且当文件默认导出函数时，Modern.js 会将默认的 bootstrap 函数作为入参传入，并用导出的函数替代默认的 bootstrap，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+
+```tsx
+export default (App: React.ComponentType, bootstrap: () => void) => {
+  // do something before bootstrap...
+  initSomething().then(() => {
+    bootstrap();
+  })
+};
+```
 
-Modern.js 生成的文件内容如下：
+此时，Modern.js 生成的文件内容如下：
 
 ```js
 import React from 'react';
@@ -140,13 +159,14 @@ const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
 const MOUNT_ID = 'root';
 
 let AppWrapper = null;
+let root = null;
 
 function render() {
   AppWrapper = createApp({
     // runtime 的插件参数...
   })(App);
   if (IS_BROWSER) {
-    customBootstrap(AppWrapper);
+    customBootstrap(AppWrapper, () => bootstrap(AppWrapper, MOUNT_ID, root, ReactDOM));
   }
   return AppWrapper;
 }
@@ -170,9 +190,9 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-Modern.js **不推荐**使用这种方式，这种方式丧失了框架的一些能力，如 **`modern.config.js` 文件中的 `runtime` 配置将不会再生效**。但是在项目从其他框架迁移到 Modern.js，例如 CRA，或是自己手动搭建的 webpack 时，这种方式会非常有用。
+Modern.js **不推荐**新项目使用这种方式，这种方式丧失了框架的一些能力，如 **`modern.config.js` 文件中的 `runtime` 配置将不会再生效**。但是在项目从其他框架迁移到 Modern.js，例如 CRA，或是自己手动搭建的 webpack 时，这种方式会非常有用。
 
-## 自定义入口
+## 使用配置指定入口
 
 大部分存量项目并不是按照 Modern.js 的目录结构来搭建的。如果要改成 Modern.js 约定的目录结构，会存在一定的迁移成本。
 

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

@@ -611,7 +611,7 @@ export default (): CliPlugin => ({
 
 这样就为 HTML 模版中新增了一个 Script 标签。
 
-<!-- ## Server
+{/* ## Server
 
 :::note
 目前 Server 插件还未完全开放，API 不保证稳定，使用需谨慎。
@@ -692,7 +692,7 @@ export default (): ServerPlugin => ({
     };
   },
 });
-``` -->
+```*/}
 
 ## Runtime
 
@@ -764,7 +764,7 @@ export default (): Plugin => ({
 });
 ```
 
-<!-- ### `provide`
+{/* ### `provide`
 
 - 功能：修改需要渲染的 Element
 - 执行阶段：渲染（SSR/CSR）
@@ -836,4 +836,4 @@ export default (): Plugin => ({
     };
   },
 });
-``` -->
+```*/}

package/package.json

@@ -15,7 +15,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.17.1",
+  "version": "2.17.2-alpha.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"