@modern-js/main-doc 0.0.0-next-1679558946601 → 0.0.0-next-1679666804179

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

@@ -4,26 +4,29 @@ sidebar_position: 1
 
 # Entries
 
-Entries are Modern.js default file convention, and each entry in the project is a separate page, corresponding to a server level route.
+Through this chapter, you can learn about the entry convention in Modern.js and how to customize the entry.
 
-Many configurations, such as HTML templates, Meta information, whether SSR is enabled, SSG, server level routing rules are divided by the entry dimension.
+## What is an Entry
+
+**Entry is the starting module of a page.**
+
+In the Modern.js project, each entry corresponds to an independent page, and also corresponds to a server route. By default, Modern.js will automatically determine the entry of the page based on the directory convention, and also supports customizing the entry through configuration items.
+
+Many configuration items provided by Modern.js are divided by entry, such as page title, HTML template, page Meta information, whether to enable SSR/SSG, server-side routing rules, etc.
 
 ## Single Entry and Multiple Entries
 
-Modern.js initialization project is a single entry, the project structure is as follows:
+The project initialized by Modern.js is single-entry (SPA), and the project structure is as follows:
 
 ```
 .
 ├── src
-│   ├── modern-app-env.d.ts
 │   └── routes
 │       ├── index.css
 │       ├── layout.tsx
 │       └── page.tsx
 ├── package.json
 ├── modern.config.ts
-├── pnpm-lock.yaml
-├── README.md
 └── tsconfig.json
 ```
 
@@ -35,17 +38,16 @@ Modern.js can easily switch from single entry to multiple entry. You can execute
 ? Entry name: new-entry
 ```
 
-After execution, the `src/` directory will become the following structure:
+After execution, Modern.js will automatically generate a new entry directory, and you can see that the `src/` directory has the following structure:
 
-```
+```bash
 .
-├── modern-app-env.d.ts
-├── myapp
+├── myapp     # Original entry
 │   └── routes
 │       ├── index.css
 │       ├── layout.tsx
 │       └── page.tsx
-└── new-entry
+└── new-entry  # New entry
     └── routes
         ├── index.css
         ├── layout.tsx
@@ -56,65 +58,154 @@ The original code was moved to the directory with the same name as the `name` in
 
 After executing `pnpm run dev`, you can see that a `/new-entry` route has been added, and the migrated code route has not changed.
 
-:::note
-Modern.js will use the directory with the same name as the `name` in the `package.json` as the main entry, the default route is `/`, and the default route for other entries is `/{entryName}`.
+:::tip
+Modern.js will use the entry with the same name as the `name` field in the package.json file as the main entry, the route of the main entry is `/`, and the route of other entries is `/{entryName}`.
+
+For example, when `name` in package.json is `myapp`, `src/myapp` will be used as the main entry of the project.
 
 :::
 
-## Entry conditions
+## Entry Type
 
-By default, the Modern.js entry currently scans the file under `src/`, identifies the entry, and generates the corresponding server level route.
+Different entry types have different compile and run-time behaviors. When creating a project in Modern.js, developers can manually choose to create a project in **framework mode** or **build mode**. After the creation is complete, you can see that the project template files for different modes are different.
+
+By default, Modern.js will scan the files under `src/` before starting the project, identify the entry, and generate the corresponding server-side route.
 
 :::tip
-You can change the entry directory to another directory by [source.entriesDir](/configure/app/source/entries-dir).
+You can change the entry directory to another directory through [source.entriesDir](/configure/app/source/entries-dir).
 
 :::
 
-Not all first-level directories under `src/` will become project entrances. The directory where the entry is located must meet one of the following four conditions:
+Not all first-level directories under `src/` will become project entries, and the directory where the entry is located must meet one of the following four conditions:
 
-1. Directory with `routes/`
-2. Has the `App.[jt]sx?` file
-3. With `index.[jt]sx?` file
-4. With `pages/` directory (compatible Modern.js 1.0)
+1. Have a `routes/` directory
+2. Has `App.[jt]sx?` file
+3. Has `index.[jt]sx?` file
+4. Has a `pages/` directory (Modern.js 1.0 compatible)
 
-When the `src/` directory satisfies the entry feature, the Modern.js considers the current project to be a single entry application.
+When the `src/` directory meets the entry characteristics, Modern.js will consider the current project as a single-entry application.
 
 :::tip
-Single entry The default entry name is `main`.
+In single-entry applications, the default entry is named `main`.
 
 :::
 
-When the project is not a single-entry application, Modern.js further look at the first-level directory under `src/`.
+When the project is not a single-entry application, Modern.js will further check the first-level directory under `src/`.
+
+### Framework Mode Entry
 
-## Difference between entries
+Framework mode refers to the need to use the capabilities of the Modern.js framework, such as Router, SSR, integrated calls, etc. Under this kind of entry agreement, the entry defined by the developer is not the real Webpack compilation entry. Modern.js will generate an encapsulated entry when it starts, and the real entry can be found in `node_modules/.modern/{entryName}/index.js`.
 
-Entries to different conventions have different behaviors.
+#### Conventional Routing
 
-### routes
+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 the entry is the `routes/` convention, Modern.js will scan the files under `routes` at startup, and automatically generate the client route based on the file convention(react-router).
+For details, please refer to [routing](/guides/basic-features/routes).
 
-For details, please refer to [Routing](/guides/basic-features/routes).
+#### Custom Routing
 
-### App
+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.
 
-If the entry is the `App.[jt]sx?` convention, 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).
 
-For details, please refer to [Routing](/guides/basic-features/routes).
+#### Custom App
 
-### Index
+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:
 
-Typically, the above two modes are sufficient, but when developers need to take over the React mount logic themselves, or take over the Webpack entry entirely, the `index.[jt]sx?`convention can be used.
+```tsx
+import ReactDOM from 'react-dom/client';
+import { bootstrap } from '@modern-js/runtime';
 
-If the entry is the `index.[jt]sx?` convention, the Modern.js determines the build behavior based on whether the file has a default component export.
+export default (App: React.ComponentType) => {
+  // do something before bootstrap...
+  bootstrap(App, 'root', undefined, ReactDOM);
+};
+```
+
+:::warning
+Since the bootstrap function needs to be compatible with React17 and React18, you need to manually pass in ReactDOM parameters when calling the bootstrap function.
+
+:::
+
+The content of the file generated by Modern.js is as follows:
 
-For details, please refer to [customized App](/guides/concept/entries#自定义-app).
+```js
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import customBootstrap from '@_edenx_src/index.tsx';
+import App from '@_edenx_src/App';
+import { router, state } from '@edenx/runtime/plugins';
 
-## configuration
+const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
+const MOUNT_ID = 'root';
 
-In Modern.js, you can manually configure the entry in `modern.config.[jt]s`, in addition to using the file convention to generate the entry.
+let AppWrapper = null;
+
+function render() {
+  AppWrapper = createApp({
+    // plugin parameters for runtime...
+  })(App);
+  if (IS_BROWSER) {
+    customBootstrap(AppWrapper);
+  }
+  return AppWrapper;
+}
+
+AppWrapper = render();
+
+export default AppWrapper;
+```
+
+### Build Mode Entry
+
+Build mode refers to the ability not to use any Modern.js runtime, and the developer defines the entry of the project Webpack completely by himself.
+
+If `index.[jt]sx` exists in the entry and there is no default export function, then this file is the real Webpack entry file. This is similar to [Create React App](https://github.com/facebook/create-react-app), you need to mount components to DOM nodes, add hot update code, etc. For example:
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+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.
+
+## Custom Entry
+
+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.
+
+In this case, instead of generating the entry using file conventions, you can manually configure the entry in `modern.config.[jt]s`.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      // Specify a new entry named entry_customize
+      entry_customize: './src/home/test/index.ts',
+    },
+    // Disable default ingress scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Disable Default Entries
+
+When using a custom entry, part of the project structure may happen to hit the directory convention of Modern.js, but in fact this part of the directory is not the real entry.
+
+Modern.js provides `disableDefaultEntries` config to disable default entry scanning rules. When you need to customize the entry, you generally need to use `disableDefaultEntries` with `entries`. In this way, some existing projects can be quickly migrated without modifying the directory structure.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```
 
 :::tip
-Details can be found in [source.entries](/configure/app/source/entries).
+For detailed usage, please refer to [source.entries](/configure/app/source/entries) and [source.disableDefaultEntries](/configure/app/source/disable-default-entries).
 
 :::

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

@@ -191,8 +191,8 @@ foo
 
 - Functionality: Reset some file states before exiting the process.
 - Execution phase: Before the process exits.
-- Hook model: AsyncWorkflow
-- Type: `AsyncWorkflow<void, void>`
+- Hook model: Workflow
+- Type: `Workflow<void, void>`
 - Example usage:
 
 ```ts
@@ -209,6 +209,10 @@ export default (): CliPlugin => ({
 });
 ```
 
+:::tip
+Since the callback function when exiting the process in Node.js is synchronous, the type of `beforeExit` Hook is `Workflow` and cannot perform asynchronous operations.
+:::
+
 ### `beforeDev`
 
 - Functionality: Tasks before running the main dev process.
@@ -442,7 +446,7 @@ export default (): CliPlugin => ({
       modifyEntryRuntimePlugins({ entrypoint, plugins }) {
         const name = 'customPlugin';
         const options = {
-          /** 可序列化的内容 */
+          /** serializable content */
         };
 
         return {

package/docs/en/guides/topic-detail/model/typescript-best-practice.mdx

@@ -47,7 +47,7 @@ export const bar = model<State>('bar').define({
     data: '',
   },
   computed: {
-    // 为 fooState 指定类型
+    // specify the type for fooState
     withFoo: [foo, (state, fooState: FooState) => state.data + fooState.data],
   },
 });
@@ -62,11 +62,11 @@ Reduck provides a set of utility types for getting Model type information:
 
 ```ts
 export const foo = model<State2>('foo').define({
-  // 省略
+  // skip some codes
 });
 
-// 获取 foo 的 State 类型
+// get the State type of foo
 let fooActions: GetModelActions<typeof foo>;
-// 获取 foo 的 Actions 类型
+// get the Actions type of foo
 let fooState: GetModelState<typeof foo>;
 ```

package/docs/zh/configure/app/source/config-dir.mdx

@@ -1,8 +1,8 @@
 ---
-title: source.configDir
 sidebar_label: configDir
 ---
-# configDir
+
+# source.configDir
 
 - **类型：** `string`
 - **默认值：** `./config`

package/docs/zh/configure/app/source/design-system.mdx

@@ -1,11 +1,11 @@
 ---
-title: source.designSystem
 sidebar_label: designSystem
 ---
-# designSystem
+
+# source.designSystem
 
 - **类型：** `Object`
-- **默认值：**见下方配置详情。
+- **默认值：** 见下方配置详情。
 
 :::caution 注意
 需要先通过 `pnpm run new` 启用 Tailwind CSS 功能。

package/docs/zh/configure/app/source/disable-default-entries.mdx

@@ -1,22 +1,16 @@
 ---
-title: source.disableDefaultEntries
 sidebar_label: disableDefaultEntries
 ---
-# disableDefaultEntries
+
+# source.disableDefaultEntries
 
 - **类型：** `boolean`
 - **默认值：** `false`
 
-关闭根据项目目录结构自动识别应用构建入口的功能，默认情况下，Modern.js 会根据项目目录结构得到对应构建入口。
+用于关闭基于目录结构来自动识别页面入口的功能。
 
 :::info
-默认情况下，Modern.js 会根据项目目录结构得到对应入口信息。具体可参考[入口](/guides/concept/entries)。
-配置关闭改机制后，需要使用 [`source.entries`](/configure/app/source/entries) 配置自定义入口。
-
-:::
-
-:::warning 警告
-推荐按照 Modern.js 提供的目录规范组织代码可以更好使用框架的功能，避免一些冗余的配置。
+默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，具体可参考[入口](/guides/concept/entries)。
 
 :::
 
@@ -29,3 +23,10 @@ export default defineConfig({
   },
 });
 ```
+
+关闭默认行为后，你需要使用 [`source.entries`](/configure/app/source/entries) 配置自定义的入口。
+
+:::warning
+我们推荐使用 Modern.js 提供的目录规范来组织代码，从而更好地使用框架功能，避免一些冗余的配置。
+
+:::

package/docs/zh/configure/app/source/disable-entry-dirs.mdx

@@ -1,9 +1,8 @@
 ---
-title: source.disableEntryDirs
-
 sidebar_label: disableEntryDirs
 ---
-# disableEntryDirs
+
+# source.disableEntryDirs
 
 - **类型：** `string[]`
 - **默认值：** `[]`

package/docs/zh/configure/app/source/enable-async-entry.mdx

@@ -1,13 +1,13 @@
 ---
-title: source.enableAsyncEntry
 sidebar_label: enableAsyncEntry
 ---
-# enableAsyncEntry
+
+# source.enableAsyncEntry
 
 - **类型：** `boolean`
 - **默认值：** `false`
 
-该选项用于 webpack 模块联邦 (Module Federation）场景。
+该选项用于 webpack 模块联邦（Module Federation）场景。
 
 开启此选项后，Modern.js 会通过 Dynamic Import 来包裹自动生成的入口文件（asynchronous boundary），使页面代码可以消费模块联邦生成的远程模块。
 

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

@@ -1,14 +1,13 @@
 ---
-title: source.entriesDir
-
 sidebar_label: entriesDir
 ---
-# entriesDir
+
+# source.entriesDir
 
 - **类型：** `string`
 - **默认值：** `./src`
 
-默认会根据 `src` 目录识别应用入口，可通过该选项自定义应用入口的识别目录。
+Modern.js 默认会扫描 `src` 目录来识别页面入口，你可以通过该选项自定义页面入口的识别目录。
 
 例如，当配置与目录结构如下时：
 
@@ -25,16 +24,16 @@ export default defineConfig({
 └── src
     └── pages
         ├── a
-        │   └── App.jsx
+        │   └── App.tsx
         └── b
-            └── App.jsx
+            └── App.tsx
 ```
 
-Modern.js 会根据 `./src/pages` 目录结构生成构建入口 `a` 和入口 `b`，结果如下：
+Modern.js 会扫描 `./src/pages` 目录，自动生成构建入口 `a` 和入口 `b`，结果如下：
 
 ```js
- {
-   a: './src/pages/a/App.jsx',
-   b: './src/pages/b/App.jsx'
- }
+const entry = {
+  a: './src/pages/a/App.tsx',
+  b: './src/pages/b/App.tsx',
+};
 ```

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

@@ -1,19 +1,36 @@
 ---
-title: source.entries
 sidebar_label: entries
 ---
-# entries
 
-- **类型：** `Object = { [ entryName: string ]: string | Object }`
-- **默认值：** 根据当前项目目录结构动态结算出的默认入口对象。
+# source.entries
 
-对于大部分场景，Modern.js 根据目录结构自动生成的入口能满足大部分业务需求。具体可参考[入口](/guides/concept/entries)。
+- **类型：**
 
-如需自定义构建入口时，可以通过该选项指定。
+```ts
+type Entries = Record<
+  string,
+  | string
+  | {
+      entry: string;
+      disableMount?: boolean;
+    }
+>;
+```
+
+- **默认值：** 根据当前项目的目录结构计算出的入口对象。
+
+用于配置自定义的页面入口。
+
+:::tip 何时使用
+对于大部分场景，Modern.js 根据目录结构自动生成的入口已经可以满足需求，具体可参考[入口](/guides/concept/entries)。
+
+如果你需要自定义页面入口时，可以通过该选项进行设置。
+
+:::
 
 ## String 类型
 
-当值为 `string` 类型时，为入口的文件路径:
+当 `entries` 对象的 value 为 `string` 类型时，表示入口模块的文件路径:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -22,13 +39,15 @@ export default defineConfig({
   source: {
     entries: {
       // 指定一个名称为 entry_customize 的新入口
-      entry_customize: './src/home/test/index.js',
+      entry_customize: './src/home/test/index.ts',
     },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
   },
 });
 ```
 
-默认情况下，配置的入口等价于 `App.[jt]sx`，即指定的入口文件只需要导出应用的根组件。
+默认情况下，配置的入口等价于 `App.[jt]sx`，即指定的入口文件**只需要导出应用的根组件**。
 
 例如以下目录结构：
 
@@ -41,17 +60,19 @@ export default defineConfig({
 └── package.json
 ```
 
-结合上面默认入口机制的内容，Modern.js 在分析上述目录结构时，不会得到任何默认入口。
+上述目录不符合 Modern.js 的目录结构约定，因此，Modern.js 在分析目录结构时，不会得到任何默认入口。
 
 在不想改变目录结构的情况下（如项目迁移），可以通过 `source.entries` 自定义入口：
 
-```ts title="modern.config.js"
+```ts title="modern.config.ts"
 export default defineConfig({
   source: {
     entries: {
       home: './src/entry/home.tsx',
       chat: './src/entry/chat.tsx',
     },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
   },
 });
 ```
@@ -61,7 +82,7 @@ export default defineConfig({
 当值为 `Object` 时，可配置如下属性：
 
 - `entry`：`string`，入口文件路径。
-- `disableMount`：`boolean = false`，关闭 Modern.js 生成入口代码的行为。
+- `disableMount`：`boolean = false`，关闭 Modern.js 自动生成入口代码的行为。
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -71,25 +92,65 @@ export default defineConfig({
     entries: {
       entry_customize: {
         // 入口文件路径
-        entry: './src/home/test/App.jsx',
+        entry: './src/home/test/index.tsx',
+      },
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### 禁用入口文件生成
+
+默认情况下，配置的入口等价于 `App.[jt]sx`，Modern.js 会自动生成一个入口文件来引用你配置的入口。
+
+如果你希望禁用 Modern.js 自动生成入口文件的逻辑，可以将 `disableMount` 属性设置为 `true`。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      entry_customize: {
+        entry: './src/home/test/index.tsx',
+        disableMount: true,
       },
+    },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### 约定式路由
+
+如果你需要为某个自定义入口启用约定式路由，可以将 `entry` 设置为目录路径：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
       // 启用约定式路由
       entry_spa: {
         // 约定式路由的入口路径必须设置为目录
         entry: './src/about',
       },
     },
+    // 禁用默认入口扫描
+    disableDefaultEntries: true,
   },
 });
 ```
 
-默认情况下，配置的入口等价于 `App.[jt]sx`，如果希望该入口等价于构建模式下的入口，可以将属性 `disableMount` 设置为 `true`。
+## 入口合并规则
 
-## 自定义入口和默认入口合并
+在设置 `source.entries` 后，如果没有设置 `disableDefaultEntries: true`，Modern.js 会将自定义入口与分析目录结构得到的入口合并。
 
-在指定 `source.entries` 后，Modern.js 会将用户自定义的入口与分析目录结构得到的默认入口合并。合并规则为：
+合并规则为：
 
-比较自定义入口设置的入口路径和默认入口路径，当入口路径一致时，自定义入口会覆盖默认入口。
+- 比较自定义入口设置的入口路径和默认入口路径，当入口路径一致时，自定义入口会覆盖默认入口。
 
 例如以下目录结构:
 
@@ -97,13 +158,13 @@ export default defineConfig({
 .
 ├── src
 │   ├── chat
-│   │   └── App.jsx
+│   │   └── App.tsx
 │   └── home
-│       └── index.js
+│       └── index.ts
 └── package.json
 ```
 
-Modern.js 分析 `src/` 目录，得到默认入口 `chat` 和 `home`。当用户在 `modern.config.js` 文件中配置如下时：
+Modern.js 会分析 `src/` 目录，得到默认入口 `chat` 和 `home`。当用户在 `modern.config.ts` 文件中配置如下时：
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -111,7 +172,7 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   source: {
     entries: {
-      index: './src/home/index.js',
+      index: './src/home/index.ts',
     },
   },
 };
@@ -119,5 +180,5 @@ export default defineConfig({
 
 可以看到自定义入口 `index` 的路径和默认入口 `home` 的路径一致，在合并的过程中，`index` 会覆盖掉 `home`，最终入口如下：
 
-- `chat -> ./src/chat/App.jsx`
-- `index -> ./src/home/index.js`
+- `chat -> ./src/chat/App.tsx`
+- `index -> ./src/home/index.ts`

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

@@ -1,21 +1,25 @@
 ---
-title: tools.esbuild
 sidebar_label: esbuild
 ---
-# esbuild
+
+# tools.esbuild
 
 - **类型：** `Object`
 - **默认值：** `undefined`
 
 ## 介绍
 
-:::tip esbuild 介绍
 [esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。在代码压缩方面，相比 webpack 内置的 terser 压缩器，esbuild 在性能上有数十倍的提升。
 
-:::
-
 Modern.js 提供了 esbuild 插件，让你能使用 esbuild 代替 babel-loader、ts-loader 和 terser 等库进行代码编译和压缩。在大型工程中开启后，**可以大幅度减少代码编译和压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
 
+:::tip 推荐使用 SWC
+相较于 esbuild，我们更推荐使用 SWC 来编译和压缩代码，因为 SWC 支持更多的语法特性、拥有更好的代码压缩率，并且产物具备更好的兼容性。
+
+因此，我们建议你使用 SWC 而不是 esbuild，用法请参考 [tools.swc](/configure/app/tools/swc)。
+
+:::
+
 ## 配置项
 
 你可以通过 `tools.esbuild` 配置项来设置 esbuild 编译行为。