@modern-js/main-doc 2.1.0 → 2.3.0

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 支持。
-- 满足用户使用偏好，支持多框架扩展写法。

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

@@ -1,42 +0,0 @@
----
-sidebar_position: 2
-title: 函数写法 & 框架写法
----
-
-运行时框架支持也是 **BFF** 中重要的一环。Modern.js 支持通过插件扩展 BFF 的运行时框架，并提供了一系列内置插件，开发者可以直接使用对应框架的约定和生态。
-
-插件中兼容了这些框架大部分的规范，每一种框架都需要提供两类扩展写法 BFF 函数的方式，分别是**函数写法**和**框架写法**。
-
-:::note
-当前 `api/` 目录结构是否为框架写法由对应的插件决定，Modern.js 并不关心。
-:::
-
-## 函数写法
-
-当插件认为当前为函数写法时，必须支持在 `api/_app.ts` 中编写中间件，用来扩展 BFF 函数。
-
-Modern.js 会收集 `api/_app.ts` 中的中间件，并传递给插件，由插件将中间件注入运行时，例如：
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware(myMiddleware);
-});
-```
-
-:::note
-不同插件的中间件的写法不一定相同，详情可见[运行时框架](/docs/guides/advanced-features/bff/frameworks)。
-:::
-
-## 框架写法
-
-框架写法是一种使用框架结构来扩展 BFF 函数的方式。和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
-
-框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
-
-多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时，才需要使用框架写法。
-
-:::note
-不同插件框架写法的目录结构不一定相同，详情可见[运行时框架](/docs/guides/advanced-features/bff/frameworks)。
-:::

package/zh/guides/advanced-features/code-split.md

@@ -1,76 +0,0 @@
----
-title: 代码分割
-sidebar_position: 6
----
-
-代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
-
-:::info
-使用 Modern.js [约定式路由](/docs/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，包裹 `Suspense` 组件，无需自行进行代码分割。
-:::
-
-- `import`
-- `React.lazy`
-- `loadable`
-
-## import
-
-使用动态 `import()` 语法，`import` 接收的 JS 模块将作为一个新的打包入口被打包到单独的 JS 文件中。例如：
-
-```ts
-import('./math').then(math => {
-  console.log(math.add(16, 26));
-});
-```
-
-`./math` 路径对应的 JS 模块会被打包到单独的 JS 文件中。
-
-## React.lazy
-
-React 官方提供的组件代码分割的方式。
-
-:::caution
-React 17 及以下版本不支持 SSR，建议 React17 的 SSR 应用使用 loadable。
-:::
-
-```ts
-import React, { Suspense } from 'react';
-
-const OtherComponent = React.lazy(() => import('./OtherComponent'));
-const AnotherComponent = React.lazy(() => import('./AnotherComponent'));
-
-function MyComponent() {
-  return (
-    <div>
-      <Suspense fallback={<div>Loading...</div>}>
-        <section>
-          <OtherComponent />
-          <AnotherComponent />
-        </section>
-      </Suspense>
-    </div>
-  );
-}
-```
-
-`React.lazy` 更多用法请见 [React lazy](https://zh-hans.reactjs.org/docs/code-splitting.html#reactlazy)。
-
-## loadable
-
-使用 `loadable` API，示例如下：
-
-```ts
-import loadable from '@modern-js/runtime/loadable';
-
-const OtherComponent = loadable(() => import('./OtherComponent'));
-
-function MyComponent() {
-  return <OtherComponent />;
-}
-```
-
-`loadable` 更多用法请见 [loadable API](/docs/apis/app/runtime/utility/loadable)。
-
-:::info 注
-`loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
-:::

package/zh/guides/advanced-features/compatibility.md

@@ -1,73 +0,0 @@
----
-title: 客户端兼容性
-sidebar_position: 5
----
-
-## Browserslist 配置
-
-Modern.js 支持在项目根目录 `package.json` 文件中的 `browserslist` 字段（或单独的 `.browserslistrc` 文件）指定项目覆盖的目标浏览器范围。该值会被 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 和 [`autoprefixer`](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
-
-Modern.js 中默认值如下:
-
-```js
-['> 0.01%', 'not dead', 'not op_mini all'];
-```
-
-可以在[这里](https://github.com/browserslist/browserslist)了解如何自定义浏览器范围。
-
-查看 Modern.js Builder 文档了解更多 [Browserlist](https://modernjs.dev/builder/zh/guide/advanced/browserslist.html) 相关内容。
-
-:::note
-Modern.js 支持配置 [output.overrideBrowserlist](/docs/configure/app/output/override-browserslist) 覆盖默认 browserlist 值。
-:::
-
-## Polyfill
-
-### 编译时 Polyfill
-
-Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js) 引入对应的 Polyfill 代码。
-
-默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
-
-:::info 注
-对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/docs/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
-:::
-
-### 运行时按需 Polyfill
-
-Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：
-
-- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
-- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
-
-可以通过微生成器开启该功能：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「基于 UA 的 Polyfill」功能
-```
-
-执行命令后，在 `modern.config.ts` 中注册 Polyfill 插件:
-
-```ts title="modern.config.ts"
-import polyfillPlugin from '@modern-js/plugin-polyfill';
-
-// https://modernjs.dev/docs/apis/app/config
-export default defineConfig({
-  plugins: [..., polyfillPlugin()],
-});
-```
-
-配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
-
-```js
-<script src="/__polyfill__" crossorigin></script>
-```
-
-在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
-
-![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
-
-:::caution 注意
-该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
-:::

package/zh/guides/advanced-features/eslint.md

@@ -1,146 +0,0 @@
----
-title: ESLint 规则集
-sidebar_position: 8
----
-
-<!-- 参考 [实战教程 - 确认编程环境](../handbook/c03-ide/3.1-setting-up) 确保本地 IDE 环境正常。 -->
-
-**Modern.js ESLint 规则集**是全量的 **ESLint** 规则集合，包含 `@modern-js` （对于 Node.js 项目的 Lint 规则）和 `@modern-js-app`（对于前端项目的 Lint 规则）。
-
-下面以具体问题介绍更多 ESLint 用法。
-
-## Q: 如何处理 Lint
-
-### 实时自动修复
-
-多数问题会被 ESLint 规则的自动修复功能或 [Prettier](https://prettier.io/) 的代码格式化功能（已被集成到 ESLint 里）自动解决，开发者不需要关心问题的细节和解决方式。
-
-:::info 注
-主要在 IDE 保存文件的环节执行这种自动修复，少数漏网之鱼会在提交代码环节被自动修复。
-:::
-
-### 批量自动修复
-
-在少数情况下，比如旧项目迁移的时候，可以执行以下命令，批量修复和检查所有文件：
-
-```bash
-pnpm run lint:error
-```
-
-### 人工修复
-
-对于无法自动修复的问题，可以在 IDE 里点击问题提示框里的规则链接，打开这条规则的文档，查看问题的解释和解决方案。
-
-### 声明例外情况
-
-目前阶段，有些规则并不能做到足够智能，多数情况下会有很大收益，在少数情况下也许不适用。但如果为了这些少数情况就把整个规则关掉或改掉，得不偿失。
-
-这种情况下可以用 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 注释，对符合**少数情况**的代码块做标注，声明这里是一个例外，应该忽略。比如：
-
-```js
-/* eslint-disable filenames/match-exported */
-...
-/* eslint-enable filenames/match-exported */
-```
-
-:::info 注
-在 VS Code 编辑器里输入 eslint，会自动出现关于 "eslint-disable" 的提示框，选择提示选项生成对应注释对。
-:::
-
-【Modern.js ESLint 规则集】要求 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 必须成对使用，必须明确表达要影响的范围，以及在这个范围内明确表达要禁用什么规则，目的是让**例外**有明确的、最小化的范围，避免 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 被滥用，导致不属于例外的代码也被禁用了规则。
-
-## Q: 如何自定义 ESLint 规则
-
-### 仓库根目录下 `package.json` 里的 "eslintConfig" 字段
-
-这个地方是整个仓库的默认 ESLint 配置，是针对纯 Node.js 代码（只能在 Node.js 里运行）设计的。
-
-如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置。该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
-
-```json
- "eslintConfig": {
-    "extends": [
-      "@modern-js"
-    ],
-    "rules": {
-      "filenames/match-exported": "off"
-    }
-  },
-
-```
-
-### `src/.eslintrc.js` 文件
-
-Modern.js 的应用工程、模块工程，源代码目录里都会默认有这个配置文件，是针对 Universal JS 代码设计的。
-
-:::info 注
-Universal JS 代码是既能浏览器端也能在服务器端运行的代码。
-:::
-
-如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置，该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
-
-```js
-// eslint-disable-next-line import/no-commonjs
-module.exports = {
-  root: true,
-  extends: ['@modern-js-app'],
-  parserOptions: {
-    tsconfigRootDir: __dirname,
-    project: ['../tsconfig.json'],
-  },
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-
-如果有需要，还可以继续在不同的子目录里增加 `.eslintrc.js` 文件，针对这个子目录里的代码做特殊配置：
-
-```js
-module.exports = {
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-
-:::tip 提示
-注意：没有必要使用 `extends` 字段，会自动继承父目录的配置。
-:::
-
-### package.json 里的 `eslintIgnore` 字段
-
-把包含 `.js`、`.jsx`、`.ts`、`.tsx` 文件、但不需要做代码检查和自动修复的目录，添加到 `eslintIgnore` 里，可以优化 ESLint 检查的速度，比如：
-
-```json
- "eslintIgnore": [
-    "node_modules",
-    "dist",
-    "output"
-  ],
-```
-
-## Q: 如何升级 ESLint 插件的版本
-
-只要不是 Major 版本的变化（不符合 [Semver](https://semver.org/) 规则的 `^` 符号），就可以直接在业务项目的 `package.json` 里指定这个依赖，删除 Lock 文件（或尝试手动删除 Lock 文件中这个包名的内容），执行 `pnpm install` 重新安装依赖并且生成新的 Lock 文件。
-
-做完这些操作之后，在业务项目的 `./node_modules` 目录里，这个插件应该只存在一份，并且升级到了你指定的版本。
-
-:::tip 提示
-- Major 版本就是主版本号。更多信息，请阅读【[Semantic Versioning](https://semver.org/#summary)】。
-- 所有被 Modern.js 封装的上游项目（比如 ESLint、[ESLint 插件](https://eslint.org/docs/user-guide/configuring/plugins#plugins)、[React Router](https://reactrouter.com/) 等），也都可以这样升级。
-- Modern.js 也会在每次发版中尽量及时的升级这些上游依赖。
-- Major 版本的升级需要由 Modern.js 来发版。
-:::
-
-## Q: WebStorm 有时候会报 ESLint 错误
-
-由于 WebStorm 认为 ESLint 执行目录是根据 `.eslintrc` 文件来决定的。因此 `src/.eslintrc` 文件位置的放置会导致 `tsconfig.json` 文件指定的位置（项目根目录下）在 `src/` 目录下找不到。
-
-此时需要手动配置一下：
-
-```json
---parser-options=project:../tsconfig.json
-```
-
-![webstorm-lint-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/webstorm-lint-error.png)

package/zh/guides/advanced-features/low-level.md

@@ -1,42 +0,0 @@
----
-title: 配置底层工具
-sidebar_position: 11
----
-
-## 使用方式
-
-Modern.js 内部默认集成了 [Babel](https://babeljs.io/)、[TypeScript](https://www.typescriptlang.org/)、[Webpack](https://webpack.js.org/)、[PostCSS](https://postcss.org/)、[Tailwind CSS](https://tailwindcss.com/) 等工具。通常情况下，默认配置能够满足大多业务开发需求。当有特殊需求时，可以通过底层配置来实现。
-
-以配置 Webpack 为例，只需要在 `modern.config.ts` 中添加 [`tools.webpack`](/docs/configure/app/tools/webpack) 即可：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    webpack: config => {},
-  },
-});
-```
-
-`tools` 命名空间下的配置都可以设置为 `Object` 或者 `Function`。
-
-值为 `Object` 时，会与内部默认配置进行合并，具体合并策略参考对应的配置选项文档（见下表）。
-
-值为 `Function` 时，第一个参数为内部的默认配置对象，可以直接修改这个对象不做返回，也可以返回一个新的对象或者合并后的对象作为最终结果。
-
-## 底层配置明细
-
-目前提供的底层配置如下表：
-
-| 底层工具          | 配置                                                                  |
-| ----------------- | --------------------------------------------------------------------- |
-| DevServer         | [tools.devServer](/docs/configure/app/tools/dev-server)               |
-| Babel             | [tools.babel](/docs/configure/app/tools/babel)                        |
-| styled-components | [tools.styledComponents](/docs/configure/app/tools/styled-components) |
-| PostCSS           | [tools.postcss](/docs/configure/app/tools/postcss)                    |
-| Less              | [tools.less](/docs/configure/app/tools/less)                          |
-| Sass              | [tools.sass](/docs/configure/app/tools/sass)                          |
-| webpack           | [tools.webpack](/docs/configure/app/tools/webpack)                    |
-| Minify CSS        | [tools.minifyCss](/docs/configure/app/tools/minify-css)               |
-| terser            | [tools.terser](/docs/configure/app/tools/terser)                      |
-| Tailwind CSS      | [tools.tailwind](/docs/configure/app/tools/tailwindcss)               |
-| Autoprefixer      | [tools.autoprefixer](/docs/configure/app/tools/autoprefixer)          |

package/zh/guides/advanced-features/ssg.md

@@ -1,130 +0,0 @@
----
-title: 静态站点生成（SSG）
-sidebar_position: 4
----
-
-SSG（Static Site Generation）是一种基于数据与模板，在构建时渲染完整静态网页的技术解决方案。
-
-我们首先需要执行 `pnpm run new` 启用 SSG 功能：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「SSG」功能
-```
-
-执行命令后，在 `modern.config.ts` 中注册 SSG 插件：
-
-```ts title="modern.config.ts"
-import ssgPlugin from '@modern-js/plugin-ssg';
-
-// https://modernjs.dev/docs/apis/app/config
-export default defineConfig({
-  output: {
-    ssg: true,
-  },
-  plugins: [..., ssgPlugin()],
-});
-```
-
-SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
-
-### 在约定式路由中使用
-
-**约定式路由**中， Modern.js 根据入口下的文件结构生成路由，因此框架能够收集完整的路由信息。
-
-例如，以下是一个使用约定式路由的项目目录结构：
-
-```
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
-
-上述文件目录将会生成以下三条路由：
-
-- `/`
-- `/user`
-- `/user/profile`
-
-:::note
-如果还不了解约定式路由的规则，可以先查看[路由](/docs/guides/basic-features/routes)。
-:::
-
-在 `src/routes/page.tsx` 中添加组件代码：
-
-```jsx title="src/routes/page.tsx"
-export default () => {
-  return <div>Index Page</div>;
-};
-```
-
-SSG 也是在 Node.js 环境渲染页面，因此我们可以在**开发阶段开启 SSR**，提前在暴露代码问题，验证 SSG 渲染效果：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  server: {
-    ssr: process.env.NODE_ENV === 'development',
-  }
-}
-```
-
-在项目根路径下执行 `pnpm run dev` 命令，查看 `dist/` 目录，此时只生成一个 HTML 文件 `main/index.html`。
-
-在项目根路径下执行 `pnpm run build` 命令，构建完成后，查看 `dist/` 目录，此时生成 `main/index.html`、`main/user/index.html` 和 `main/user/profile/index.html` 三个 HTML 文件，内容分别对应上述三条路由。
-
-**约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `Index Page` 的文本内容，这正是 SSG 的效果。
-
-执行 `pnpm run serve` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
-
-### 在自控式路由中使用
-
-**自控式路由**是通过组件代码自定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。此时需要用户提前告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
-
-例如有以下代码，包含多条路由，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`：
-
-```tsx title="src/App.tsx"
-import { useRuntimeContext } from '@modern-js/runtime';
-import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
-import { StaticRouter } from '@modern-js/runtime/router/server';
-
-const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
-
-export default () => {
-  const { context } = useRuntimeContext();
-  return (
-    <Router location={context.request.pathname}>
-      <Routes>
-        <Route index element={<div>index</div>} />
-        <Route path="about" element={<div>about</div>} />
-      </Routes>
-    </Router>
-  );
-};
-```
-
-如果我们希望同时开启 `/about` 的 SSG 功能，可以配置 `output.ssg`，告知 Modern.js 开启指定路由的 SSG 功能。
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  output: {
-    ssg: {
-      routes: ['/', '/about'],
-    },
-  },
-});
-```
-
-执行 `pnpm run build` 与 `pnpm run serve` 后，访问 `http://localhost:8080/about`，在 Preview 视图中可以看到页面已经完成渲染。
-
-查看构建产物文件，可以看到 `dist/` 目录中，新增了一个 `main/about/index.html` 文件。
-
-:::info
-以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
-:::