@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/configure/app/tools/ts-checker.md

@@ -0,0 +1,13 @@
+---
+title: tools.tsChecker
+sidebar_label: tsChecker
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.tsChecker](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tschecker)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/tools/tsChecker.md'
+
+<Main />

package/zh/configure/app/tools/ts-loader.md

@@ -0,0 +1,13 @@
+---
+title: tools.tsLoader
+sidebar_label: tsLoader
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.tsLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tsloader)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/tools/tsLoader.md'
+
+<Main />

package/zh/configure/app/tools/webpack-chain.md

@@ -0,0 +1,13 @@
+---
+title: tools.webpackChain
+sidebar_label: webpackChain
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.webpackChain](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpackchain)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/tools/webpackChain.md'
+
+<Main />

package/zh/configure/app/tools/webpack.md

@@ -0,0 +1,13 @@
+---
+title: tools.webpack
+sidebar_label: webpack
+sidebar_position: 1
+---
+
+:::info BUILDER
+该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.webpack](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpack)。
+:::
+
+import Main from '@modern-js/builder-doc/zh/config/tools/webpack.md'
+
+<Main />

package/zh/configure/app/usage.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 0
+---
+
+# 配置使用
+
+Modern.js 支持在 `modern.config.js` 配置文件或 `package.json` 文件中自定义配置选项。
+
+## 配置文件
+
+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](/docs/apis/app/runtime/app/define-config) API，请注意区分。

package/zh/configure/generator/introduce.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+Modern.js 提供了应用(MWA)、模块、Monorepo 三种工程方案类型，并支持通过 `@modern-js/create` 创建工程方案初始化项目。
+
+使用 `@modern-js/create` 时会询问用户一些问题来生成符合用户需求的项目，这一章将介绍这里的问题字段便于进行定制化工程方案开发时使用。
+
+:::info
+配置章节将使用同时介绍内容和字段值的方式，括号中内容为对应的字段值
+:::
+
+## 工程方案配置
+
+### Solution
+
+工程方案类型(solution)，共三个选项：
+
+- 应用(mwa)
+
+- 模块(module)
+
+- Monorepo
+
+:::info
+solution 配置只能在 `@modern-js/create` 的 `--config` 参数中使用，不能在生成器插件中通过设置输入默认值的方式使用。
+:::
+
+### Scenes
+
+项目场景(scenes)，当使用创建工程方案场景类型的生成器插件时，该值为对应生成器插件的 key 值。
+
+:::info
+scenes 配置只能在 `@modern-js/create` 的 `--config` 参数中使用，不能在生成器插件中通过设置输入默认值的方式使用。
+:::
+
+## 通用配置
+
+### Language
+
+开发语言(language)，共有两个选项：
+
+- TS(ts)
+
+- ES6+(js)
+
+### Package-Manager
+
+包管理工具(packageManager)，共有两个选项：
+
+- pnpm(pnpm)
+
+- Yarn(yarn)
+
+
+:::info
+在生成器插件创建工程方案场景的自定义类型(custom)中，默认只提供了 `packageManager` 配置。
+:::
+
+## 其他配置
+
+### noNeedInstall
+
+是否跳过依赖安装。
+
+type: Boolean
+
+default: false
+
+### noNeedGit
+
+是否跳过 git 初始化和提交初始 commit。
+
+type: Boolean
+
+default: false
+
+### successInfo
+
+自定义创建项目成功的提示信息。
+
+type: String
+
+default: 不同工程方案的命令操作提示
+
+### isMonorepoSubProject
+
+是否为 Monorepo 子项目。
+
+type: Boolean
+
+default: false
+### isTest
+
+作用于 `应用(MWA)` 项目，标识是否为测试项目。
+
+type: Boolean
+- true: 创建到路径 `examples/`
+- false: 创建到路径 `apps/`
+
+default: false
+
+### isPublic
+
+作用于 `模块(Module)` 项目，标识是否需要对外发布。
+
+type: Boolean
+- true: 创建到路径 `packages/`
+- false: 创建到路径 `features/`
+
+default: false

package/zh/configure/generator/module.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 3
+---
+
+# 模块
+
+模块项目默认包含通用配置，通用配置可查看[通用配置](/docs/configure/generator/introduce#通用配置)。
+
+## 创建项目
+
+创建项目时配置，`@modern-js/create` 使用 `--config` 参数时使用的配置，也是在生成器插件中修改和添加 input 时使用的配置。
+
+### Package-Name
+
+包名(packageName)，字符串类型，为输入值。
+
+## New 命令
+
+模块项目中 new 命令配置， 可以在执行 new 命令时通过 `--config` 参数配置，也可在生成器插件中创建元素和启用功能时使用。
+
+### Action-Type
+
+New 命令的操作类型(actionType)，类型支持一种：
+
+- function 启用功能
+
+:::info
+在生成器插件中使用启用功能和创建元素时不需要该参数，生成器插件中自动添加该参数。
+:::
+
+### Function
+
+可选功能名称(function)，支持 11 个选项:
+
+- Tailwind CSS(tailwindcss)
+
+- Less(less)
+
+- Sass(sass)
+
+- Storybook(mwa_storybook)
+
+- Runtime API(runtimeApi)

package/zh/configure/generator/monorepo.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+---
+
+# Monorepo
+
+Monorepo 项目默认只需要 [PackageManager 配置](/docs/configure/generator/introduce#package-manager)。
+
+## 创建子项目
+
+Monorepo 项目支持通过使用 new 命令创建子项目，子项目类型支持应用、测试应用、模块、内部模块，除了应用和模块各自的配置外，这里还需要一些通用的子项目配置。
+
+### Solution
+
+子项目类型(solution)，不同子项目类型字段为:
+
+- 应用(mwa)
+- 应用（测试）(mwa_test)
+- 模块(module)
+- 模块（内部）(inner_module)
+
+### Package-Name
+
+子项目名称(packageName)，字符串类型。
+
+### Package-Path
+
+子项目路径(packagePath)，字符串类型。

package/zh/configure/generator/mwa.md

@@ -0,0 +1,127 @@
+---
+sidebar_position: 2
+---
+
+# 应用
+
+应用项目默认包含通用配置，通用配置可查看[通用配置](/docs/configure/generator/introduce#通用配置)。
+
+## 创建项目
+
+创建项目时配置，`@modern-js/create` 使用 `--config` 参数时使用的配置，也是在生成器插件中修改和添加 input 时使用的配置。
+
+### Need-Modify-MWA-Config
+
+是否需要修改应用默认配置(needModifyMWAConfig)。
+
+该配置值为 `yes` 时，后续配置才会展示给用户。
+
+在使用 `--config` 参数或者在生成器插件中时，配置值为 `yes` 后续配置才会生效。
+
+该字段共有两个选项：
+
+- 是(yes)
+
+- 否(no)
+
+### Client-Route
+
+客户端路由配置(clientRoute)，默认为自控路由，共有两个选项：
+
+- 自控路由(selfControlRoute)
+
+- 约定式路由(conventionalRoute)
+
+## New 命令
+
+应用项目中 new 命令配置， 可以在执行 new 命令时通过 `--config` 参数配置，也可在生成器插件中创建元素和启用功能时使用。
+
+### Action-Type
+
+New 命令的操作类型(actionType)，类型支持两种：
+
+- element 创建工程元素
+
+- function 启用功能
+
+:::info
+在生成器插件中使用启用功能和创建元素时不需要该参数，生成器插件中自动添加该参数。
+:::
+
+### Element
+
+元素名称(element)，支持两个选项：
+
+- 创建应用入口(entry)
+
+- 新建 Server 自定义源码目(server)
+
+这两个选项还需要配置具体的配合使用，介绍如下：
+
+#### Name
+
+入口名称(name), 字符串类型。
+
+创建入口除了`name`之外，还需要 `needModifyMWAConfig`、`clientRoute` 字段。
+
+#### Framework
+
+自定义 Server 运行时框架(framework)，支持四个选项：
+
+- Egg(egg)
+
+- Express(express)
+
+- Koa(koa)
+
+- Nest(nest)
+
+### Function
+
+可选功能名称(function)，支持如下选项:
+
+- Tailwind CSS(tailwindcss)
+
+- Less(less)
+
+- Sass(sass)
+
+- BFF(bff)
+
+- SSG(ssg)
+
+- 微前端(micro_frontend)
+
+- 单元测试(test)
+
+- Storybook(mwa_storybook)
+
+- 部署(deploy)
+
+- 启用「基于 UA 的 Polyfill」功能(polyfill)
+
+- 启用「全局代理」(proxy)
+
+`bff` 和 `deploy` 和还需要配置具体的配合使用，介绍如下：
+
+#### BFF 相关参数
+
+##### BFF-Type
+
+BFF 类型(bffType)，支持两个选项：
+
+- 函数模式(function)
+
+- 框架模式(framework)
+
+##### Framework
+
+自定义 Server 运行时框架(framework)，支持四个选项：
+
+- Egg(egg)
+
+- Express(express)
+
+- Koa(koa)
+
+- Nest(nest)

package/zh/guides/advanced-features/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "进阶功能",
+  "position": 4,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "guides/advanced-features/index"
+  }
+}

package/zh/guides/advanced-features/bff/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "BFF",
+  "position": 1
+}

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

@@ -0,0 +1,25 @@
+---
+sidebar_position: 6
+title: 使用 BFF 代理
+---
+
+通过配置 BFF 代理，无需手动写码，即可对 API 请求进行转发。
+
+::: caution
+使用 BFF 代理需确保请求能进入 BFF handler。（例如请求路径必须包含 bff prefix）
+:::
+
+在 `modern.server-runtime.config.js` 文件中编写以下 BFF 代理配置，会将发送到 `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',
+    },
+  },
+};
+```
+
+具体 API 请查看 [BFF 代理](/docs/configure/app/bff/proxy)，更多 Modern.js 代理的能力可查看[调试代理](/docs/guides/basic-features/proxy)。

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

@@ -0,0 +1,142 @@
+---
+sidebar_position: 3
+title: 定制 BFF Server
+---
+
+BFF Server 与应用一体，共同开发、调试、部署，开发者通常只需要写函数即可。但有时，应用中会存在一些 BFF 函数的通用前置逻辑，例如权限校验。
+
+在[一体化 Web 专题](/docs/guides/advanced-features/web-server)中提到过，Modern.js 支持定制 Web Server。同样，Modern.js 也为 BFF Server 提供了扩展能力。
+
+Modern.js 允许开发者创建 `api/_app.ts` 文件，在该文件中对定制自己的 BFF Server。
+
+和 Web Server 相同，默认支持了 4 种主流的 Node.js Server 框架：Express、Koa、Egg、Nest，开发者可以根据自身偏好，选择合适的框架来编写 `api/_app.ts`。
+
+这里先以 Express 为例来展示一下用法，下一章节会详细介绍各个框架扩展的写法。
+
+首先创建项目，并[开启 BFF 功能](/docs/tutorials/first-app/c09-bff/9.2-enable-bff)，这时项目的目录结构是：
+
+```md
+.
+├── README.md
+├── api
+│   ├── _app.ts
+│   ├── index.ts
+│   └── info
+│       └── [type].ts
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── App.css
+│   ├── App.tsx
+│   ├── index.test.ts
+│   └── modern-app-env.d.ts
+└── tsconfig.json
+```
+
+创建一个 `api/login.ts` 文件用于实现登录：
+
+```ts
+import { useContext } from '@modern-js/runtime/server';
+
+export const post = async () => {
+  const ctx = useContext();
+  ctx.res.cookie('sid', Math.random());
+
+  return { code: 0, message: 'OK' };
+};
+```
+
+:::info 补充信息
+`useContext` API 用于获取请求上下文，具体用法可以看 [API 文档](/docs/apis/app/runtime/bff-server/use-context)。
+:::
+
+接下来修改 `api/_app.ts`，手写一个中间件用于权限校验：
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import { Request, Response, NextFunction } from 'express';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req: Request, res: Response, next: NextFunction) => {
+    if (req.url !== '/api/login') {
+      const sid = req?.cookies?.sid;
+      if (!sid) {
+        res.status(400);
+        res.json({ code: -1, message: 'need login' });
+      } else {
+        next();
+      }
+    } else {
+      next();
+    }
+  });
+});
+```
+
+然后添加一个普通的接口函数文件 `/api/hello.ts`：
+
+```ts
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+最后在前端 `/src/App.tsx` 添加接口的访问代码，直接使用一体化调用的方式：
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
+
+    fetchMyApi();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+然后 `pnpm run dev` 启动项目，访问 [http://localhost:8080/](http://localhost:8080/) 会发现 `/api/hello` 的请求被拦截了：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+我们再修改前端代码 `src/App.tsx`，在访问 `/api/hello` 前先调用登录接口：
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+刷新页面，可以看到 `/api/hello` 访问成功：
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+以上代码模拟了在 `/api/_app.ts` 中添加中间件的方式，实现了简易的登录功能。
+
+同样，可以在这个钩子文件中实现其他功能来扩展 BFF Server。