@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -0,0 +1,31 @@
+---
+title: source.disableDefaultEntries
+sidebar_label: disableDefaultEntries
+---
+# disableDefaultEntries
+
+- 类型： `boolean`
+- 默认值： `false`
+
+关闭根据项目目录结构自动识别应用构建入口的功能，默认情况下，Modern.js 会根据项目目录结构得到对应构建入口。
+
+:::info
+默认情况下，Modern.js 会根据项目目录结构得到对应入口信息。具体可参考[入口](/guides/concept/entries)。
+配置关闭改机制后，需要使用 [`source.entries`](/configure/app/source/entries) 配置自定义入口。
+
+:::
+
+:::warning 警告
+推荐按照 Modern.js 提供的目录规范组织代码可以更好使用框架的功能，避免一些冗余的配置。
+
+:::
+
+设置如下，即可关闭默认的行为：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```

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

@@ -0,0 +1,39 @@
+---
+title: source.disableEntryDirs
+
+sidebar_label: disableEntryDirs
+---
+# disableEntryDirs
+
+- 类型： `string[]`
+- 默认值： `[]`
+
+默认会根据 `src` 目录识别应用入口，可通过该选项禁止某些目录被识别为应用入口。
+
+例如，当配置与目录结构如下时：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableEntryDirs: './src/one',
+  },
+});
+```
+
+```bash title="项目目录结构"
+└── src/
+    ├── one/
+    |    └── App.tsx
+    ├── two/
+    |    └── routes/
+    └── env.d.ts
+```
+
+在未设置该配置项时，Modern.js 会根据项目目录产出两个 entry:
+
+- one
+- two
+
+当设置该配置项后，`src/one` 不会作为 entry 目录被识别。
+
+常见的用法是，将 `src/common`、`src/components` 目录配置到该选项中，避免这些目录被识别为应用入口。

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

@@ -0,0 +1,55 @@
+---
+title: source.enableAsyncEntry
+sidebar_label: enableAsyncEntry
+---
+# enableAsyncEntry
+
+- 类型： `boolean`
+- 默认值： `false`
+
+该选项用于 webpack 模块联邦 (Module Federation）场景。
+
+开启此选项后，Modern.js 会通过 Dynamic Import 来包裹自动生成的入口文件（asynchronous boundary），使页面代码可以消费模块联邦生成的远程模块。
+
+## 背景知识
+
+如果不了解 webpack 模块联邦，请先阅读 Module Federation 官方文档：
+
+- [中文文档](https://webpack.docschina.org/concepts/module-federation/)
+- [英文文档](https://webpack.js.org/concepts/module-federation)
+
+## 示例
+
+首先，在配置文件中开启此选项：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+  },
+});
+```
+
+然后执行 `dev` 或 `build` 命令，可以看到 Modern.js 自动生成的文件变为以下结构：
+
+```bash
+node_modules
+  └─ .modern-js
+     └─ main
+        ├─ bootstrap.js  # 真正的入口代码
+        ├─ index.js      # 异步入口文件（asynchronous boundary）
+        └─ index.html
+```
+
+其中 `index.js` 的内容如下：
+
+```js
+import('./bootstrap.js');
+```
+
+此时，就可以在当前页面中消费任意的远程模块了。
+
+:::info
+Modern.js 未对 webpack 的 ModuleFederationPlugin 进行封装，请通过 [tools.webpackChain](/configure/app/tools/webpack-chain) 自行配置 ModuleFederationPlugin。
+
+:::

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

@@ -0,0 +1,40 @@
+---
+title: source.entriesDir
+
+sidebar_label: entriesDir
+---
+# entriesDir
+
+- 类型： `string`
+- 默认值： `./src`
+
+默认会根据 `src` 目录识别应用入口，可通过该选项自定义应用入口的识别目录。
+
+例如，当配置与目录结构如下时：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entriesDir: './src/pages',
+  },
+});
+```
+
+```bash title="项目目录结构"
+.
+└── src
+    └── pages
+        ├── a
+        │   └── App.jsx
+        └── b
+            └── App.jsx
+```
+
+Modern.js 会根据 `./src/pages` 目录结构生成构建入口 `a` 和入口 `b`，结果如下：
+
+```js
+ {
+   a: './src/pages/a/App.jsx',
+   b: './src/pages/b/App.jsx'
+ }
+```

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

@@ -0,0 +1,123 @@
+---
+title: source.entries
+sidebar_label: entries
+---
+# entries
+
+- 类型： `Object = { [ entryName: string ]: string | Object }`
+- 默认值： 根据当前项目目录结构动态结算出的默认入口对象。
+
+对于大部分场景，Modern.js 根据目录结构自动生成的入口能满足大部分业务需求。具体可参考[入口](/guides/concept/entries)。
+
+如需自定义构建入口时，可以通过该选项指定。
+
+## String 类型
+
+当值为 `string` 类型时，为入口的文件路径:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // 指定一个名称为 entry_customize 的新入口
+      entry_customize: './src/home/test/index.js',
+    },
+  },
+});
+```
+
+默认情况下，配置的入口等价于 `App.[jt]sx`，即指定的入口文件只需要导出应用的根组件。
+
+例如以下目录结构：
+
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+结合上面默认入口机制的内容，Modern.js 在分析上述目录结构时，不会得到任何默认入口。
+
+在不想改变目录结构的情况下（如项目迁移），可以通过 `source.entries` 自定义入口：
+
+```ts title="modern.config.js"
+export default defineConfig({
+  source: {
+    entries: {
+      home: './src/entry/home.tsx',
+      chat: './src/entry/chat.tsx',
+    },
+  },
+});
+```
+
+## Object 类型
+
+当值为 `Object` 时，可配置如下属性：
+
+- `entry`：`string`，入口文件路径。
+- `disableMount`：`boolean = false`，关闭 Modern.js 生成入口代码的行为。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      entry_customize: {
+        // 入口文件路径
+        entry: './src/home/test/App.jsx',
+      },
+      // 启用约定式路由
+      entry_spa: {
+        // 约定式路由的入口路径必须设置为目录
+        entry: './src/about',
+      },
+    },
+  },
+});
+```
+
+默认情况下，配置的入口等价于 `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/configure/app/testing/transformer.mdx

@@ -0,0 +1,16 @@
+---
+title: testing.transformer
+sidebar_label: transformer
+sidebar_position: 1
+---
+# transformer
+
+- 类型：`'babel-jest' | 'ts-jest'`
+- 默认值：`babel-jest`
+
+配置执行测试的时候对于源码的编译工具： [babel-jest](https://www.npmjs.com/package/babel-jest) 或 [ts-jest](https://github.com/kulshekhar/ts-jest)。默认使用 `babel-jest`。
+
+:::info 补充信息
+`babel-jest` 也可以编译 TS 文件，但不会类型报错，如果你需要跑测试的时候对 TS 类型进行校验，那么请使用 `ts-jest`。
+
+:::

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

@@ -0,0 +1,40 @@
+---
+title: tools.esbuild
+sidebar_label: esbuild
+---
+# 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) 问题**。
+
+## 配置项
+
+你可以通过 `tools.esbuild` 配置项来设置 esbuild 编译行为。
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    esbuild: {
+      loader: {
+        target: 'chrome61',
+      },
+      minimize: {
+        target: 'chrome61',
+      },
+    },
+  },
+});
+```
+
+完整配置项请参考 [Modern.js Builder - esbuild 插件配置](https://modernjs.dev/builder/plugins/plugin-esbuild.html#%E9%85%8D%E7%BD%AE)。

package/zh/configure/app/tools/jest.mdx

@@ -0,0 +1,41 @@
+---
+title: tools.jest
+
+sidebar_label: jest
+---
+# jest
+
+- 类型： `Object | Function`
+- 默认值：`{}`
+
+:::caution 注意
+需要先通过 `pnpm run new` 启用 单元测试 功能。
+
+:::
+
+对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `Object` 类型时，可以配置 Jest 所支持的所有底层配置 。
+
+```js title=modern.config.js
+export default defineConfig({
+  tools: {
+    jest: {
+      testTimeout: 10000,
+    },
+  },
+});
+```
+
+值为 `Function` 类型时，默认配置作为第一个参数传入，需要返回新的 Jest 配置对象。
+
+```js title=modern.config.js
+export default defineConfig({
+  tools: {
+    jest: options => {
+      return {
+        ...options,
+        testTimeout: 10000,
+      };
+    },
+  },
+});
+```

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

@@ -0,0 +1,54 @@
+---
+title: tools.swc
+sidebar_label: swc
+---
+# swc
+
+- 类型： `Object`
+- 默认值： `undefined`
+
+## 介绍
+
+[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且比 Babel 性能高出 10 倍不止。
+
+Modern.js 提供了开箱即用的 SWC 插件，可以为你的 Web 应用提供语法降级、Polyfill 以及压缩，并且移植了一些额外常见的 Babel 插件。
+
+## 安装
+
+使用前需要安装 `@modern-js/plugin-swc` 插件。
+
+```bash
+pnpm add @modern-js/plugin-swc -D
+```
+
+安装完成后，只需在 `modern.config.ts` 文件中注册 SWC 插件，即可启用 SWC 编译和压缩能力。
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import swcPlugin from '@modern-js/plugin-swc';
+
+export default defineConfig({
+  plugins: [appTools(), swcPlugin()],
+});
+```
+
+## 配置项
+
+你可以通过 `tools.swc` 配置项来设置 SWC 编译行为。
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc: {
+      jsMinify: {
+        compress: {},
+        mangle: true,
+      },
+    },
+  },
+});
+```
+
+完整配置项请参考 [Modern.js Builder - SWC 插件配置](https://modernjs.dev/builder/plugins/plugin-swc.html#%E9%85%8D%E7%BD%AE)。

package/zh/configure/app/tools/tailwindcss.mdx

@@ -0,0 +1,43 @@
+---
+title: tools.tailwindcss
+
+sidebar_label: tailwindcss
+---
+# tailwindcss
+
+- 类型： `Object | Function`
+- 默认值：见下方配置详情。
+
+<details>
+  <summary>TailwindCSS 配置详情</summary>
+
+```js
+const tailwind = {
+  content: [
+    './config/html/**/*.html',
+    './config/html/**/*.ejs',
+    './config/html/**/*.hbs',
+    './src/**/*.js',
+    './src/**/*.jsx',
+    './src/**/*.ts',
+    './src/**/*.tsx',
+    './storybook/**/*',
+  ],
+  theme: source.designSystem, // 使用source.designSystem配置作为Tailwind CSS Theme配置
+};
+```
+
+:::tip 提示
+更多关于：<a href="https://tailwindcss.com/docs/configuration" target="_blank">TailwindCSS 配置</a>。
+
+:::
+
+</details>
+
+对应 [TailwindCSS](https://tailwindcss.com/docs/configuration) 的配置，值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。
+
+值为 `Function` 类型时，函数返回的对象与默认配置通过 `Object.assign` 合并。
+
+不允许出现 `theme` 属性，否则会构建失败。 Modern.js 使用 [`source.designSystem`](/configure/app/source/design-system) 作为 `Tailwind CSS Theme` 配置。
+
+其他的使用方式和 Tailwind CSS 一致: [快速传送门](https://tailwindcss.com/docs/configuration)。

package/zh/configure/app/usage.mdx

@@ -0,0 +1,93 @@
+---
+sidebar_position: 0
+---
+
+# 配置使用
+
+Modern.js 中有两种配置，一个是编译时配置，一个是服务端运行时配置。
+
+编译时配置可以在两个位置进行配置：
+
+- `package.json` 文件
+- 根路径下的 `modern.config.t(j)s` 文件
+
+:::warning 注意
+同一个配置不支持同时在 `package.json` 中和 `modern.config.t(j)s` 中配置。推荐在 `modern.config.t(j)s` 中进行配置。
+
+:::
+
+服务端运行时配置可以在根路径下的 `modern.server-runtime.config.t(j)s` 自定义配置选项。
+
+## 在配置文件中配置
+
+Modern.js 的配置文件定义在项目的根目录下，同时支持 `.js` 和 `.ts` 两种格式：
+
+- `modern.config.js`
+- `modern.config.ts`
+
+### modern.config.js
+
+`modern.config.js` 中可以使用 JavaScript 语法，因此比 `package.json` 更加灵活。
+
+比如，你可以在 `modern.config.js` 中定义函数类型的配置选项：
+
+```js title="modern.config.js"
+export default {
+  source: {
+    alias: opts => {
+      opts['@common'] = './src/common';
+    },
+  },
+};
+```
+
+你也可以通过 `process.env.NODE_ENV` 进行动态设置：
+
+```js title="modern.config.js"
+export default {
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+### modern.config.ts
+
+我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
+
+从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
+
+## 在 package.json 中配置（不推荐）
+
+除了配置文件外，也可以在 `package.json` 中的 `modernConfig` 字段下设置配置选项，如：
+
+```json title="package.json"
+{
+  "modernConfig": {
+    "source": {
+      "alias": {
+        "@common": "./src/common"
+      }
+    }
+  }
+}
+```
+
+由于 JSON 文件格式的限制，`package.json` 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。
+
+## 注意事项
+
+- 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示。
+- `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。

package/zh/guides/advanced-features/bff/bff-proxy.mdx

@@ -0,0 +1,30 @@
+---
+sidebar_position: 5
+title: 使用 BFF 代理
+---
+# 使用 BFF 代理
+
+通过配置 BFF 代理，无需手动写码，即可对 API 请求进行转发。
+
+:::caution
+使用 BFF 代理需确保请求能进入 BFF handler。（例如请求路径必须包含 bff prefix）
+
+:::
+
+在 `modern.server-runtime.config.js` 文件中编写以下 BFF 代理配置，会将发送到 `http://localhost:8080/api/v1/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
+
+```js title="modern.server-runtime.config.js"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api/v1/topics': 'https://cnodejs.org',
+    },
+  },
+};
+```
+
+:::note
+详细 API 请查看 [BFF 代理](/configure/app/bff/proxy)。更多 Modern.js 代理的能力可查看[调试代理](/guides/basic-features/proxy)。
+
+:::