@modern-js/main-doc 2.58.2 → 2.58.3

package/docs/en/community/blog/_meta.json

@@ -1,6 +1 @@
-[
-  "overview",
-  "v2-release-note",
-  "2022-0910-updates",
-  "2022-0708-updates"
-]
+["overview", "v2-release-note", "2022-0910-updates", "2022-0708-updates"]

package/docs/en/components/deploy.mdx

@@ -1 +1 @@
-After local verification, you can organize the artifacts in `dist/` into the structure required by the server for deployment.
+After local develop, you can refer to the [Deployment](/guides/basic-features/deploy.html) section to deploy the project to the server.

package/docs/en/configure/_meta.json

@@ -75,4 +75,4 @@
   },
   "app/builder-plugins",
   "app/auto-load-plugin"
-]
+]

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

@@ -19,7 +19,7 @@ When using Rspack as the bundler, SWC will be used for transpiling and compressi
 
 ## Used in Rspack mode
 
-You can set the options of [builtin:swc-loader](https://www.rspack.dev/guide/builtin-swc-loader) through `tools.swc`.
+You can set the options of [builtin:swc-loader](https://rspack.dev/guide/features/builtin-swc-loader) through `tools.swc`.
 
 ```
 import { defineConfig } from '@modern-js/app-tools';

package/docs/en/guides/advanced-features/bff/_meta.json

@@ -1,6 +1 @@
-[
-  "function",
-  "type",
-  "frameworks",
-  "sdk"
-]
+["function", "type", "frameworks", "sdk"]

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

@@ -22,13 +22,6 @@ import InitRspackApp from '@site-docs-en/components/init-rspack-app';
 
 After the project is created, you can experience the project by running `pnpm run dev`. For more project information, please refer to [Quick Start](/guides/get-started/quick-start.html).
 
-:::tip
-When using Rspack as the bundler, the following Features are temporarily unavailable as some of the capabilities are still under development and we will provide support in the future.
-
-- The usage of [useLoader](/guides/basic-features/data/data-fetch.html) in Client Side Rendering
-
-:::
-
 ## Enable Rspack build
 
 Since Modern.js MAJOR_VERSION.46.0, you can enable Rspack build by add the following configuration in `modern.config.ts`:
@@ -85,7 +78,7 @@ For unsupported configurations, we have marked `Bundler: only support webpack` o
 
 ## Modify transpile configuration
 
-Modern.js uses Rspack [builtin:swc-loader](https://www.rspack.dev/guide/builtin-swc-loader.html) for code translation in Rspack mode.
+Modern.js uses Rspack [builtin:swc-loader](https://rspack.dev/guide/features/builtin-swc-loader) for code translation in Rspack mode.
 
 Modern.js has provided a more convenient configuration for the common configuration of `builtin:swc-loader`, such as: configuring the component library to import it on demand through [source.transformImport](/configure/app/source/transform-import).
 

package/docs/en/guides/advanced-features/ssr/_meta.json

@@ -1,5 +1 @@
-[
-  "usage",
-  "stream",
-  "cache"
-]
+["usage", "stream", "cache"]

package/docs/en/guides/basic-features/data/_meta.json

@@ -1,4 +1 @@
-[
-  "data-fetch",
-  "data-write"
-]
+["data-fetch", "data-write"]

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

@@ -481,7 +481,7 @@ The Data Loader in our SSR project is designed to only run on the server side. T
 **`useLoader`** is a legacy API in Modern.js v1. This API is a React Hook designed specifically for SSR applications, allowing developers to fetch data in components in isomorphic development.
 
 :::tip
-It is not necessary to use `useLoader` to fetch data in CSR projects.
+It is not necessary to use `useLoader` to fetch data in CSR projects, and `useLoader` is not supported when using Rspack as the bundler.
 :::
 
 Here is the simplest example:

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

@@ -380,7 +380,7 @@ export default () => {
 
 In each directory under `routes/`, developers can also define an `error.tsx` file that exports an `<ErrorBoundary>` component by default.
 
-When this component exists in the routes directory, any rendering errors will be caught by the `ErrorBoundary` component. When the `layout.tsx` file is not defined in the directory, the `<ErrorBoundary>` component will not take effect.
+When this component exists in the routes directory, any rendering errors will be caught by the `ErrorBoundary` component.
 
 `<ErrorBoundary>` can return the UI view when an error occurs. When the `<ErrorBoundary>` component is not declared in the current level, the error will bubble up to a higher-level component until it is caught or thrown. At the same time, when a component has an error, it will only affect the route component and its child components that catch the error. The status and view of other components are not affected and can continue to interact.
 

package/docs/en/guides/concept/_meta.json

@@ -1,4 +1 @@
-[
-  "entries",
-  "builder"
-]
+["entries", "builder"]

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

@@ -16,7 +16,7 @@ Many configuration options provided by Modern.js are divided by entry, such as p
 
 ## Single Entry and Multiple Entries
 
-The project initialized by Modern.js is a single entry (SPA) project, with the following structure:
+The project initialized by Modern.js is a single entry project, with the following structure:
 
 ```
 .
@@ -56,13 +56,12 @@ After running the command, Modern.js will automatically generate a new entry dir
 
 The original entry code has been moved to a directory with the same name as the `name` field in `package.json`, and a `new-entry` entry directory has been created.
 
-You can run `pnpm run dev` to start the development server. At this point, you will see a new route named `/new-entry` added, and the existing page routes remain unchanged.
-
-:::tip
 Modern.js will use the entry with the same name as the `name` field in `package.json` as the main entry. The route of the main entry is `/`, and the route of other entries is `/{entryName}`.
 
-For example, when the `name` field in `package.json` is `myapp`, `src/myapp` will be the main entry of the project.
+You can run `pnpm run dev` to start the development server. At this point, you will see a new route named `/new-entry` added, and the existing page routes remain unchanged.
 
+:::note
+The concepts of **single entry/multiple entry** and **SPA/MPA** are not equivalent. The former pertains to how to configure and package the application, while the latter is about the patterns for organizing front-end applications. Each entry point can be either an SPA or a non-SPA.
 :::
 
 ## Entry Types
@@ -82,30 +81,26 @@ By default, Modern.js scans the files under `src/` before starting the project,
 
 :::
 
-Not all top-level directories under `src/` become project entries. The directory where the entry is located must meet one of the following five conditions:
+The entry directory must meet one of the following three conditions:
 
 1. Has a `routes/` directory.
 2. Has an `App.[jt]sx?` file.
-3. Has an `index.[jt]sx?` file.
-4. Has a `pages/` directory (compatible with Modern.js 1.0).
-5. Has an `entry.[jt]sx?` file.
+5. Has an `entry.[jt]sx?` file.(Requires [source.enableCustomEntry](/configure/app/source/enable-custom-entry) to be enabled)
 
-When the `src/` directory meets the entry requirements, Modern.js considers the current project as a single entry application.
+When the `src/` directory meets the conditions of an entry, Modern.js will consider the current application to be a single-entry application. Otherwise, Modern.js will scan the first-level directories under `src/` and further determine if they are entries. In this case, the application is typically a multi-entry application.
 
 :::tip
 In a single entry application, the default entry name is `main`.
 
 :::
 
-When the project is not a single entry application, Modern.js will further look at the top-level directories under `src/`.
-
 ### Framework Mode Entry
 
-The framework mode refers to the need to use the framework capabilities of Modern.js, such as nested routing, SSR, and integrated BFF, etc. Under this kind of entry convention, the entry defined by the developer is not the actual compilation entry. When Modern.js is launched, it generates a wrapped entry, and the real entry can be found at `node_modules/.modern/[entryName]/index.js`.
+Framework mode refers to using Modern.js's framework capabilities, such as convention routing, SSR (Server-Side Rendering), and integrated calls. Under this type of entry convention, the entries in the application are not the actual compilation entries. Modern.js will generate a wrapped entry during startup, which you can find in `node_modules/.modern/[entryName]/index.js`.
 
 #### Conventional Routing
 
-If there is a `routes/` directory in the entry, Modern.js will scan the files under `routes/` during startup, and automatically generate client-side routes (react-router) based on file conventions. For example:
+If there is a `routes/` directory within the entry, we refer to this entry as a convention-based route. Modern.js will scan the files under `routes/` during startup and automatically generate client-side routes (react-router) based on file conventions. For example:
 
 ```bash
 .
@@ -121,7 +116,15 @@ For more information, please refer to [Conventional Routing](/guides/basic-featu
 
 #### Self-controlled Routing
 
-If there is an `App.[jt]sx?` file in the entry, developers can set the client-side route in this file through code, or not set the client-side route.
+If there is an `App.[jt]sx?` file within the entry, we refer to this entry as a self-controlled route. For example:
+
+```bash
+.
+├── src
+│   └── App.tsx
+```
+
+In this file, you can define client-side routes or  not to set any client-side routes.
 
 ```tsx
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
@@ -142,12 +145,14 @@ For more information, please refer to [Self-controlled Routing](/guides/basic-fe
 
 #### Custom Entry
 
-If there is an `entry.[jt]sx` file in the entry, developers need to call the `createRoot` and `render` functions in the `entry.[jt]sx` file to complete the project's entry logic.
-
 :::info
-Using this file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+Using this features requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
 :::
 
+By default, whether you use convention routing or self-controlled routing, Modern.js will automatically handle rendering. If you wish to customize this behavior, you can creating a custom entry file.
+
+If there is an `entry.[jt]sx` file within the entry, Modern.js will no longer control the application's rendering process. You can call the `createRoot` and `render` functions within the `entry.[jt]sx` file to complete the entry logic for your application.
+
 ```tsx
 import { createRoot } from '@modern-js/runtime/react';
 import { render } from '@modern-js/runtime/browser';
@@ -157,7 +162,9 @@ const ModernRoot = createRoot();
 render(<ModernRoot />);
 ```
 
-For example, if some other operations need to be performed before render is executed, it can be implemented in this way:
+In the code above, the component returned by the `createRoot` function is either the component generated from the `routes/` directory or the component exported by `App.tsx`. 
+
+The `render` function is used to handle rendering and mounting of the component. For example, if you want to execute some asynchronous tasks before rendering, you can achieve it like this:
 
 ```tsx
 import { createRoot } from '@modern-js/runtime/react';
@@ -166,7 +173,7 @@ import { render } from '@modern-js/runtime/browser';
 const ModernRoot = createRoot();
 
 async function beforeRender() {
-   // todo
+  // some async request
 }
 
 beforeRender().then(() => {
@@ -174,34 +181,15 @@ beforeRender().then(() => {
 });
 ```
 
-#### Custom Bootstrap
-
-:::warning
-Soon to be deprecated, it is recommended to use a custom entry.
-:::
-
-If there is an `index.[jt]sx` file in the entry, and the file exports a function by default, Modern.js will pass the default `bootstrap` function as a parameter and use the exported function to replace the default `bootstrap`. This way, developers can customize how components are mounted to DOM nodes or add custom behavior before mounting. For example:
-
-```tsx
-export default (App: React.ComponentType, bootstrap: () => void) => {
-  // do something before bootstrap...
-  initSomething().then(() => {
-    bootstrap();
-  });
-};
-```
-
 ### Build Mode Entry
 
-Build mode refers to not using the Runtime capabilities provided by Modern.js, but rather having the developer define the entry of the page completely on their own.
-
-When the entry directory contains `index.[jt]sx` (soon to be deprecated) and does not export a function via `export default`, or when there is an `entry.[jt]sx` file in the entry directory and the `@modern-js/runtime` dependency is not installed, the corresponding file will be identified as the entry module of webpack or Rspack.
-
 :::info
-Using the `entry.[jt]sx` file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+Using this features requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
 :::
 
-In this case, Modern.js will not generate the entry code automatically. Therefore, you need to manually mount the component to the DOM node, for example:
+Build mode refers to the development mode that does not use Modern.js's runtime capabilities and only utilizes Modern.js's build capabilities. When the `@modern-js/runtime` dependency is not installed in the application, Modern.js will treat all entries as build mode entries.
+
+In this case, if there is an `entry.[jt]sx` file within the entry, this file will be recognized as the build entry for webpack or Rspack. Modern.js will not automatically generate entry code at this time, and you need to mount the component to the DOM node yourself. For example:
 
 ```js title=src/entry.tsx
 import React from 'react';
@@ -211,9 +199,13 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-This approach is equivalent to enabling the [source.entries.disableMount](/configure/app/source/entries) option in Modern.js. When you use this approach, **you will not be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the `modern.config.js` file will no longer take effect.
+In build mode, the application **will not be able to use Modern.js's runtime capabilities**, such as:
+- Convention routing, the routing based on the files under `src/routes`
+- Server-Side Rendering (SSR)
+- The `runtime` configuration in the `modern.config.js` file will no longer take effect
 
-## Custom Entries Config
+
+## Specify entry in the configuration file
 
 In some cases, you may need to customize the entry configuration instead of using the entry conventions provided by Modern.js.
 
@@ -246,4 +238,36 @@ export default defineConfig({
 });
 ```
 
-Note that when you enable `disableMount`, **you won't be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the `modern.config.ts` file.
+It is worth noting that, by default, Modern.js considers entries specified through the configuration as **framework mode entries** and will automatically generate the actual compilation entry. 
+
+If your application is migrating from build tools like Webpack or Vite to the Modern.js framework, you typically need to enable the `disableMount` option in the entry configuration. In this case, Modern.js will treat the entry as a **build mode entry**.
+
+## Deprecated
+
+Currently, if the entry directory meets the following conditions, it will also be considered an application entry:
+
+1. Has an `index.[jt]sx?` file.
+2. Has a `pages/` directory.
+
+The `pages/` directory was the convention routing in older versions of Modern.js. Now, it is recommended to use the `routes/` directory.
+
+The `index.[jt]sx?` file supported **Custom Bootstrap** and **Build Mode Entry** in older versions. Now, it is recommended to use `entry.[jt]sx?` instead.
+
+### Custom Bootstrap
+
+When there is an `index.[jt]sx` file in the entry, and  the file's default export is a function, Modern.js will pass the default `bootstrap` function as an argument and use the exported function to replace the default `bootstrap`. 
+
+This allows developers to customize mounting components to DOM or add custom behaviors before mounting. For example:
+
+```tsx
+export default (App: React.ComponentType, bootstrap: () => void) => {
+  // do something before bootstrap...
+  initSomething().then(() => {
+    bootstrap();
+  });
+};
+```
+
+### Build Mode Entry
+
+When an `index.[jt]sx` file exists in the entry directory and does not export a function via export default, this entry will also be considered a build mode entry.

package/docs/en/guides/get-started/_meta.json

@@ -1,7 +1 @@
-[
-  "introduction",
-  "quick-start",
-  "upgrade",
-  "glossary",
-  "tech-stack"
-]
+["introduction", "quick-start", "upgrade", "glossary", "tech-stack"]

package/docs/en/guides/get-started/introduction.mdx

@@ -55,7 +55,7 @@ It mainly includes the following features:
 - 🏠 **Integration**: Development and production environment web server are unique, CSR and SSR are isomorphic development, and API service calls are functions as interfaces.
 - 📦 **Out Of The Box**: Default TS support, built-in build, ESLint, debugging tools, fully functional and testable.
 - 🌏 **Ecology**: Self-developed state management, micro-frontend, module packaging, and other peripheral needs.
-- 🕸 **Routing Modes**: Includes self-controlled routing, file-convention-based routing (nested routing), etc.
+- 🕸 **Convention Routing**: Using file-based routing helps developers quickly set up applications.
 
 ## Comparison with Others
 

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

@@ -72,7 +72,6 @@ In a newly created project, the `@modern-js/app-tools` npm package is installed
 - It integrates Modern.js Core, providing capabilities for configuration parsing, plugin loading, and more.
 - It integrates Modern.js Builder, providing build capabilities.
 - It integrates Modern.js Server, providing capabilities for development and production servers.
-- It integrates some commonly used plugins, such as `plugin-lint`, `plugin-data-loader`, and more.
 
 `@modern-js/app-tools` is implemented based on the plugin system of Modern.js. Essentially, it is a plugin. Therefore, you need to register `appTools` in the `plugins` field of the configuration file:
 

package/docs/en/guides/get-started/tech-stack.mdx

@@ -30,8 +30,6 @@ We are also working with Zack Jackson, the author of [Module Federation](https:/
 
 Modern.js can be used with any community state management library, such as [Redux](https://redux.js.org/), [Jotai](https://jotai.org/), [Zustand](https://docs.pmnd.rs/zustand), [Valtio](https://valtio.pmnd.rs/), and more.
 
-Modern.js also provides a wrapper around Redux called Reduck for state management. You can refer to ["Reduck State Management"](/en/guides/topic-detail/model/quick-start) for usage.
-
 ## Package Manager
 
 Modern.js can be used with any community package manager, such as [npm](https://www.npmjs.com/package/npm), [yarn](https://classic.yarnpkg.com/lang/en/), [pnpm](https://pnpm.io/), or [Bun](https://bun.sh/).

package/docs/en/guides/get-started/upgrade.mdx

@@ -37,10 +37,24 @@ import ReleaseNote from '@site-docs-en/components/release-note';
 <ReleaseNote />
 
 :::tip
-When upgrading, you need to upgrade all packages provided by Modern.js, instead of upgrading a single dependency.
-
+When upgrading, you need to upgrade all packages provided by Modern.js, rather than upgrading some dependencies.
 :::
 
+## Version Management Strategy
+
+In Modern.js projects, we recommend that all officially provided dependencies use fixed version, and avoid using `^` or `~` for range declarations. For example:
+
+```json
+{
+  "dependencies": {
+    "@modern-js/app-tools": "x.y.z"
+  }
+}
+```
+
+This ensures that the versions of dependencies are fully determined, thereby guaranteeing build consistency and predictability.
+
+
 ## Lock nested dependency
 
 When a nested dependency of the project has a problem and Modern.js cannot be updated immediately, you can use the package manager to lock the version of the nested dependency.

package/docs/en/guides/topic-detail/framework-plugin/_meta.json

@@ -7,4 +7,4 @@
   "extend",
   "plugin-api",
   "hook-list"
-]
+]

package/docs/en/guides/topic-detail/generator/_meta.json

@@ -14,4 +14,4 @@
     "name": "plugin",
     "label": "generator-plugin"
   }
-]
+]

package/docs/en/guides/topic-detail/generator/create/_meta.json

@@ -1,5 +1 @@
-[
-  "use",
-  "option",
-  "config"
-]
+["use", "option", "config"]

package/docs/en/guides/topic-detail/generator/new/_meta.json

@@ -1,5 +1 @@
-[
-  "use",
-  "option",
-  "config"
-]
+["use", "option", "config"]

package/docs/en/guides/topic-detail/generator/plugin/_meta.json

@@ -8,4 +8,4 @@
     "name": "api",
     "label": "API"
   }
-]
+]

package/docs/en/guides/troubleshooting/_meta.json

@@ -1,6 +1 @@
-[
-  "dependencies",
-  "cli",
-  "builder",
-  "hmr"
-]
+["dependencies", "cli", "builder", "hmr"]

package/docs/zh/community/blog/_meta.json

@@ -1,6 +1 @@
-[
-  "overview",
-  "v2-release-note",
-  "2022-0910-updates",
-  "2022-0708-updates"
-]
+["overview", "v2-release-note", "2022-0910-updates", "2022-0708-updates"]

package/docs/zh/components/deploy.mdx

@@ -1 +1 @@
-本地验证完成后，可以将 `dist/` 下的产物整理成服务器需要的结构，进行部署。
+本地验证完成后，可以参考 [部署](/guides/basic-features/deploy.html) 一节，将项目部署到服务器上。

package/docs/zh/configure/_meta.json

@@ -75,4 +75,4 @@
   },
   "app/builder-plugins",
   "app/auto-load-plugin"
-]
+]

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

@@ -19,7 +19,7 @@ import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
 ## 在 Rspack 模式下使用
 
-通过 `tools.swc` 可以设置 Rspack [builtin:swc-loader](https://www.rspack.dev/guide/builtin-swc-loader) 的选项。
+通过 `tools.swc` 可以设置 Rspack [builtin:swc-loader](https://rspack.dev/zh/guide/features/builtin-swc-loader) 的选项。
 
 ```
 import { defineConfig } from '@modern-js/app-tools';

package/docs/zh/guides/advanced-features/bff/_meta.json

@@ -1,6 +1 @@
-[
-  "function",
-  "type",
-  "frameworks",
-  "sdk"
-]
+["function", "type", "frameworks", "sdk"]

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

@@ -22,13 +22,6 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 
 项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目，更多信息可参考[快速上手](/guides/get-started/quick-start.html)。
 
-:::tip
-在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：
-
-- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data/data-fetch.html)
-
-:::
-
 ## 开启 Rspack 构建
 
 从 Modern.js MAJOR_VERSION.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
@@ -86,7 +79,7 @@ export default {
 
 ## 修改转译配置
 
-Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://www.rspack.dev/zh/guide/builtin-swc-loader.html) 进行代码转译。
+Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://rspack.dev/zh/guide/features/builtin-swc-loader) 进行代码转译。
 
 Modern.js 已对 `builtin:swc-loader` 的常见配置提供了更方便的配置方式，如：通过 [source.transformImport](/configure/app/source/transform-import) 配置组件库按需引入。如果对 `builtin:swc-loader` 有自定义配置的需求，可通过 [tools.swc](/configure/app/tools/swc) 进行配置：
 

package/docs/zh/guides/advanced-features/ssr/_meta.json

@@ -1,5 +1 @@
-[
-  "usage",
-  "stream",
-  "cache"
-]
+["usage", "stream", "cache"]

package/docs/zh/guides/basic-features/data/_meta.json

@@ -1,4 +1 @@
-[
-  "data-fetch",
-  "data-write"
-]
+["data-fetch", "data-write"]

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

@@ -67,9 +67,9 @@ export const loader = async (): Promise<ProfileData> => {
 
 :::
 
-在 CSR 环境下，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
+在 CSR 项目中，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
 
-在 SSR 环境下，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
+在 SSR 项目中，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
 
 :::info
 在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 `loader` 的纯粹，只做数据获取的场景。
@@ -499,8 +499,7 @@ export const loader = async (): Promise<ProfileData> => {
 **`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。
 
 :::tip
-CSR 的项目没有必要使用 `useLoader` 获取数据。
-
+CSR 的项目没有必要使用 `useLoader` 获取数据，且在使用 Rspack 作为打包工具时，`useLoader` 不支持使用。
 :::
 
 以下是一个最简单的例子：

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

@@ -381,7 +381,7 @@ export default () => {
 
 `routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。
 
-当有路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
+当有路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。
 
 `<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
 

package/docs/zh/guides/concept/_meta.json

@@ -1,4 +1 @@
-[
-  "entries",
-  "builder"
-]
+["entries", "builder"]

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

@@ -10,13 +10,13 @@ sidebar_position: 1
 
 **入口（Entry）指的是一个页面的起始模块。**
 
-在 Modern.js 项目中，每一个入口对应一个独立的页面，也对应一条服务端路由。默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，同时也支持通过配置项来自定义入口。
+在 Modern.js 应用中，每一个入口对应一个独立的页面，也对应一条服务端路由。默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，同时也支持通过配置项来自定义入口。
 
 Modern.js 提供的很多配置项都是以入口为维度进行划分的，比如页面标题、HTML 模板、页面 Meta 信息、是否开启 SSR/SSG、服务端路由规则等。
 
 ## 单入口与多入口
 
-Modern.js 初始化的项目是单入口的（SPA），项目结构如下：
+Modern.js 初始化的应用是单入口的，应用结构如下：
 
 ```
 .
@@ -30,7 +30,7 @@ Modern.js 初始化的项目是单入口的（SPA），项目结构如下：
 └── tsconfig.json
 ```
 
-在 Modern.js 项目中，你可以很方便的将单入口切换成多入口，直接在项目下执行 `pnpm run new`，根据提示创建入口即可：
+在 Modern.js 应用中，你可以很方便的将单入口切换成多入口。在应用目录下执行 `pnpm run new`，根据提示即可创建入口：
 
 ```bash
 ? 请选择你想要的操作 创建工程元素
@@ -56,13 +56,12 @@ Modern.js 初始化的项目是单入口的（SPA），项目结构如下：
 
 原本的入口代码被移动到了和 `package.json` 中 `name` 同名的目录下，并创建了 `new-entry` 入口目录。
 
-你可以执行 `pnpm run dev` 启动开发服务，此时可以看到新增了一条名为 `/new-entry` 的路由，并且原有页面的路由并未发生变化。
-
-:::tip
-Modern.js 会将与 `package.json` 文件中 `name` 字段同名的入口作为主入口，主入口的路由为 `/`，其他入口的路由为 `/{entryName}`。
+Modern.js 会将与 `package.json` 文件中 `name` 字段同名的入口作为主入口，主入口的路由为 `/`，其他入口的路由为 `/{entryName}`。比如，`package.json` 中的 `name` 为 `myapp` 时，`src/myapp` 会作为应用的主入口。
 
-比如，`package.json` 中的 `name` 为 `myapp` 时，`src/myapp` 会作为项目的主入口。
+你可以执行 `pnpm run dev` 启动开发服务，此时可以看到新增了一条名为 `/new-entry` 的路由，并且原有页面的路由并未发生变化。
 
+:::note
+**单入口/多入口** 和 **SPA/MPA** 的概念并不等价。前者是关于如何配置和打包应用，而后者是组织前端应用的模式，每个入口都可以是 SPA 或非 SPA 的。
 :::
 
 ## 入口类型
@@ -73,39 +72,32 @@ import EntryMode from '@site-docs/components/entry-mode.mdx';
 
 <EntryMode />
 
-默认情况下，Modern.js 启动项目前会对 `src/` 下的文件进行扫描，识别入口，并生成对应的服务端路由。
+默认情况下，Modern.js 启动应用前会对 `src/` 下的文件进行扫描，识别入口，并生成对应的服务端路由。
 
 :::tip
-- 你可以通过 [source.entriesDir](/configure/app/source/entries-dir) 修改页面入口的识别目录。
-- 如果你需要自定义入口，请参考 [自定义入口](#自定义入口)。
-
+你可以通过 [source.entriesDir](/configure/app/source/entries-dir) 修改识别入口的目录。
 :::
 
-并非 `src/` 下所有的一级目录都会成为项目入口, 入口所在目录必须满足以下五个条件之一：
+入口所在目录必须满足以下三个条件之一：
 
 1. 具有 `routes/` 目录。
 2. 具有 `App.[jt]sx?` 文件。
-3. 具有 `entry.[jt]sx?` 文件 (需要开启 `source.enableCustomEntry` 使用)。
-4. 具有 `index.[jt]sx?` 文件（即将废弃）。
-5. 具有 `pages/` 目录（兼容 Modern.js 1.0）(即将废弃)。
+3. 具有 `entry.[jt]sx?` 文件 (需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry) 使用)。
 
 
-当 `src/` 目录满足入口特征时，Modern.js 会认为当前项目为单入口应用。
+当 `src/` 目录满足入口特征时，Modern.js 会认为当前应用为单入口应用。否则，Modern.js 会扫描 `src/` 下的一级目录，并进一步判断是否为入口，此时应用通常为多入口应用。
 
 :::tip
 在单入口应用中，默认的入口名为 `main`。
-
 :::
 
-当项目不是单入口应用时，Modern.js 会进一步查看 `src/` 下的一级目录。
-
 ### 框架模式入口
 
-框架模式指的是需要使用 Modern.js 的框架能力，例如嵌套路由、SSR、一体化调用等。这类入口约定下，开发者定义的入口并不是真正的编译入口。Modern.js 在启动时会生成一个封装过的入口，可以在 `node_modules/.modern/[entryName]/index.js` 找到真正的入口。
+框架模式指的是需要使用 Modern.js 的框架能力，例如约定式路由、SSR、一体化调用等。这类入口约定下，应用中的入口并不是真正的编译入口。Modern.js 在启动时会生成一个封装过的入口，可以在 `node_modules/.modern/[entryName]/index.js` 找到真正的入口。
 
 #### 约定式路由
 
-如果入口中存在 `routes/` 目录，Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。例如：
+如果入口中存在 `routes/` 目录，我们称该入口为约定式路由。Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。例如：
 
 ```bash
 .
@@ -121,9 +113,17 @@ import EntryMode from '@site-docs/components/entry-mode.mdx';
 
 #### 自控式路由
 
-如果入口中存在 `App.[jt]sx?` 文件，开发者可以在这个文件中通过代码的方式，设置客户端路由，或者不设置客户端路由。
+如果入口中存在 `App.[jt]sx?` 文件，我们称为该入口为自控式路由。例如：
 
-```tsx
+```bash
+.
+├── src
+│   └── App.tsx
+```
+
+你可以在这个文件中通过代码的方式，设置客户端路由，或者不设置客户端路由。
+
+```tsx title="src/App.tsx"
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
 
 export default () => {
@@ -142,12 +142,14 @@ export default () => {
 
 #### 自定义入口
 
-如果入口中存在 `entry.[jt]sx` 文件，需要开发者在 `entry.[jt]sx` 文件中调用 `createRoot` 和 `render` 函数，完成项目入口逻辑。
-
 :::info
-使用该文件需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
+使用该功能需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
 :::
 
+默认情况下，使用约定式路由或自控式路由时，Modern.js 会自动完成渲染。如果你希望自定义这个行为，可以通过自定义入口文件的方式来实现。
+
+如果入口中存在 `entry.[jt]sx` 文件，则 Modern.js 不再控制应用的渲染流程，你可以在 `entry.[jt]sx` 文件中调用 `createRoot` 和 `render` 函数，完成应用入口逻辑。
+
 ```tsx
 import { createRoot } from '@modern-js/runtime/react';
 import { render } from '@modern-js/runtime/browser';
@@ -158,7 +160,7 @@ render(<ModernRoot />);
 
 ```
 
-比如在 render 执行前，需要做一些其他操作，可以这样实现：
+上述代码中，`createRoot` 函数返回的组件为 `routes/` 目录生成或 `App.tsx` 导出的组件，`render` 函数用于处理渲染与挂载组件。例如，你希望在渲染前执行某些异步任务，可以这样实现：
 
 ```tsx
 import { createRoot } from '@modern-js/runtime/react';
@@ -167,7 +169,7 @@ import { render } from '@modern-js/runtime/browser';
 const ModernRoot = createRoot();
 
 async function beforeRender() {
-   // todo
+   // some async request
 }
 
 beforeRender().then(() => {
@@ -175,34 +177,15 @@ beforeRender().then(() => {
 });
 ```
 
-#### 自定义 Bootstrap
-
-:::warning
-即将废弃，推荐使用自定义入口
-:::
-
-如果入口中存在 `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 提供的 Runtime 能力，而是完全由开发者自行定义页面的入口。
-
-当入口目录中存在 `index.[jt]sx`(即将废弃) 并且没有通过 `export default` 导出函数或者入口目录存在 `entry.[jt]sx` 并且未安装 `@modern-js/runtime` 依赖时，对应文件就会被识别为 webpack 或 Rspack 的 entry 模块。
-
 :::info
-使用 `entry.[jt]sx` 文件需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
+使用该功能需要开启需要开启 [source.enableCustomEntry](/configure/app/source/enable-custom-entry)。
 :::
 
-此时 Modern.js 不会自动生成入口代码，因此需要你自行将组件挂载到 DOM 节点上，例如:
+构建模式指的是不使用 Modern.js 提供的 Runtime 能力，只使用 Modern.js 构建能力的开发模式。当应用中未安装 `@modern-js/runtime` 依赖时，Modern.js 会认为当前应用所有的入口都是构建模式入口。
+
+此时，如果入口中存在 `entry.[jt]sx`，则该文件会被识别为 webpack 或 Rspack 的构建入口。此时，Modern.js 不会自动生成入口代码，你需要自行将组件挂载到 DOM 节点上，例如:
 
 ```js title=src/entry.tsx
 import React from 'react';
@@ -212,18 +195,21 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-这种方式等价于开启 Modern.js 的 [source.entries.disableMount](/configure/app/source/entries) 选项。当你使用这种方式时，**将无法使用 Modern.js 框架的运行时能力**，比如 `modern.config.js` 文件中的 `runtime` 配置将不会再生效。
+在构建模式入口中，**将无法使用 Modern.js 框架的运行时能力**，比如：
+- 约定式路由，即基于 `src/routes` 下文件的路由
+- 服务端渲染（SSR）
+- `modern.config.js` 文件中的 `runtime` 配置将不会再生效
 
-## 自定义入口配置
+## 在配置文件中指定入口
 
 在某些情况下，你可能需要自定义入口配置，而不是使用 Modern.js 提供的入口约定。
 
-比如你需要将一个非 Modern.js 项目迁移到 Modern.js，它并不是按照 Modern.js 的目录结构来搭建的。如果你要将它改成 Modern.js 约定的目录结构，可能会存在一定的迁移成本。这种情况下，你就可以使用自定义入口。
+比如你需要将一个非 Modern.js 应用迁移到 Modern.js，它并不是按照 Modern.js 的目录结构来搭建的。如果你要将它改成 Modern.js 约定的目录结构，会存在一定的迁移成本。这种情况下，你就可以使用自定义入口。
 
 Modern.js 提供了以下配置项，你可以在 [modern.config.ts](/configure/app/usage) 中配置它们：
 
 - [source.entries](/configure/app/source/entries)：用于设置自定义的入口对象。
-- [source.disableDefaultEntries](/configure/app/source/disable-default-entries)：用于关闭 Modern.js 默认的入口扫描行为。当你使用自定义入口时，项目的部分结构可能会恰巧命中 Modern.js 约定的目录结构，但你可能不希望 Modern.js 为你自动生成入口配置，开启该选项可以避免这个问题。
+- [source.disableDefaultEntries](/configure/app/source/disable-default-entries)：用于关闭 Modern.js 默认的入口扫描行为。当你使用自定义入口时，应用的部分结构可能会恰巧命中 Modern.js 约定的目录结构，但你可能不希望 Modern.js 为你自动生成入口配置，开启该选项可以避免这个问题。
 
 ### 示例
 
@@ -247,4 +233,37 @@ export default defineConfig({
 });
 ```
 
-注意，当你开启 `disableMount` 时，**将无法使用 Modern.js 框架的运行时能力**，比如 `modern.config.ts` 文件中的 `runtime` 配置将不会再生效。
+值得注意的是，默认情况下，Modern.js 认为通过配置指定的入口是**框架模式入口**，将自动生成真正的编译入口。如果你的应用是从 Webpack 或 Vite 等构建工具迁移到 Modern.js 框架时，你通常需要在入口配置中开启 `disableMount` 选项，此时 Modern.js 认为该入口是**构建模式入口**。
+
+
+## 弃用功能
+
+目前，如果入口所在的目录满足以下条件，也会成为应用入口。
+
+1. 具有 `index.[jt]sx?` 文件。
+2. 具有 `pages/` 目录。
+
+
+`pages/` 目录为 Modern.js 旧版本中的约定式路由，新版本中推荐使用 `routes/` 目录。
+
+`index.[jt]sx?` 在旧版本中支持应用自定义 Bootstrap 逻辑和构建模式入口，新版本中推荐使用 `entry.[jt]sx?` 代替。
+
+### 自定义 Bootstrap
+
+当入口中存在 `index.[jt]sx` 文件，并且当文件默认导出函数时，Modern.js 会将默认的 `bootstrap` 函数作为入参传入，并用导出的函数替代默认的 `bootstrap`，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+
+```tsx
+export default (App: React.ComponentType, bootstrap: () => void) => {
+  // do something before bootstrap...
+  initSomething().then(() => {
+    bootstrap();
+  });
+};
+```
+
+### 构建模式入口
+
+当入口目录中存在 `index.[jt]sx`(即将废弃) 并且没有通过 `export default` 导出函数时，该入口也将被认为是构建模式入口。
+
+
+

package/docs/zh/guides/get-started/_meta.json

@@ -1,7 +1 @@
-[
-  "introduction",
-  "quick-start",
-  "upgrade",
-  "glossary",
-  "tech-stack"
-]
+["introduction", "quick-start", "upgrade", "glossary", "tech-stack"]

package/docs/zh/guides/get-started/introduction.mdx

@@ -50,10 +50,10 @@ Modern.js 能为开发者提供极致的**开发体验（Development Experience
 
 - 🚀 **Rust 构建**：提供双构建工具支持，轻松切换到 Rspack 构建工具，编译飞快。
 - 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
-- 🏠 **一体化**：开发与生产环境 Web Server 唯一，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
+- 🏠 **一体化**：开发与生产环境 Web Server 逻辑一致，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
 - 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
 - 🌏 **周边生态**：自研状态管理、微前端、模块打包等周边需求。
-- 🕸 **多种路由模式**：包含自控路由、基于文件约定的路由（嵌套路由）等。
+- 🕸 **约定式路由**：使用基于文件约定的路由，帮助开发者快速搭建应用。
 
 ## 和其他框架的对比
 

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

@@ -74,7 +74,6 @@ export default defineConfig({
 - 集成 Modern.js Core，提供配置解析、插件加载等能力。
 - 集成 Modern.js Builder，提供构建能力。
 - 集成 Modern.js Server，提供开发和生产服务器相关能力。
-- 集成一些最为常用的插件，比如 `plugin-lint`、`plugin-data-loader` 等。
 
 `@modern-js/app-tools` 是基于 Modern.js 的插件体系实现的，本质上是一个插件，因此你需要在配置文件的 `plugins` 字段中注册 `appTools`：
 

package/docs/zh/guides/get-started/tech-stack.mdx

@@ -30,8 +30,6 @@ Modern.js 提供对 [Garfish](https://www.garfishjs.org/) 微前端框架开箱
 
 Modern.js 可以与社区中任意的状态管理库搭配使用，比如 [Redux](https://redux.js.org/)、[Jotai](https://jotai.org/)、[Zustand](https://docs.pmnd.rs/zustand)、[Valtio](https://valtio.pmnd.rs/) 等。
 
-Modern.js 也基于 Redux 封装了 Reduck 状态管理库，你可以参考 [「Reduck 状态管理」](/guides/topic-detail/model/quick-start)来使用。
-
 ## 包管理器
 
 Modern.js 可以与社区中任意的包管理器搭配使用，比如 [npm](https://www.npmjs.com/package/npm)、[yarn](https://classic.yarnpkg.com/lang/en/)、[pnpm](https://pnpm.io/) 或 [Bun](https://bun.sh/)。

package/docs/zh/guides/get-started/upgrade.mdx

@@ -38,9 +38,23 @@ import ReleaseNote from '@site-docs/components/release-note';
 
 :::tip
 当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。
-
 :::
 
+## 版本管理策略
+
+在 Modern.js 项目中，我们推荐所有官方提供的依赖都使用固定版本号，不使用 `^` 或 `~` 进行范围声明。例如：
+
+```json
+{
+  "dependencies": {
+    "@modern-js/app-tools": "x.y.z"
+  }
+}
+```
+
+这样可以确保依赖的版本是完全确定的，从而保证构建的一致性和可预测性。
+
+
 ## 锁定子依赖
 
 当项目某个子依赖出现问题，而 Modern.js 无法立即更新时，可以使用包管理器锁定子依赖版本。

package/docs/zh/guides/topic-detail/framework-plugin/_meta.json

@@ -7,4 +7,4 @@
   "extend",
   "plugin-api",
   "hook-list"
-]
+]

package/docs/zh/guides/topic-detail/generator/_meta.json

@@ -14,4 +14,4 @@
     "name": "plugin",
     "label": "generator-plugin"
   }
-]
+]

package/docs/zh/guides/topic-detail/generator/create/_meta.json

@@ -1,5 +1 @@
-[
-  "use",
-  "option",
-  "config"
-]
+["use", "option", "config"]

package/docs/zh/guides/topic-detail/generator/new/_meta.json

@@ -1,5 +1 @@
-[
-  "use",
-  "option",
-  "config"
-]
+["use", "option", "config"]

package/docs/zh/guides/topic-detail/generator/plugin/_meta.json

@@ -8,4 +8,4 @@
     "name": "api",
     "label": "API"
   }
-]
+]

package/docs/zh/guides/troubleshooting/_meta.json

@@ -1,6 +1 @@
-[
-  "dependencies",
-  "cli",
-  "builder",
-  "hmr"
-]
+["dependencies", "cli", "builder", "hmr"]

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.58.2",
+  "version": "2.58.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.58.2"
+    "@modern-js/sandpack-react": "2.58.3"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.58.2"
+    "@modern-js/builder-doc": "^2.58.3"
   },
   "devDependencies": {
     "@rspress/shared": "1.27.0",
@@ -39,7 +39,7 @@
     "rspress": "1.27.0",
     "ts-node": "^10.9.1",
     "typescript": "^5",
-    "@modern-js/builder-doc": "2.58.2"
+    "@modern-js/builder-doc": "2.58.3"
   },
   "scripts": {
     "dev": "rspress dev",

package/rspress.config.ts

@@ -1,6 +1,6 @@
 import path from 'path';
-import { defineConfig } from 'rspress/config';
 import type { NavItem } from '@rspress/shared';
+import { defineConfig } from 'rspress/config';
 
 const { version } = require('./package.json');
 

package/src/components/ContentCard/index.tsx

@@ -1,5 +1,5 @@
-import type React from 'react';
 import cl from 'classnames';
+import type React from 'react';
 import { withBase } from 'rspress/runtime';
 import styles from './index.module.scss';
 

package/src/components/Sandpack/index.tsx

@@ -2,7 +2,7 @@ import ModernSandpack, {
   type ModernSandpackProps,
 } from '@modern-js/sandpack-react';
 import React, { type PropsWithChildren } from 'react';
-import { useDark, NoSSR } from 'rspress/runtime';
+import { NoSSR, useDark } from 'rspress/runtime';
 
 import './index.css';
 

package/src/components/ShowcaseList/index.tsx

@@ -1,5 +1,5 @@
-import { useShowcases } from './useShowcases';
 import styles from './index.module.scss';
+import { useShowcases } from './useShowcases';
 
 const getDomain = (url: string) => new URL(url).hostname;
 

package/src/i18n/index.ts

@@ -1,4 +1,4 @@
-import { withBase, useLang } from 'rspress/runtime';
+import { useLang, withBase } from 'rspress/runtime';
 import { EN_US } from './enUS';
 import { ZH_CN } from './zhCN';
 

package/src/pages/index.tsx

@@ -1,11 +1,11 @@
 /* eslint-disable react/no-unescaped-entities */
 import clsx from 'clsx';
-import { useLang, Helmet, useLocation } from 'rspress/runtime';
 import { useEffect } from 'react';
+import { Helmet, useLang, useLocation } from 'rspress/runtime';
 import ContentCard from '../components/ContentCard';
-import SecondaryTitle from '../components/SecondaryTitle';
 import { FeatureLayout } from '../components/FeatureLayout';
 import Footer from '../components/Footer';
+import SecondaryTitle from '../components/SecondaryTitle';
 import { useI18n, useUrl } from '../i18n';
 import styles from './index.module.scss';