@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/configure/app/server/enable-framework-ext.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_label: enableFrameworkExt
+---
+
+# server.enableFrameworkExt
+
+- 类型： `boolean`
+- 默认值： `false`
+
+默认情况下，开启[自定义 Web Server 功能](/guides/advanced-features/web-server)后，Middleware 会使用 Modern.js 本身的语法。
+
+开启 `server.enableFrameworkExt` 可以使用其他框架扩展的语法。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    enableFrameworkExt: true,
+  },
+});
+```
+
+## 示例
+
+默认的使用方式：
+
+```ts title="server/index.ts"
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = (ctx, next) => {
+  console.log(ctx.request.url);
+  next();
+};
+```
+
+开启后，Middleware 类型将从其他命名空间下导出，并且可以使用框架拓展的语法：
+
+```ts title="server/index.ts"
+import { SomeType } from '@modern-js/runtime/{frameworknName}';
+
+export const middleware: SomeType = (...args) => {
+  console.log(args[0].url);
+  next();
+};
+```
+
+:::note
+上述代码为伪代码，具体使用方式需要参考对应的框架拓展。
+
+:::

package/zh/configure/app/server/port.mdx

@@ -0,0 +1,38 @@
+---
+sidebar_label: port
+---
+
+# server.port
+
+- 类型： `number`
+- 默认值： `8080`
+
+Modern.js 在执行 `dev`, `start` 和 `serve` 命令时，会以 `8080` 为默认端口启动，并会在端口被占用时自动递增端口号。你可以通过该配置来修改 Server 启动的端口号：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+### 与 dev.port 的区别
+
+大多数情况下，我们推荐使用 `server.port` 而不是 `dev.port` 来设置端口号，他们之间的区别如下：
+
+- `dev.port` 仅在开发环境下生效，`server.port` 在开发环境和生产环境下均能生效。
+- 在开发环境下，`dev.port` 的优先级高于 `server.port`。
+
+当你同时设置 `dev.port` 和 `server.port` 时，`dev.port` 会在开发环境下生效，`server.port` 会在生产环境下生效。比如以下例子，在开发环境下监听的端口号为 `3001`，在生产环境下监听的端口号为 `3002`。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    port: 3001,
+  },
+  server: {
+    port: 3002,
+  },
+});
+```

package/zh/configure/app/server/public-routes.mdx

@@ -0,0 +1,26 @@
+---
+sidebar_label: publicRoutes
+---
+
+# server.publicRoutes
+
+- 类型： `Object`
+- 默认值： 根据文件约定自动生成的服务端路由规则：应用的每个文件生成一条路由规则。
+
+该配置选项只作用于服务端路由，可以自定义 `config/public/` 下资源的访问路由。
+
+对象的 `key` 为当前应用的相对文件路径（不使用 `./`）, 值可以是 `string`。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    publicRoutes: {
+      // 设置一个长路由
+      'index.json': '/user-config/card-info/extra/help.json',
+
+      // 设置一个不带后缀的路由
+      'robot.txt': '/app/authentication',
+    },
+  },
+});
+```

package/zh/configure/app/server/routes.mdx

@@ -0,0 +1,90 @@
+---
+sidebar_label: routes
+---
+
+# server.routes
+
+- 类型： `Object`
+- 默认值： 根据文件约定自动生成的服务端路由规则：应用的每个入口生成一条路由规则，入口名称等于路由名称。
+
+该配置选项只作用于服务端路由，可以自定义应用入口的服务访问配置。
+
+## 自定义访问路由
+
+对象的 `key` 为当前应用的入口名, 值可以是 `string | Array<string>`。
+
+当值类型为 `string` 时，当前值即表示访问该入口的路由名称。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      // 默认路由为 /entryName1，自定义后为 /p/test1
+      entryName1: '/p/test1'
+      // 支持动态服务端路由配置
+      entryName2: '/detail/:id'
+    }
+  }
+});
+```
+
+也可以通过 `Array<string>` 为入口设置多个访问路由:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': [`/a`, '/b'],
+    },
+  },
+});
+```
+
+此时，通过 `/a`、`/b` 两个路由都可以访问到 `page-a` 入口。
+
+执行 `dev` 命令后，可以在 `dist/route.json` 中查看入口 `page-a` 存在两条路由记录:
+
+```json
+{
+  "routes": [
+    {
+      "urlPath": "/a",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    },
+    {
+      "urlPath": "/b",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    }
+  ]
+}
+```
+
+## 自定义响应头
+
+可以通过配置入口的 resHeaders 设置响应头：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': {
+        route: ['/a', '/b'],
+        resHeaders: {
+          'x-modern-test': '1',
+        },
+      },
+    },
+  },
+});
+```
+
+:::note
+这一配置在生产环境与开发环境都生效，可以根据 NODE_ENV 区分环境设置不同的响应头。但如果你只需要在开发环境设置响应头，推荐使用 `tools.devServer.headers`。
+
+:::

package/zh/configure/app/server/ssr-by-entries.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_label: ssrByEntries
+---
+
+# server.ssrByEntries
+
+- 类型： `Object`
+- 默认值： `undefined`
+
+按入口设置 ssr 选项，选项内的属性同 [ssr](./ssr.md)，指定值会和 ssr 属性内容做替换合并操作，例如：
+
+:::info 注
+「 入口名 」默认为目录名，少数情况下通过 `source.entries` 自定义入口时，入口名为 `source.entries` 对象的 `key`。
+
+:::
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: true,
+    ssrByEntries: {
+      // page-a 不启用 ssr
+      'page-a': false,
+    },
+  },
+});
+```
+
+如上配置，项目整体启用了 ssr, 但是针对入口 `page-a` 关闭了 ssr 渲染能力。

package/zh/configure/app/server/ssr.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_label: ssr
+---
+
+# server.ssr
+
+- 类型： `boolean`
+- 默认值： `false`
+
+SSR 开关以及相关设置。
+
+当值类型为 `boolean` 时，表示是否开启 SSR 部署模式，默认 `false` 不开启。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+});
+```

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

@@ -0,0 +1,12 @@
+---
+title: source.alias
+sidebar_label: alias
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，详细信息可参考 [source.alias](https://modernjs.dev/builder/api/config-source.html#source-alias)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/source/alias.md'
+
+<Main />

package/zh/configure/app/source/compile-js-data-uri.mdx

@@ -0,0 +1,12 @@
+---
+title: source.compileJsDataURI
+sidebar_label: compileJsDataURI
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，详细信息可参考 [source.compileJsDataURI](https://modernjs.dev/builder/api/config-source.html#source-compilejsdatauri)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/source/compileJsDataURI.md'
+
+<Main />

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

@@ -0,0 +1,24 @@
+---
+title: source.configDir
+sidebar_label: configDir
+---
+# configDir
+
+- 类型： `string`
+- 默认值： `./config`
+
+Modern.js 支持在 `./config` 文件夹下放置一些文件自定义 HTML 模板、图标、静态资源等，具体可参考[文件约定](/apis/app/hooks/config/html)。
+
+通过该选项可以自定义配置文件的目录。
+
+例如，将资源文件目录调整为 `resources` 目录：
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    configDir: './resources',
+  },
+});
+```

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

@@ -0,0 +1,12 @@
+---
+title: source.define
+sidebar_label: define
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，详细信息可参考 [source.define](https://modernjs.dev/builder/api/config-source.html#source-define)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/source/define.md'
+
+<Main />