@modern-js/main-doc 2.1.0 → 2.3.0

package/zh/configure/app/tools/styled-components.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: styledComponents
+---
+
+# tools.styledComponents
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.styledComponents](https://modernjs.dev/builder/api/config-tools.html#tools-styledcomponents)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/tools/styledComponents.md'
+
+<Main />

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,37 @@
+---
+sidebar_label: tailwindcss
+---
+
+# tools.tailwindcss
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const tailwind = {
+  content: [
+    './config/html/**/*.html',
+    './config/html/**/*.ejs',
+    './config/html/**/*.hbs',
+    './src/**/*.js',
+    './src/**/*.jsx',
+    './src/**/*.ts',
+    './src/**/*.tsx',
+    './storybook/**/*',
+  ],
+  // 使用 source.designSystem 配置作为 Tailwind CSS Theme 配置
+  theme: source.designSystem,
+};
+```
+
+对应 [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/tools/terser.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: terser
+---
+
+# tools.terser
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.terser](https://modernjs.dev/builder/api/config-tools.html#tools-terser)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/tools/terser.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: tsChecker
+---
+
+# tools.tsChecker
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.tsChecker](https://modernjs.dev/builder/api/config-tools.html#tools-tschecker)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/tools/tsChecker.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: tsLoader
+---
+
+# tools.tsLoader
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.tsLoader](https://modernjs.dev/builder/api/config-tools.html#tools-tsloader)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/tools/tsLoader.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: webpackChain
+---
+
+# tools.webpackChain
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.webpackChain](https://modernjs.dev/builder/api/config-tools.html#tools-webpackchain)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpackChain.md'
+
+<Main />

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

@@ -0,0 +1,13 @@
+---
+sidebar_label: webpack
+---
+
+# tools.webpack
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.webpack](https://modernjs.dev/builder/api/config-tools.html#tools-webpack)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpack.md'
+
+<Main />

package/zh/configure/app/usage.mdx

@@ -0,0 +1,139 @@
+---
+sidebar_position: 0
+---
+
+# 配置使用
+
+Modern.js 中有两种配置，一个是编译时配置，一个是服务端运行时配置。
+
+编译时配置可以在两个位置进行配置：
+
+- 根路径下的 `modern.config.(ts|js|mjs)` 文件
+- `package.json` 文件
+
+:::info
+不支持同时在 package.json 中和 modern.config.ts 中配置同一个配置项，推荐优先在 modern.config.ts 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
+:::
+
+服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中自定义配置选项。
+
+## 在配置文件中配置
+
+Modern.js 的配置文件定义在项目的根目录下，支持 `.js`, `.ts` 和 `.mjs` 格式：
+
+- `modern.config.js`
+- `modern.config.ts`
+- `modern.config.mjs`
+
+### 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，请注意区分。
+
+## 本地调试配置
+
+为了便于本地调试配置，Modern.js 支持在项目根目录下创建 `modern.config.local.(ts|js|mjs)` 文件，用于覆盖 `modern.config.(ts|js|mjs)` 中的配置选项。
+
+### 示例
+
+比如，项目的 `modern.config.ts` 中配置了端口号为 `3000`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+如果你在本地调试时需要将端口号修改为 `3001`，但是又不希望修改当前项目的 `modern.config.ts` 文件，那么可以创建一个 `modern.config.local.ts` 文件，并添加以下配置：
+
+```ts title="modern.config.local.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+`modern.config.local.ts` 文件中的配置会与 `modern.config.ts` 中的配置进行深层合并，并覆盖 `modern.config.ts` 中的配置选项，因此 `server.port` 会被覆盖为 `3001`。
+
+### 注意事项
+
+在使用 `modern.config.local.ts` 时，请注意以下事项：
+
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 或 `modern start` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
+- 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
+
+```bash title=".gitingore"
+modern.config.local.ts
+modern.config.local.js
+modern.config.local.mjs
+```

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)。
+
+:::

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

@@ -0,0 +1,152 @@
+---
+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;
+```