@modern-js/main-doc 2.10.0 → 2.11.0

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/en/tutorials/first-app/c06-model.mdx

@@ -195,18 +195,10 @@ const Item = ({
 export default Item;
 ```
 
-Next, we modify `src/routes/page.tsx` to pass more parameters to the `<Item>` component:
+Next, we add `src/routes.page.loader` and modify `src/routes/page.tsx` to pass more parameters to the `<Item>` component:
 
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-import { useModel } from '@modern-js/runtime/model';
-import { useLoaderData } from '@modern-js/runtime/router';
-import { List } from 'antd';
-import { name, internet } from 'faker';
-import Item from '../components/Item';
-import contacts from '../models/contacts';
-
-type LoaderData = {
+```tsx title="src/routes/page.loader.ts"
+export type LoaderData = {
   code: number;
   data: {
     name: string;
@@ -215,7 +207,7 @@ type LoaderData = {
   }[];
 };
 
-export const loader = async (): Promise<LoaderData> => {
+export default async (): Promise<LoaderData> => {
   const data = new Array(20).fill(0).map(() => {
     const firstName = name.firstName();
     return {
@@ -231,6 +223,17 @@ export const loader = async (): Promise<LoaderData> => {
     data,
   };
 };
+```
+
+```tsx title="src/routes/page.tsx"
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { useLoaderData } from '@modern-js/runtime/router';
+import { List } from 'antd';
+import { name, internet } from 'faker';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+import type { LoaderData } from './page.loader';
 
 function Index() {
   const { data } = useLoaderData() as LoaderData;

package/docs/en/tutorials/first-app/c07-container.mdx

@@ -15,24 +15,8 @@ Because the two pages need to share the same set of state (point of contact tabu
 
 Modern.js support obtaining data through Data Loader in `layout.tsx`, we first move the data acquisition part of the code to `src/routes/layout.tsx`:
 
-```tsx
-import { name, internet } from 'faker';
-import {
-  Outlet,
-  useLoaderData,
-  useLocation,
-  useNavigate,
-} from '@modern-js/runtime/router';
-import { useState } from 'react';
-import { Radio, RadioChangeEvent } from 'antd';
-import { useModel } from '@modern-js/runtime/model';
-import contacts from '../models/contacts';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import '../styles/utils.css';
-
-type LoaderData = {
+```ts title="src/routes/layout.loader.ts"
+export type LoaderData = {
   code: number;
   data: {
     name: string;
@@ -41,7 +25,7 @@ type LoaderData = {
   }[];
 };
 
-export const loader = async (): Promise<LoaderData> => {
+export default async (): Promise<LoaderData> => {
   const data = new Array(20).fill(0).map(() => {
     const firstName = name.firstName();
     return {
@@ -56,6 +40,25 @@ export const loader = async (): Promise<LoaderData> => {
     data,
   };
 };
+```
+
+```tsx title="src/routes/layout.tsx"
+import { name, internet } from 'faker';
+import {
+  Outlet,
+  useLoaderData,
+  useLocation,
+  useNavigate,
+} from '@modern-js/runtime/router';
+import { useState } from 'react';
+import { Radio, RadioChangeEvent } from 'antd';
+import { useModel } from '@modern-js/runtime/model';
+import contacts from '../models/contacts';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import '../styles/utils.css';
+import type { LoaderData } from './layout.loader';
 
 export default function Layout() {
   const { data } = useLoaderData() as LoaderData;

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

@@ -4,31 +4,4 @@ sidebar_position: 8
 ---
 # *.[server|node].[tj]sx
 
-应用项目中使用，用于放置服务端代码，一般有以下两个作用：
-
-1. 当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。
-
-2. 在使用 [data loader](/guides/basic-features/data-fetch) 时，需要将服务端的依赖从该文件中做重导出
-
-```tsx
-// routes/user/avatar.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-import { readFile } from './utils.server';
-
-type ProfileData = {
-  /* some type declarations */
-};
-
-export const loader = async (): ProfileData => {
-  const profile = await readFile('profile.json');
-  return profile;
-};
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-
-// routes/user/utils.server.ts
-export * from 'fs-extra';
-```
+应用项目中使用，用于放置服务端代码，当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。

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',
+};
 ```