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

package/zh/configure/app/source/entries.md

@@ -10,7 +10,6 @@ sidebar_label: entries
 
 如需自定义构建入口时，可以通过该选项指定。
 
-
 ## String 类型
 
 当值为 `string` 类型时，为入口的文件路径:
@@ -28,9 +27,33 @@ export default defineConfig({
 });
 ```
 
-自定义的入口，只需要默认导出 `App`, Modern.js 会生成真正的入口文件。
+默认情况下，配置的入口等价于 `App.[jt]sx`，即指定的入口文件只需要导出应用的根组件。
+
+例如以下目录结构：
+
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+结合上面默认入口机制的内容，Modern.js 在分析上述目录结构时，不会得到任何默认入口。
 
-需要关闭这一行为时，可以将值设为 `Object`，属性 `disableMount` 设置为 `true`。
+在不想改变目录结构的情况下（如项目迁移），可以通过 `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 +83,43 @@ export default defineConfig({
   },
 });
 ```
+
+默认情况下，配置的入口等价于 `App.[jt]sx`，如果希望该入口等价于构建模式下的入口，可以将属性 `disableMount` 设置为 `true`。
+
+
+## 自定义入口和默认入口合并
+
+在指定 `source.entries` 后，Modern.js 会将用户自定义的入口与分析目录结构得到的默认入口合并。合并规则为：
+
+比较自定义入口设置的入口路径和默认入口路径，当入口路径一致时，自定义入口会覆盖默认入口。
+
+例如以下目录结构:
+
+```
+.
+├── src
+│   ├── chat
+│   │   └── App.jsx
+│   └── home
+│       └── index.js
+└── package.json
+```
+
+Modern.js 分析 `src/` 目录，得到默认入口 `chat` 和 `home`。当用户在 `modern.config.js` 文件中配置如下时：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      index: './src/home/index.js',
+    },
+  },
+};
+```
+
+可以看到自定义入口 `index` 的路径和默认入口 `home` 的路径一致，在合并的过程中，`index` 会覆盖掉 `home`，最终入口如下：
+
+- `chat -> ./src/chat/App.jsx`
+- `index -> ./src/home/index.js`

package/zh/guides/advanced-features/compatibility.md

@@ -29,7 +29,18 @@ Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-C
 ? 启用可选功能 启用「基于 UA 的 Polyfill」功能
 ```
 
-安装依赖后，配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run start` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
+执行命令后，在 `modern.config.ts` 中注册 Polyfill 插件:
+
+```ts title="modern.config.ts"
+import PolyfillPlugin from '@modern-js/plugin-polyfill';
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  ...,
+  plugins: [..., PolyfillPlugin()],
+});
+```
+
+配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
 
 ```js
 <script src="/__polyfill__" crossorigin></script>

package/zh/guides/advanced-features/eslint.md

@@ -49,10 +49,6 @@ pnpm run lint:error
 
 【Modern.js ESLint 规则集】要求 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 必须成对使用，必须明确表达要影响的范围，以及在这个范围内明确表达要禁用什么规则，目的是让**例外**有明确的、最小化的范围，避免 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 被滥用，导致不属于例外的代码也被禁用了规则。
 
-### 添加自定义配置
-
-<!-- 见 [如何自定义 Lint 规则](/guide/more-guides/more-about-lint#q-如何自定义-lint-规则) -->
-
 ## Q: 如何自定义 ESLint 规则
 
 ### 仓库根目录下 `package.json` 里的 "eslintConfig" 字段
@@ -73,7 +69,7 @@ pnpm run lint:error
 
 ```
 
-### `src/.eslintrc.json` 文件
+### `src/.eslintrc.js` 文件
 
 Modern.js 的应用工程、模块工程，源代码目录里都会默认有这个配置文件，是针对 Universal JS 代码设计的。
 
@@ -83,25 +79,29 @@ Universal JS 代码是既能浏览器端也能在服务器端运行的代码。
 
 如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置，该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
 
-```json
-{
-  "extends": [
-    "@modern-js-app"
-  ],
-  "rules": {
-    "filenames/match-exported": "off"
-  }
-}
+```js
+// eslint-disable-next-line import/no-commonjs
+module.exports = {
+  root: true,
+  extends: ['@modern-js-app'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['../tsconfig.json'],
+  },
+  rules: {
+    'filenames/match-exported': 'off',
+  },
+};
 ```
 
-如果有需要，还可以继续在不同的子目录里增加 `.eslintrc.json` 文件，针对这个子目录里的代码做特殊配置：
+如果有需要，还可以继续在不同的子目录里增加 `.eslintrc.js` 文件，针对这个子目录里的代码做特殊配置：
 
-```json
-{
-  "rules": {
-    "filenames/match-exported": "off"
-  }
-}
+```js
+module.exports = {
+  rules: {
+    'filenames/match-exported': 'off',
+  },
+};
 ```
 
 :::tip 提示

package/zh/guides/advanced-features/ssg.md

@@ -16,6 +16,17 @@ SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `de
 ? 启用可选功能 启用「SSG」功能
 ```
 
+执行命令后，在 `modern.config.ts` 中注册 SSG 插件:
+
+```ts title="modern.config.ts"
+import SSGPlugin from '@modern-js/plugin-ssg';
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  ...,
+  plugins: [..., SSGPlugin()],
+});
+```
+
 SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
 
 ### 在约定式路由中使用
@@ -71,7 +82,7 @@ export default defineConfig({
 
 **约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `Index Page` 的文本内容，这正是 SSG 的效果。
 
-执行 `pnpm run start` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
+执行 `pnpm run serve` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
 
 ### 在自控式路由中使用
 
@@ -111,7 +122,7 @@ export default defineConfig({
 })
 ```
 
-执行 `pnpm run build` 与 `pnpm run start` 后，访问 `http://localhost:8080/about`，在 Preview 视图中可以看到页面已经完成渲染。
+执行 `pnpm run build` 与 `pnpm run serve` 后，访问 `http://localhost:8080/about`，在 Preview 视图中可以看到页面已经完成渲染。
 
 查看构建产物文件，可以看到 `dist/` 目录中，新增了一个 `main/about/index.html` 文件。
 
@@ -159,4 +170,4 @@ export default () => {
 
 执行 `pnpm run dev`，重复刷新页面，可以看到 `/foo` 页面的渲染结果不断发生变化，说明数据是在请求时获取的。
 
-重新执行 `pnpm run build` 后，执行 `pnpm run start`，重复刷新页面，发现页面渲染结果始终保持同样的内容，数据在请求时不会再次获取，说明页面在编译时已经完成渲染。
+重新执行 `pnpm run build` 后，执行 `pnpm run serve`，重复刷新页面，发现页面渲染结果始终保持同样的内容，数据在请求时不会再次获取，说明页面在编译时已经完成渲染。

package/zh/guides/advanced-features/ssr.md

@@ -177,7 +177,7 @@ import { PreRender } from '@modern-js/runtime/ssr';
 <PreRender interval={5} />
 ```
 
-修改后，执行 `pnpm run build && pnpm run start` 启动应用，并打开页面。
+修改后，执行 `pnpm run build && pnpm run serve` 启动应用，并打开页面。
 
 首次打开时，和之前的渲染并没有什么不同，同样存在 2s 延迟。点击刷新，页面瞬间打开，但此时，页面数据并没有因为刷新发生变化，这是因为缓存还没有过期。
 

package/zh/guides/advanced-features/testing.md

@@ -15,6 +15,17 @@ Modern.js 默认继承了 [Jest](https://jestjs.io/) 的测试能力。
 
 执行上述命令后，`package.json` 中将会自动生成 `"test": "modern test"` 命令。
 
+在 `modern.config.ts` 中注册 Test 插件:
+
+```ts title="modern.config.ts"
+import TestPlugin from '@modern-js/plugin-testing';
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  ...,
+  plugins: [..., TestPlugin()],
+});
+```
+
 ## 测试文件
 
 Modern.js 默认识别的测试文件路径为： `<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。

package/zh/guides/advanced-features/web-server.md

@@ -16,7 +16,18 @@ Modern.js 作为以客户端为中心的开发框架，对服务端的定制能
 ? 创建工程元素 新建「自定义 Web Server」源码目录
 ```
 
-执行命令后，项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
+执行命令后，在 `modern.config.ts` 中注册 Server 插件:
+
+```ts title="modern.config.ts"
+import ServerPlugin from '@modern-js/plugin-server';
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  ...,
+  plugins: [..., ServerPlugin()],
+});
+```
+
+项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
 
 ## 使用 API 扩展 Web Server
 

package/zh/guides/basic-features/css/tailwindcss.md

@@ -13,6 +13,17 @@ sidebar_position: 2
 ? 启用可选功能 启用 Tailwind CSS 支持
 ```
 
+在 `modern.config.ts` 中注册 Tailwind 插件:
+
+```ts title="modern.config.ts"
+import TailwindCSSPlugin from '@modern-js/plugin-tailwindcss';
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  ...,
+  plugins: [..., TailwindCSSPlugin()],
+});
+```
+
 使用时在入口的根组件(如 `src/App.jsx`)添加如下代码：
 
 ```js