@modern-js/main-doc 2.0.0-beta.4 → 2.0.0-beta.5

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.0.0-beta.4 build /github/workspace/packages/toolkit/main-doc
+> @modern-js/main-doc@2.0.0-beta.4 build /Users/bytedance/github/modern.js/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/dev.md

@@ -2,10 +2,10 @@
 sidebar_position: 1
 ---
 
-# dev
+# dev / start
 
 ```bash
-Usage: modern dev [options]
+Usage: modern dev / modern start [options]
 
 Development commands
 
@@ -19,8 +19,13 @@ Options:
 
 `modern dev` start a development server，watch file change，default support React Fast Refresh:
 
+`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
+
 ```bash
-App running at:
+$ modern dev
+
+info    Starting dev server...
+info    App running at:
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/inspect.md

@@ -5,31 +5,56 @@ sidebar_position: 7
 ```
 Usage: modern inspect [options]
 
-inspect internal webpack config
-
 Options:
   --env <env>           view the configuration in the target environment (default: "development")
   --output <output>     Specify the path to output in the dist (default: "/")
-  --no-console          Do not output the full result in shell
   --verbose             Show the full function in the result
   -c --config <config>  configuration file path, which can be a relative path or an absolute path
   -h, --help            show command help
 ```
 
-`modern inspect` command used to view the full webpack configuration of the project.
+`modern inspect` command used to view the [Modern.js Builder config](https://modernjs.dev/builder/en/guide/basic/builder-config.html) and webpack config of the project.
+
+After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
+
+- `builder.config.js`: The Modern.js Builder config to use at build time.
+- `webpack.config.web.js`: The webpack config used by to use at build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
 
-Executing the command `npx modern inspect` in the project will output the webpack configuration on the shell, and will also generate a `webpack.client.inspect.js` file in the project's `dist` directory, which developers can open and view manually.
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+```
 
 ## Configuration Env
 
-By default, the webpack configuration of the development environment is output. And the `env` option can be used to output the configuration of the production environment:
+By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
 
 ```bash
 modern inspect --env production
 ```
 
-## Configuration Type
+## Verbose content
+
+By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
+
+```bash
+modern inspect --verbose
+```
 
 ### SSR Configuration
 
-If the project has SSR enable, an additional `webpack.ssr.inspect.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
+If the project has enabled SSR, an additional `webpack.config.node.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/serve.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 6
+---
+
+```bash
+Usage: modern serve [options]
+
+run server
+
+Options:
+  -c --config <config>  configuration file path, which can be a relative path or an absolute path
+  -h, --help            show command help
+  --api-only            only run API service
+```
+
+Usually use the `modern serve` command to enable project run in the production environment, and you need to execute the [`build'](/docs/apis/app/commands/build) command in advance to build the product.
+
+By default, the project will run in `localhost:8080`, you can modify the Server port number with `server.port`:
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  }
+})
+```
+
+import CommandTip from '@site-docs-en/components/command-tip.md'
+
+<CommandTip />
+
+

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/server.md

@@ -0,0 +1,31 @@
+---
+title: "*.[server|node].[tj]sx"
+sidebar_position: 8
+---
+
+Used in application projects to place server side code, it generally has the following two functions：
+
+1. When `*.tsx` and `*. [server|node].tsx` coexist, rendering on the server side will give preference to the `*. [server|node].tsx` file instead of the `*.tsx` file.
+
+2. When using [data loader](/docs/guides/basic-features/data-fetch), the server-side dependencies need to be re-exported from this file
+
+```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';
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/bootstrap.md

@@ -2,7 +2,7 @@
 title: bootstrap
 ---
 
-Used to start and mount App, usually without manual calls。This API is only required when using [Custom App](/docs/guides/advanced-features/custom-app).
+Used to start and mount App, usually without manual calls。This API is only required when using [Custom App](/docs/guides/concept/entries#自定义-app).
 
 ## Usage
 
@@ -41,7 +41,6 @@ type BootStrap<T = unknown> = (
 ```tsx
 import ReactDOM from 'react-dom/client'
 import { createApp, bootstrap } from '@modern-js/runtime';
-import { router, state } from '@modern-js/runtime/plugins';
 
 function App() {
   return <div>Hello Modern.js</div>;
@@ -49,7 +48,9 @@ function App() {
 
 const WrappedApp = createApp({
   // customized plugin
-  plugins: [router({}), state({})],
+  plugins: [
+    customPlugin(),
+  ],
 })(App);
 
 bootstrap(WrappedApp, 'root', undefined, ReactDOM);

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/create-app.md

@@ -2,7 +2,7 @@
 title: createApp
 ---
 
-Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/docs/guides/advanced-features/custom-app).
+Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/docs/guides/concept/entries#自定义-app).
 
 ## Usage
 
@@ -40,8 +40,7 @@ function App() {
 
 export default createApp({
   plugins: [
-    router({}),
-    state({}),
+    customPlugin()
   ]
 })(App);
 ```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/use-module-apps.md

@@ -7,7 +7,7 @@ Returns the React components of all micro-front-end sub-applications for freely
 ## Usage
 
 ```tsx
-import { useModuleApps } from '@modern/plugin-garfish';
+import { useModuleApps } from '@modern-js/runtime/garfish';
 ```
 
 :::info Turn on

package/en/docusaurus-plugin-content-docs/current/components/init-app.md

@@ -15,7 +15,7 @@ After create the project, Modern.js automatically installs dependency and create
 You can run the following command in the directory of the new project：
 pnpm run dev          # Run and debug the project according to the requirements of the development environment
 pnpm run build        # Build the project according to the requirements of the product environment
-pnpm run start        # Run the project according to the requirements of the product environment
+pnpm run serve        # Run the project according to the requirements of the product environment
 pnpm run lint         # Check and fix all codes
 pnpm run new          # Create more project elements, such as application portals
 ```

package/en/docusaurus-plugin-content-docs/current/configure/app/builder-plugins.md

@@ -0,0 +1,70 @@
+---
+title: builderPlugins
+sidebar_position: 10
+---
+
+- Type: `BuilderPlugin[]`
+- Default: `[]`
+
+Used to configure the Modern.js Builder plugin.
+
+Modern.js Builder is the build engine of Modern.js, please read [Builder](/docs/guides/basic-features/builder) for background. If you want to know how to write Builder plugins, you can refer to [Modern.js Builder - Introduce to Plugin](https://modernjs.dev/builder/en/plugins/introduction.html).
+
+## Precautions
+
+This option **is used to configure the Modern.js Builder plugins**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [plugins](docs/configure/app/builder-plugins) to configure Modern.js framework plugins.
+- Use [tools.webpack](/docs/configure/app/tools/webpack) or [tools.webpackChain](/docs/configure/app/tools/webpack-chain) to configure webpack plugins.
+- Use [tools.babel](/docs/configure/app/tools/babel) to configure babel plugins.
+
+## When to use
+
+In most scenarios, we recommend you to use the Modern.js framework plugin, which can be registered through the [plugins](docs/configure/app/plugins) config. Because the API provided by the framework plugin is richer and more capable, while the API provided by the Builder plugin can only be used to build scenes.
+
+When you need to reference some existing Builder plugins (and there is no related capability in Modern.js), or reuse Builder plugins between different frameworks, you can use the `builderPlugins` field to register them.
+
+## Example
+
+Below is an example of using the Builder plugin.
+
+### Using plugins on npm
+
+To use a plugin on npm, you need to install the plugin through the package manager and import it.
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [MyBuilderPlugin()],
+});
+```
+
+### Using local plugins
+
+Use the plugin in the local code repository, you can import it directly through the relative path import.
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from './plugin/myBuilderPlugin';
+
+export default defineConfig({
+  builderPlugins: [MyBuilderPlugin()],
+});
+```
+
+### Plugin configuration items
+
+If the plugin provides some custom configuration options, you can pass in the configuration through the parameters of the plugin function.
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    MyBuilderPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/en/docusaurus-plugin-content-docs/current/configure/app/dev/with-master-app.md

@@ -29,4 +29,3 @@ export default defineConfig({
 - moduleApp: `string` Online address of the main application.
 - moduleName: `Contact` The name of the child app (needs to match the module name registered in the main app)。
 
-For detailed usage, please refer to [Micro Front-end Sub-Application](/docs/guides/topic-detail/micro-frontend/debugging)。

package/en/docusaurus-plugin-content-docs/current/configure/app/plugins.md

@@ -3,18 +3,24 @@ title: plugins
 sidebar_position: 9
 ---
 
-* Type: `CliPlugin[]`
-* Default: `[]`
+- Type: `CliPlugin[]`
+- Default: `[]`
 
-Used to configure custom Modern.js plugins.
+Used to configure custom Modern.js framework plugins.
 
 For the way to write custom plugins, please refer to [How to Write Plugins](/docs/guides/topic-detail/framework-plugin/implement).
 
-This option is used to configure the framework plugin. If you need to configure the webpack plugin, please use [tools.webpack](/docs/configure/app/tools/webpack) or [tools.webpack Chain](/docs/configure/app/tools/webpack-chain); If you need to configure the babel plugin, please use [tools.babel](/docs/configure/app/tools/babel).
+## Precautions
+
+This config **is used to configure the Modern.js framework plugin**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [builderPlugins](docs/configure/app/builder-plugins) to configure Modern.js Builder plugins.
+- Use [tools.webpack](/docs/configure/app/tools/webpack) or [tools.webpackChain](/docs/configure/app/tools/webpack-chain) to configure webpack plugins.
+- Use [tools.babel](/docs/configure/app/tools/babel) to configure babel plugins.
 
 ## Plugin type
 
-There are three different plug-in mechanisms built into the Modern.js:
+There are three different type of framework plugins built into the Modern.js:
 
 - `CLI Plugin`，for local development, compilation and build phases, can extend various capabilities on the command line and compilation phases.
 - `Server Plugin`，for server-level.

package/en/docusaurus-plugin-content-docs/current/configure/app/source/disable-entry-dirs.md

@@ -0,0 +1,38 @@
+---
+title: source.disableEntryDirs
+
+sidebar_label: disableEntryDirs
+---
+
+* Type： `string[]`
+* Default： `[]`
+
+By default, application entries are identified based on the'src 'directory, you can disable some directories from being identified as application entries with this option.
+
+For example, when the configuration and directory structure is as follows：
+
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableEntryDirs: './src/one'
+  }
+})
+```
+
+``` title="Project directory structure"
+└── src/
+    ├── one/
+    |    └── App.tsx
+    ├── two/
+    |    └── routes/
+    └── env.d.ts
+```
+
+When this option is not set, Modern.js will generate two entries based on the project directory:
+- one
+- two
+
+When this option is set, `src/one` will not be recognized as an entry directory.
+
+A common usage is to configure the `src/common`, `src/components` directories to this option to avoid these directories being recognized as application entries.

package/en/docusaurus-plugin-content-docs/current/configure/app/source/entries.md

@@ -27,10 +27,34 @@ export default defineConfig({
 });
 ```
 
-Customized entry, only need to export `App` by default, Modern.js will generate a real entry file.
+By default, the configured entry is equivalent to `App.[jt]sx`, that is, the specified entry file only needs to export the root component of the application.
 
-When this behavior needs to be turned off, the value can be set to `Object` and the property `disableMount` can be set to `true`.
+For example the following directory structure:
 
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+With the content of the above default entry mechanism, Modern.js when analyzing the above directory, will not get any default entry.
+
+In cases where you do not want to change the directory structure (such as project migration), you can customize the entry through `source.entries`:
+
+
+```ts title="modern.config.js"
+export default defineConfig({
+  source: {
+    entries: {
+      home: './src/entry/home.tsx',
+      chat: './src/entry/chat.tsx',
+    },
+  },
+});
+```
 
 ## Object
 
@@ -60,3 +84,43 @@ export default defineConfig({
   },
 });
 ```
+
+By default, the configured entry is equivalent to `App.[jt]sx`. If you want the entry to be equivalent to the entry in build mode, you can set the value to'Object' and the property `disableMount` to `true`.
+
+## Combine Entry
+
+When `source.entries` is specified, the Modern.js merges the user-defined entry with the default entry obtained by analyzing the directory structure. The merging rule is:
+
+Compare the entry path set by the custom entry with the default entry path. When the entry paths are the same, the custom entry will override the default entry.
+
+For example the following directory structure:
+
+
+```bash
+.
+├── src
+│   ├── chat
+│   │   └── App.jsx
+│   └── home
+│       └── index.js
+└── package.json
+```
+
+Modern.js analyze the `src/` directory to get the default entries `chat` and `home`. When the user configures the following in the `modern.config.js` file:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      index: './src/home/index.js',
+    },
+  },
+};
+```
+
+You can see that the path of the custom entry `index` is the same as the path of the default entry `home`. During the merging process, `index` will override `home`, and the final entry is as follows:
+
+- `chat -> ./src/chat/App.jsx`
+- `index -> ./src/home/index.js`

package/en/docusaurus-plugin-content-docs/current/configure/app/tools/esbuild.md

@@ -35,4 +35,4 @@ export default defineConfig({
 });
 ```
 
-For config details, please refer to [Modern.js Builder - esbuild Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-esbuild.html#config).
+For config details, please refer to [Modern.js Builder - Esbuild Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-esbuild.html#config).

package/en/docusaurus-plugin-content-docs/current/guides/concept/entries.md

@@ -105,7 +105,7 @@ Typically, the above two modes are sufficient, but when developers need to take
 
 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.
 
-For details, please refer to [customized App](/docs/guides/advanced-features/custom-app).
+For details, please refer to [customized App](/docs/guides/concept/entries#自定义-app).
 
 ## configuration
 

package/en/docusaurus-plugin-content-docs/current/guides/get-started/quick-start.md

@@ -140,12 +140,12 @@ The bundle is generated to `dist/` by default, and the directory structure is as
 
 ## Verify
 
-Execute `pnpm run start` in the project to verify locally that the bundle is running correctly:
+Execute `pnpm run serve` in the project to verify locally that the bundle is running correctly:
 
 ```bash
-$ pnpm run start
+$ pnpm run serve
 
-> modern start
+> modern serve
 
 Starting the modern server...
 info    App running at:

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Custom Plugin",
+  "position": 6
+}

package/package.json

@@ -11,7 +11,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.5",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -20,11 +20,11 @@
     "@modern-js/builder-doc": "2.0.0-beta.4"
   },
   "devDependencies": {
+    "@modern-js/builder-doc": "2.0.0-beta.4",
     "ts-node": "^10",
     "fs-extra": "^10",
     "@types/node": "^16",
-    "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.0.0-beta.4"
+    "@types/fs-extra": "^9"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/zh/apis/app/commands/dev.md

@@ -2,10 +2,10 @@
 sidebar_position: 1
 ---
 
-# dev
+# dev / start
 
 ```bash
-Usage: modern dev [options]
+Usage: modern dev / modern start [options]
 
 本地开发命令
 
@@ -17,10 +17,15 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-`modern dev` 命令启动一个开发服务器，同时监听源文件变化，默认支持 React Fast Refresh：
+`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译，同时监听源文件变化，默认支持模块热更新和 React Fast Refresh。
+
+`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。
 
 ```bash
-App running at:
+$ modern dev
+
+info    Starting dev server...
+info    App running at:
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/zh/apis/app/commands/inspect.md

@@ -5,31 +5,56 @@ sidebar_position: 7
 ```
 Usage: modern inspect [options]
 
-inspect internal webpack config
-
 Options:
   --env <env>           查看指定环境下的配置 (default: "development")
   --output <output>     指定在 dist 目录下输出的路径 (default: "/")
-  --no-console          不在终端中输出完整结果
   --verbose             在结果中展示函数的完整内容
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help            显示命令帮助
 ```
 
-`modern inspect` 命令，用于查看项目的 webpack 完整配置。
+`modern inspect` 命令，用于查看项目的 [Modern.js Builder 配置](https://modernjs.dev/builder/zh/guide/basic/builder-config.html) 以及 webpack 配置。
+
+在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
+
+- `builder.config.js`: 表示在构建时使用的 Modern.js Builder 配置。
+- `webpack.config.web.js`: 表示在构建时使用的 webpack 配置。
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
 
-在项目根目录下执行命令 `npx modern inspect`，会将 webpack 配置输出在终端界面，同时也会在项目的 `dist` 目录生成一份 `webpack.client.inspect.js` 文件，开发者可手动打开查看。
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+```
 
 ## 指定环境
 
-默认情况下，会输出开发环境的 webpack 配置，可以使用 `env` 选项来输出生产环境的配置：
+默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
 
 ```bash
 modern inspect --env production
 ```
 
-## 配置类型
+## 完整内容
+
+默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
+
+```bash
+modern inspect --verbose
+```
+
+## SSR 构建配置
 
-### SSR 配置
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.js` 文件，对应 SSR 构建时的 webpack 配置。
 
-如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.ssr.inspect.js` 文件，对应 SSR 构建时的 webpack 配置。
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
+```

package/zh/apis/app/commands/{start.md → serve.md}

@@ -3,9 +3,9 @@ sidebar_position: 6
 ---
 
 ```bash
-Usage: modern start [options]
+Usage: modern serve [options]
 
-start server
+run server
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
@@ -13,7 +13,7 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-通常使用 `modern start` 命令在生产环境下启用应用工程, 需要提前执行 [`build`](/docs/apis/app/commands/build) 命令构建出对应产物。
+通常使用 `modern serve` 命令在生产环境下启用应用工程, 需要提前执行 [`build`](/docs/apis/app/commands/build) 命令构建出对应产物。
 
 默认情况下，应用将会在 `localhost:8080` 启动，可以通过 `server.port` 修改 Server 端口号：
 

package/zh/apis/app/hooks/src/index_.md

@@ -13,7 +13,7 @@ sidebar_position: 3
 
 ```js title=src/index.js
 import ReactDOM from 'react-dom/client';
-import { bootstrap } from '@edenx/runtime';
+import { bootstrap } from '@modern-js/runtime';
 
 export default (App: React.ComponentType) => {
   // do something before bootstrap...