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

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

@@ -1,42 +0,0 @@
----
-title: tools.swc
-sidebar_label: 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` 插件，安装完成后，会自动启用 SWC 编译和压缩能力。
-
-```bash
-pnpm add @modern-js/plugin-swc -D
-```
-
-## 配置项
-
-你可以通过 `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/zh/plugins/plugin-swc.html#%E9%85%8D%E7%BD%AE)。

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

@@ -1,41 +0,0 @@
----
-title: tools.tailwindcss
-
-sidebar_label: 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`](/docs/configure/app/source/design-system) 作为 `Tailwind CSS Theme` 配置。
-
-其他的使用方式和 Tailwind CSS 一致: [快速传送门](https://tailwindcss.com/docs/configuration)。

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

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

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

@@ -1,12 +0,0 @@
----
-title: tools.tsChecker
-sidebar_label: tsChecker
----
-
-:::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

@@ -1,12 +0,0 @@
----
-title: tools.tsLoader
-sidebar_label: tsLoader
----
-
-:::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

@@ -1,12 +0,0 @@
----
-title: tools.webpackChain
-sidebar_label: webpackChain
----
-
-:::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

@@ -1,12 +0,0 @@
----
-title: tools.webpack
-sidebar_label: webpack
----
-
-:::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

@@ -1,92 +0,0 @@
----
-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](/docs/apis/app/runtime/app/define-config) API，请注意区分。

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

@@ -1,27 +0,0 @@
----
-sidebar_position: 5
-title: 使用 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 代理](/docs/configure/app/bff/proxy)。更多 Modern.js 代理的能力可查看[调试代理](/docs/guides/basic-features/proxy)。
-:::

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

@@ -1,150 +0,0 @@
----
-sidebar_position: 3
-title: 运行时框架
----
-
-Modern.js 的 BFF 支持不同的运行时框架，当前 Modern.js 的 BFF 支持两种运行时框架 [Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/)。
-
-## 函数写法
-
-在函数写法下，各类运行时框架仅中间件写法存在差异，其他实现基本相同。这里以 Express 为例，介绍如何在 `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();
-    }
-  });
-});
-```
-
-然后添加一个普通的 BFF 函数 `/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/` 会发现 `/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。
-
-## 框架写法
-
-框架写法下，Modern.js 不会收集 `api/_app.ts` 中的中间件，运行流程由插件自行控制。
-
-### Express
-
-Express 的框架写法支持可在 `api/app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，甚至扩展原有框架等。
-
-BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
-
-```ts title="api/app.ts"
-import express from "express";
-
-const app = express();
-
-app.put("/user", function (req, res) {
-  res.send("Got a PUT request at /user");
-});
-
-app.use(async (req, res, next) => {
-  console.info(`access url: ${req.url}`);
-  next();
-});
-
-export default app;
-```
-
-### Koa
-
-Koa 框架写法与 Express 类似，支持在 `app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，扩展原有框架等。
-
-BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
-
-:::caution 注意
-在框架写法下，当没有 `app.ts` 的时候，Modern.js 默认会添加 `koa-body`；当有 `app.ts` 时，如果开发者希望使用带有 Body 的 BFF 函数，需要确保 `koa-body` 中间件已经添加。
-:::
-
-```ts title=api/app.ts
-import koa from "koa";
-
-const app = new Koa();
-
-app.put("/user", function (req, res) {
-  res.send("Got a PUT request at /user");
-});
-
-app.use(async (ctx, next) => {
-  console.info(`access url: ${ctx.url}`);
-  await next();
-});
-
-export default app;
-```

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

@@ -1,242 +0,0 @@
----
-sidebar_position: 1
-title: 基础用法
----
-
-通过 Modern.js 开发的应用，可以在 `api/` 目录下定义接口函数，前端可以调用这些接口函数，即可发起请求，无需写前后端胶水层代码，同时保证前后端类型安全。
-
-## 启用 BFF
-
-import EnableBFF from '@site-docs/components/enable-bff.md'
-
-<EnableBFF/>
-
-## BFF 函数
-
-允许通过一体化调用的函数，称为 **BFF 函数**。这里写一个最简单的 BFF 函数，创建 `api/hello.ts` 文件：
-
-:::caution
-如果是框架模式（有 `api/lambda` 目录），需要创建 `api/lambda/hello.ts`
-:::
-
-```ts title="api/hello.ts"
-export const get = async () => 'Hello Modern.js';
-```
-
-接着在 `src/App.tsx` 中直接引入函数并调用：
-
-```tsx title=src/App.tsx
-import { useState, useEffect } from 'react';
-import { get as hello } from '@api/hello';
-
-export default () => {
-  const [text, setText] = useState('');
-
-  useEffect(() => {
-    hello().then(setText);
-  }, []);
-  return <div>{text}</div>;
-};
-```
-
-:::info 注
-Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可以直接通过别名的方式引入函数。
-:::
-
-在 `src/App.tsx` 中引入的函数，会自动转换成接口调用，不需要再去通过 fetch 去调用接口。
-
-执行 `pnpm run dev` 打开 `http://localhost:8080/` 可以看到页面已经展示了 BFF 函数返回的内容，在 Network 中可以看到页面向 `http://localhost:8080/api/hello` 发送了请求：
-
-![Network](https://p6-piu.byteimg.com/tos-cn-i-8jisjyls3a/fd41750f8d414179a9b4ecb519919b36~tplv-8jisjyls3a-3:0:0:q75.png)
-
-## 函数路由
-
-Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，也是一种**约定式路由**。
-
-函数写法下 `api/` 下的所有文件中的每个 BFF 函数都会映射为一个接口。框架写法下 `api/lambda` 下的所有文件中的每个 BFF 函数都会映射为一个接口。
-
-:::note
-函数写法和框架写法会在下一节详细介绍。
-:::
-
-所有 BFF 函数生成的路由都带有统一的前缀，默认值为 `/api`。可以通过 [bff.prefix](/docs/configure/app/bff/prefix) 设置公共路由的前缀。
-
-下面介绍几种路由的约定。
-
-### 默认路由
-
-以 `index.[jt]s` 命名的文件会被映射到上一层目录。
-
-* `api/index.ts` -> `{prefix}/`
-* `api/user/index.ts` -> `{prefix}/user`
-
-### 多层路由
-
-支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
-
-* `api/hello.ts` -> `{prefix}/hello`
-* `api/user/list.ts` -> `{prefix}/user/list`
-
-### 动态路由
-
-同样的，创建命名带有 `[xxx]` 的文件夹或者文件，支持动态的命名路由参数。动态路由的函数参数规则可以看 [dynamac-path](/docs/guides/advanced-features/bff/function#dynamic-path)
-
-* `api/user/[username]/info.ts` -> `{prefix}/user/:username/info`
-* `api/user/username/[action].ts` -> `{prefix}/user/username/:action`
-
-### 白名单
-
-默认 `api/` 目录下所有文件都会当作 BFF 函数文件去解析，但以下文件不会被解析：
-
-* 命名以 `_` 开头的文件。例如：`_utils.ts`。
-* 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
-* 测试文件。例如：`foo.test.ts`。
-* TypeScript 类型文件。例如：`hello.d.ts`。
-* `node_module` 下的文件。
-
-## RESTful API
-
-Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义, 遵循 HTTP Method 规范，并且不允许自由定义参数。
-
-:::info 注
-假设函数允许自由定义参数，产出的路由必然由**私有协议**进行调用（原因是无法区分请求参数与请求体），而无法实现任意的 RESTful API。
-
-如果服务仅用于应用本身不存在问题，但它**不标准的接口定义**无法融入更大的体系。 在多个系统共同工作的情况下（例如 BFF 低码搭建），会导致其他系统也需要遵循**私有协议**。
-:::
-
-### 函数具名导出
-
-Modern.js BFF 函数的导出名决定了函数对应接口的 Method，如 `get`，`post` 等。
-
-例如，按照以下例子，可导出一个 GET 接口。
-
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: '现代 web 工程方案',
-  };
-};
-```
-
-按照以下例子，则可导出一个 `POST` 接口
-
-```ts
-export const post = async () => {
-  return {
-    name: 'Modern.js',
-    desc: '现代 web 工程方案',
-  };
-};
-```
-
-* 对应 HTTP Method，Modern.js 也支持了 9 种定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
-
-* 名字是大小不敏感的，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
-
-* 可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
-
-:::info 注
-需要注意的是，定义的函数都应该是异步的，与函数调用时类型有关，后面会提到。
-:::
-
-### 函数参数规则
-
-如上所述，为了满足 RESTful API 的设计标准，因此 Modern.js 中 BFF 函数需要遵循一定的入参规则。
-
-函数参数分为两块，分别是请求路径中的动态部分和请求选项 `RequestOption`。
-
-#### Dynamic Path
-
-动态路由会作为函数第一部分的入参，每个入参对应一段动态路由。例如以下示例，uid 会作为前两个参数传递到函数中：
-
-```ts title="api/[level]/[id].ts"
-export default async (level: number, id: number) => {
-  const userData = await queryUser(level, uid);
-  return userData
-}
-```
-
-在调用时直接传入动态参数：
-
-```ts title="App.tsx"
-import { useState, useEffect } from 'react'
-import { get as getUser } from '@api/[level]/[id]'
-
-export default () => {
-  const [name, setName] = useState('')
-
-  useEffect(() => {
-    getUser(6, 001).then(
-      userData => setName(userData.name)
-    )
-  }, [])
-
-  return <div>{name}</div>
-}
-```
-
-#### RequestOption
-
-Dynamic Path 之后的参数是包含 querystring、request body 的对象 `RequestOption`，这个字段用来定义 `data` 和 `query` 的类型。
-
-在不存在动态路由的普通函数中，可以从第一个入参中获取传入的 `data` 和 `query`，例如：
-
-```ts title="api/hello.ts"
-import type { RequestOption } from '@modern-js/runtime/server'
-
-export async function post(
-  { query, data }: RequestOption<Record<string, string>, Record<string, string>>
-) {
-  // do somethings
-}
-```
-
-这里你也可以使用自定义类型：
-```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/runtime/server'
-
-type IQuery = {
-  // some types
-}
-type IData = {
-  // some types
-}
-
-export async function post(
-  { query, data }: { query:IQuery, data:IData }
-) {
-  // do somethings
-}
-```
-
-当函数文件使用动态路由规则时，动态路由会在 `RequestOption` 对象参数前。
-
-```ts title="api/[sku]/[id]/item.ts"
-export async function post(
-  sku: string,
-  id: string,
-  { data, query }: RequestOption<Record<string, string>, Record<string, string>>
-) {
-  // do somethings
-}
-```
-
-调用时也按照函数定义，传入对应的参数即可：
-
-```ts title="App.tsx"
-import { post } from '@api/[sku]/[id]/item'
-
-export default () => {
-  const addSku = () => {
-    post('0001'/* sku */, '1234' /* id */, {
-      query: { /* ... */ },
-      data: { /* ... */ },
-    })
-  }
-
-  return <div onClick={addSku}>添加 SKU</div>
-}
-```
-
-之前提到，定义的函数都应该是异步的，是因为在前端调用时会自动转换成 HTTP 接口调用，所以为了保持类型定义与实际调用体验统一，需要在定义 BFF 函数时将它设置为异步。

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

@@ -1,20 +0,0 @@
----
-title: BFF
----
-
-在**前后端分离**概念出现后一段时间发展中，前端部分能够做的事越来越多，前端需要一些面向 UI 的数据接口，因此业界引入了 BFF（Backends for Frontends）这一概念。
-
-它主要为了解决的问题包括：
-
-* 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
-* 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
-* 根据已有接口快速开发新产品。
-* 与第三方系统对接，例如登陆鉴权。
-
-Modern.js 官方支持了 BFF，并提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
-
-* 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
-* 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
-* 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
-* 完善的 TypeScript 支持。
-* 满足用户使用偏好，支持多框架扩展写法。