+ {!posts &&
+ );
+}
+```
+
+可以看到我们在首页组件维护了一个 `posts` 状态，当 `posts` 是 `undefined` 时，我们认为是数据尚未加载完成。所以我们可以加入一个 `useEffect`让他在组件加载后对 API 路由发起一个请求，去查询目前所有的文章列表：
+
+```tsx
+// pages/index.tsx
+
+import React, { useEffect, useState } from 'react';
+import { history } from 'umi';
+
+export default function HomePage() {
+ const [posts, setPosts] = useStateLoading...
} + {posts &&
+ {posts.map(post =>
}
+
+
)}
+ history.push(`/posts/${post.id}`)}>
+
+ {post.title}
+
+ {!posts &&
+ );
+}
+```
+
+可以看到我们加入了一个 `refresh` 函数，他会帮我们从 API 路由查询目前的文章列表。若你现在访问这个页面，应该可以看到一开始是 `Loading ...`
+等一阵子就会有全部文章的标题被渲染出来的效果。
+
+
+
+最后只要帮他加一点样式：
+
+
+
+---
+
+其他页面留给读者实作，可以加入自己的想法及样式的设计来实现，源代码可参考：[https://github.com/umijs/umi-blog-example/blob/main/src/pages](https://github.com/umijs/umi-blog-example/blob/main/src/pages)
+
+## 部署
+
+最后，将你的项目提交到 git 服务上，然后登入 [Vercel](https://vercel.com):
+
+
+
+如果你的项目代码是提交到 GitHub，那么建议你选择 GitHub 登入，这样你就可以在 Vercel 直接导入现有的代码仓库了 👍
+
+
+
+导入以后，他会自动检测到这个项目是使用 Umi.js 框架搭建的，并且自动化完成相关的配置，因此直接点击 **Deploy** 即可开始部署！
+
+等他部署完成以后，你的博客就正式上线啦 👍
+
+---
+
+但这个时候你会发现，网站内的 API 路由没有办法正常工作，这是因为他缺少了连线到数据库需要的环境变量。我们需要帮他配置一下：
+
+
+
+在项目配置页面，下面有可以设置环境变量的地方：
+
+
+
+你可以把 `DATABASE_URL`, `JWT_KEY` 等等你用到的环境变量从这里传入。
+
+
+
+加入环境变量以后，点击 **Redeploy** 重新部署一次版本，你的博客就能正常运作啦～
diff --git a/docs/docs/blog/legacy-browser.en-US.md b/docs/docs/blog/legacy-browser.en-US.md
new file mode 100644
index 000000000000..d3b3d7e09c74
--- /dev/null
+++ b/docs/docs/blog/legacy-browser.en-US.md
@@ -0,0 +1,127 @@
+---
+toc: content
+order: 6
+group:
+ title: Blog
+---
+
+# 非现代浏览器兼容
+
+## 默认兼容说明
+
+Umi 4 默认不支持 IE ，编译兼容目标 `targets` 为 `chrome: 80` ，如需调整，请指定明确的 [targets](../docs/api/config#targets) ：
+
+```ts
+// .umirc.ts
+
+export default {
+ targets: { chrome: 67 },
+};
+```
+
+若想反馈更多关于兼容性的问题，或参与讨论，请前往：[issue / 8656](https://github.com/umijs/umi/issues/8658)
+
+## 兼容非现代浏览器
+
+如果你并不需要兼容至 IE ，只为了提升项目对非现代浏览器的兼容性，可调整兼容目标 [targets](../docs/api/config#targets) 。
+
+Umi 4 默认使用现代构建工具，产物生成至 `es6` ，如果你有要打包为 `es5` 产物的考量，请调整配置：
+
+```ts
+// .umirc.ts
+
+export default {
+ jsMinifier: 'terser',
+ cssMinifier: 'cssnano',
+};
+```
+
+## 兼容旧时代浏览器 ( IE 11 )
+
+由于 IE 已经淘汰不再主流，当需要兼容至 IE 时，请阅读以下对策。
+
+### 框架自带的 legacy mode
+
+Umi 4 自带提供一个 `legacy` 配置用于构建降级（使用限制等详见 [legacy](../docs/api/config#legacy) ）：
+
+```ts
+// .umirc.ts
+
+export default {
+ legacy: {},
+};
+```
+
+默认仅在构建时生效，将尝试构建能使 IE 兼容的产物。
+
+### legacy mode 的更多自定义
+
+`legacy` 开启时，默认会转译全部 `node_modules` ，这在大型项目中，会极大的增加构建时间。
+
+若你了解当前项目使用的第三方依赖情况（知道哪些不再提供 `es5` 产物了），可以关闭 `node_modules` 的转换，改为使用 [`extraBabelIncludes`](https://umijs.org/docs/api/config#extrababelincludes) 定点配置那些需要额外纳入转换范围的包。
+
+一个例子：
+
+```ts
+// .umirc.ts
+
+export default {
+ legacy: {
+ nodeModulesTransform: false,
+ },
+ extraBabelIncludes: ['some-es6-pkg', /@scope\//],
+};
+```
+
+### 提高兼容的鲁棒性
+
+`legacy` 选项并不能 100% 保证产物 **没有边界情况** 的运行在被淘汰的浏览器内，你可能还需要添加 **前置的** 全量 polyfill 来增强项目的 [鲁棒性](https://baike.baidu.com/item/%E9%B2%81%E6%A3%92%E6%80%A7/832302) 。
+
+```ts
+// .umirc.ts
+
+export default {
+ headScripts: [
+ 'http://polyfill.alicdn.com/v3/polyfill.min.js', // or https://polyfill.io/v3/polyfill.min.js
+ ],
+ legacy: {},
+};
+```
+
+参考的思路有：
+
+| 方案 | 说明 |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CDN 引入 | 以 cdn 形式引入 **script 形式且前置的** 、目标浏览器环境缺少的 polyfill js 文件，如 [es6-shim](https://github.com/paulmillr/es6-shim) 。 |
+| 人工 core-js | 利用 [core-js](https://github.com/zloirock/core-js) 系工具，如通过 [core-js-builder](https://github.com/zloirock/core-js/tree/master/packages/core-js-builder) 构建自己需要的 polyfill 产物，再以 **前置 script 脚本** 形式引入项目。 |
+| 动态 polyfill 服务 | 使用根据当前浏览器请求 UA 动态下发所需 polyfill 的服务，比如 [polyfill.io](https://polyfill.io/v3/polyfill.min.js) ，考虑到速度，可使用国内的 [alicdn polyfill.io](http://polyfill.alicdn.com/v3/polyfill.min.js) 服务。另外，你还可以使用 [polyfill-service](https://github.com/Financial-Times/polyfill-service) 自建相同的动态 polyfill 下发服务。 |
+
+注：
+
+1. 当你处于内外网隔离开发环境时，可以考虑将全部 polyfill 的 js 内容传入内网，在内网的 CDN 使用，或放入 public 目录等方式使用。
+
+2. 使用 script 前置引入的意义在于，在项目 js 资源运行前就准备好一个完整的、被 polyfill 过 api 的环境。
+
+### 在开发环境验证
+
+推荐的做法是：构建后在本地通过 [`umi preview`](../docs/api/commands#preview) 或 [`serve`](https://www.npmjs.com/package/serve) 、nginx 等启动服务，来验证产物的 IE 11 运行可行性。
+
+当你需要在开发环境验证时：
+
+1. 将 `legacy.buildOnly` 置为 `false` 。
+
+2. 由于 react fresh 、hmr 等开发注入的 es6 代码始终在第一位运行，你需要以 script 形式添加一个前置的 polyfill ，提前准备好环境。
+
+```ts
+// .umirc.ts
+
+const isProd = process.env.NODE_ENV === 'production';
+export default {
+ legacy: {
+ buildOnly: false,
+ },
+ headScripts: isProd ? [] : ['http://polyfill.alicdn.com/v3/polyfill.min.js'],
+};
+```
+
+注：IE 11 并不能完整支持开发时的热更新，且缓存可能需要人为在控制台进行清除后才能看到最新的页面，请做好准备。
diff --git a/docs/docs/blog/mfsu-faster-than-vite.en-US.md b/docs/docs/blog/mfsu-faster-than-vite.en-US.md
new file mode 100644
index 000000000000..19df5e5a07f9
--- /dev/null
+++ b/docs/docs/blog/mfsu-faster-than-vite.en-US.md
@@ -0,0 +1,41 @@
+---
+order: 3
+toc: content
+group:
+ title: Blog
+---
+
+# 比 Vite 还快的 MFSU
+
+Loading...
} + {posts && ( +
+ {posts.map((post) => (
+
+ )}
+
+
+ ))}
+ history.push(`/posts/${post.id}`)}>
+
+ {post.title}
++ 编者按：Change the code, don't Workaround! Webpack + 慢就去改他，优化到位后，Bundle 也可以很快。此方案会在 Umi 4 + 中默认开启，适用于既要 Webpack 功能与生态，又想要 Vite 速度的同学们。 +
+ +Umi 4 中同时支持 webpack 和 vite 两种构建方式，跑通了后，迫不及待对比了 Vite 和 Webpack + MFSU 的效果，结果有点意外。关于什么是 MFSU，我在[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)中有一段详细介绍。 + ++ + 两个示例、四种模式、四个维度的对比。 + + 两个示例分别是大型的全量 ant-design-pro 和小型的 libs example；四种模式分别是 webpack、webpack + MFSU、webpack + MFSU with esbuild mode、Vite in umi；四个维度分别是无缓存的冷启动、有缓存的热启动、修改代码后的热更新、页面打开速度。 +
+ +多说几点和统计相关的。上述 webpack 相关模式全部开启物理缓存；Vite 是 Umi 中集成后的 Vite，也有担心是不是 Umi 对于 Vite 的误用，经开发者确认，基本排除误用的可能性，大段时间消耗在预编译依赖上；Ant Design Pro 中包含 less 的使用，这是使用 esbuild 无法加速的部分，这有影响，但对于不同模式应该是公平的；下图数据是本地用 13-inch M1 2022 重启电脑后跑 5 次后平均取值的结果；Vite 的热更速度没统计是因为由于 esm 的特性，改完后要等请求过来后处理完才算结束，无法统计，但肯定是很快的。 + +直接上结果。有兴趣手动验证的同学可到 umijs/umi 仓库的不同 example 目录下执行 npm run dev 验证。 + + + ++ 图：全量 ant-design-pro 速度对比图 +
+ + + ++ 图：libs example 速度对比图 +
+ +可以看到，**在这几个场景下，MFSU with esbuild 数据领先。** 四个模式的页面打开速度差不多，所以对比数据没在图中列出，这也是让我意外的点，原以为 Vite 请求多会让页面打开速度变慢，也有可能项目还不够复杂？ diff --git a/docs/docs/blog/mfsu-independent-usage.en-US.md b/docs/docs/blog/mfsu-independent-usage.en-US.md new file mode 100644 index 000000000000..68857e23e3c4 --- /dev/null +++ b/docs/docs/blog/mfsu-independent-usage.en-US.md @@ -0,0 +1,257 @@ +--- +toc: content +order: 4 +group: + title: Blog +--- + +# 独立使用 MFSU + +`MFSU` 支持独立在非 umijs 项目中使用，本文将会介绍如何将 `MFSU` 接入你的 webpack 项目。 + +## 示例项目 + +如何接入 MFSU ？提供以下几个 示例项目 配置供参考： + +Webpack 配置示例：examples/mfsu-independent + +CRA v5 配置示例：cra-v5-with-mfsu-example + +## 安装 + +首先安装 `mfsu` 的依赖： + +```bash + pnpm add -D @umijs/mfsu +``` + +## 配置 MFSU + +配置 MFSU 一共需要简单的四步操作，请确保以下所有行为都只在开发环境生效。 + +### 1. 初始化实例 + +第一步，初始化一个 `MFSU` 实例，这是 `MFSU` 的基础： + +```js +// webpack.config.js + +const { MFSU } = require('@umijs/mfsu'); +const webpack = require('webpack'); + +// [mfsu] 1. init instance +const mfsu = new MFSU({ + implementor: webpack, + buildDepWithESBuild: true, +}); +``` + +### 2. 添加中间件 + +第二步，添加 `MFSU` 的 `devServer` 中间件到 webpack-dev-server 中，他将为你提供 `MFSU` 所需打包后的资源： + +#### webpack 5 + +```js +// webpack.config.js + +module.exports = { + devServer: { + // [mfsu] 2. add mfsu middleware + setupMiddlewares(middlewares, devServer) { + middlewares.unshift(...mfsu.getMiddlewares()); + return middlewares; + }, + }, +}; +``` + +#### webpack 4 + +```js +// webpack.config.js + +module.exports = { + devServer: { + // [mfsu] 2. add mfsu middleware + onBeforeSetupMiddleware(devServer) { + for (const middleware of mfsu.getMiddlewares()) { + devServer.app.use(middleware); + } + }, + }, +}; +``` + +### 3. 配置转换器 + +第三步，你需要配置一种源码转换器，他的作用是用来收集、转换依赖导入路径，替换为 `MFSU` 的模块联邦地址（中间件所提供的）。 + +此处提供两种方案：`babel plugins` 或 `esbuild handler` ，一般情况下选择 `babel plugins` 即可。 + +#### Babel Plugins + +向 `babel-loader` 添加 `MFSU` 的 `babel plugins` 即可。 + +```js +// webpack.config.js + +module.exports = { + module: { + rules: [ + // handle javascript source loader + { + test: /\.[jt]sx?$/, + exclude: /node_modules/, + use: { + loader: 'babel-loader', + options: { + plugins: [ + // [mfsu] 3. add mfsu babel plugins + ...mfsu.getBabelPlugins(), + ], + }, + }, + }, + ], + }, +}; +``` + +#### Esbuild handler + +另一种方案是使用内置提供的 `esbuild-loader` 来处理 `js/ts` 资源，**仅用于开发环境** 。 + +:::info +使用这种方案的好处是：在开发环境获得比 `babel` 更快的编译和启动速度 +::: + +```js +// webpack.config.js + +const { esbuildLoader } = require('@umijs/mfsu'); +const esbuild = require('esbuild'); + +module.exports = { + module: { + rules: [ + { + test: /\.[jt]sx?$/, + exclude: /node_modules/, + use: { + loader: esbuildLoader, + options: { + handler: [ + // [mfsu] 3. add mfsu esbuild loader handlers + ...mfsu.getEsbuildLoaderHandler(), + ], + target: 'esnext', + implementation: esbuild, + }, + }, + }, + ], + }, +}; +``` + +:::warning +什么时候我不应该使用 esbuild 方案？1. 我有自定义的 `babel plugins` 必须在开发环境使用
2. 我需要显示 `css-in-js` 的开发环境友好类名（一般由 babel plugin 提供支持）
3. 在开发环境多适配一套 `esbuild-loader` 的成本大于配置 `babel plugins` 的成本 +::: + +### 4. 设定 webpack 配置 + +第四步，调用 `MFSU` 提供的方法改变你的 webpack 配置，在这里只有增量行为，你无需担心会影响到你原来的配置内容。 + +如下代码所示，`mfsu.setWebpackConfig` 是一个异步方法，为了调用他你需要将原来的 webpack 配置单独抽为一个对象 `config` 之后，再将调用此方法的返回值导出。 + +```js +// webpack.config.js + +const config = { + // origin webpack config +}; + +const depConfig = { + // webpack config for dependencies +}; + +// [mfsu] 4. inject mfsu webpack config +const getConfig = async () => { + await mfsu.setWebpackConfig({ + config, + depConfig, + }); + return config; +}; + +module.exports = getConfig(); +``` + +到此为止，`MFSU` 完全配置完毕，下面可以开始启动项目使用。 + +## 使用 + +进行完 4 步配置后，启动你的项目，你可以从项目根目录得到 `.mfsu` 文件夹，即 `MFSU` 缓存文件夹，请将其添加到 git 的忽略列表（这些缓存文件你不应该提交他们）： + +```bash +# .gitignore + +.mfsu +``` + +符合预期时，你已经可以享受 `MFSU` 带来的好处，包括 `esbuild` 快速的打包和二次热启动的提速。 + +## 其他配置 + +以下是其他你可能会用到的 `MFSU` 实例配置： + +```js +const mfsu = new MFSU({ + cwd: process.cwd(), +}); +``` + +其他 Options: + +| option | default | description | +| :-------------------- | :----------------------- | :--------------------------------------------------------------------- | +| `cwd` | `process.cwd()` | 项目根目录 | +| `getCacheDependency` | `() => {}` | 用返回值来对比，使 MFSU cache 无效的函数 | +| `tmpBase` | `${process.cwd()}/.mfsu` | MFSU 缓存存放目录 | +| `unMatchLibs` | `[]` | 手动排除某些不需要被 MFSU 处理的依赖 | +| `runtimePublicPath` | `undefined` | 同 umijs > [`runtimePublicPath`](../docs/api/config#runtimepublicpath) | +| `implementor` | `undefined` | webpack 实例，需要和项目内使用的唯一实例一致 | +| `buildDepWithESBuild` | `false` | 是否使用 `esbuild` 打包依赖 | +| `onMFSUProgress` | `undefined` | 获取 MFSU 编译进度的回调 | + +## 常见问题 + +#### 如何保证我的 MFSU 配置只在开发环境生效？ + +使用环境标识避免所有 `MFSU` 在生产环境构建时的配置侵入： + +```js +const isDev = process.env.NODE_ENV === 'development' + +const mfsu = isDev + ? new MFSU({ + implementor: webpack, + buildDepWithESBuild: true, + }) + : undefined + +// e.g. +{ + test: /\.[jt]sx?$/, + exclude: /node_modules/, + use: { + loader: 'babel-loader', + options: { + plugins: [ + ...(isDev ? [] : mfsu.getBabelPlugins()) + ] + } + } +} +``` diff --git a/docs/docs/blog/umi-4-rc.en-US.md b/docs/docs/blog/umi-4-rc.en-US.md new file mode 100644 index 000000000000..a7a85d7498f3 --- /dev/null +++ b/docs/docs/blog/umi-4-rc.en-US.md @@ -0,0 +1,150 @@ +--- +toc: content +order: 2 +group: + title: Blog +--- + +# Umi 4 RC 发布 + +大家好，Umi 4 经过几个月的开发，终于要和大家见面了。相比 Umi 2 到 3，3 到 4 的变化是巨大的，开发时间也更长，但我们尽量把对于开发者的影响降低到最小。按捺住激动的心情，在此先和大家分享下都有哪些变化。 + +🎉 新官网和文档
🚀 MFSU V3 & 默认开启
🎭 双构建引擎和 ESMi
🕸 Webpack 5
⛹🏾♂️ React Router 6 & 新路由
🐹 最佳实践迭代
🛡️ 依赖预打包
🤺 Umi Max
🐛 Low Import 研发模式
⚠️ 强约束功能集成
🎈 Import All From Umi 迭代
🍀 srcTranspiler 和 depTranspiler
🌼 jsMinifier 和 cssMinifier
🌸 应用元数据
❄️ 微生成器
🧪 贴心小改进
+ +
+ 新官网和文档。 + 下图是新官网的首页，包括重新梳理的文档、信息结构、以及新写的文档插件。目前包含基础的配置、API、升级和快速上手等基础文档，剩余文档还在紧张编写中。有个变化是之前插件的文档集成到 + Umi 官网中，成为 Umi Max 的一部分，之后无需跳转。 +
+ + + ++ MFSU V3 & 默认开启。 + MFSU 更新了他的第三个大版本，如果你有用 Umi 3 内置的 MFSU 并遇到问题，建议重新尝试，这个版本有很多改进，解决基本所有之前可能会遇到的诡异问题，并且编译速度和页面打开速度都更快。昨天我还有写一篇 + [《比 Vite 更快的 MFSU》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ==&mid=2247484624&idx=1&sn=2addfa8cc2511fbea91faf831195788f)。基于此，我们自信地把这个功能在 + Umi 4 中默认开启。还有值得一提的是，MFSU 可脱离 Umi 运行。 +
+ + + ++ 双构建引擎和 ESMi。 + Umi 4 提供 Vite 和 Webpack 两种构建模式供开发者选择，并尽可能保证他们之间功能的一致性，可能有些同学会喜欢 + dev 用 vite，build 用 webpack 这样的组合。同时基于 Vite 模式实现了 ESMi 的 Client + 端，ESMi 依赖服务端，在外网还无法使用。 +
+ ++ Webpack 5。Umi 4 + 默认使用 webpack 5 并开启物理缓存。 +
+ ++ + React Router 6 & 新路由。 + + Umi 4 的路由基于 React Router 6 实现，个人非常喜欢这个版本，因为 Remix 的原因，React + Router 6 从设计上考虑了配置式路由的场景，让我得以删除大量 Umi 3 中关于路由渲染的代码。同时基于此，设计了新的路由结构，方便扩展和在未来处理路由的约定式请求。 +
+ ++ 最佳实践迭代。 + 针对之前 umijs/plugins 仓库中的插件进行了重写、升级，并整合到主仓库。这么做是为了更好的顶层设计，让官方插件之间的风格更一致。 +
+ ++ 依赖预打包。 + 由于服务企业内部，安全和稳定是其中很重要点，加上最近 colors 和 faker.js 闹得社区沸沸扬扬，谁都不希望睡一觉醒来，自己负责的业务挂了，还背个故障。Umi + 4 接着 Umi 3 继续做依赖预打包的事，并且更彻底，不仅是 node 侧的依赖，部分运行时的依赖也会做锁定，比如 + core-js 和 @babel/runtime。 +
+ + + ++ Umi Max。Umi Max + 是内部 Bigfish + 框架的对外版本，解我们自己的问题，同时也给社区另一个集中化框架的选择。 +
+ ++ + Low Import 研发模式。 + + 这是 Umi 4 的试验性功能之一，目前已开发完成，解的问题是让开发者少些或不写 import + 语句。项目中大量的 import 其实都可以通过工程化的方式自动处理。Umi 4 里通过 lowImport:{' '} + {} 开启，然后就可以无 import 直接用路由相关的 Link、useLocation 等，数据流相关的 + connect、useModel，antd 组件 Button、Calendar 等，以及其他更多。 +
+ + + ++ 强约束功能集成。Umi + 4 提供 API 让强约束和代码校验变得非常容易。API 包括 + api.onCheck、api.onCheckConfig、api.onCheckPkgJSON 和 + api.onCheckCode，顾名思义，非常好理解他们分别是干嘛的，可以分别对依赖类、代码类和配置类的内容做校验和卡点，适用于团队。 +
+ ++ + Import All From Umi 迭代。 + + 这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。这种方式有好有坏。好处是通过 + umi 将大量依赖管理起来，用户无需手动安装。坏处是更黑盒，同时有点 Hack。Umi 4 不能解其黑盒问题，但解了 + Hack 问题，让实现无副作用，可以和 Vite、MFSU 等方案无缝结合。 +
+ ++ + srcTranspiler 和 depTranspiler。 + + 提供针对源码编译和依赖编译更多选择。源码编译可选 babel、swc 和 esbuild，目前没有银弹，合适场景做合适的选择。比如 + swc 由于不支持 top level await，和 mfsu 会有些冲突，但他适用于 build，因为有补丁可以兼容到 + es7；比如 esbuild 适用于 dev，因为快。数据方面以 ant-design-pro 项目为例，源码编译用 + esbuild 相比 babel 在 M1 2020 无缓存情况下会快 3s。 +
+ ++ + jsMinifier 和 cssMinifier。 + + js 压缩和 css 压缩 Umi 4 默认都用的 esbuild，因为快。同时也提供更多选择，js 压缩还支持 + swc、terser 和 uglifyJs，css 压缩还支持 cssnano。 +
+ ++ 应用元数据。Umi 4 + 有通过 api.appData + 收集各种项目数据，从配置、路由、package.json、tsconfig.json、npmClient + 到数据流、国际化、antd 用了哪个版本、react 和 react-dom + 的版本等，应有尽有，这对于插件开发者会非常实用，也适用于有统计需求的场景。 +
+ ++ 微生成器。没错，就是 + modern.js 的微生成器，这功能从 modern.js + 里学习了不少，名字就不改了。举个例子，比如 prettier + 功能，可能不是每个项目都需要，就比较适用于微生成器，按需启用、添加配置、安装依赖。 +
+ ++ 贴心小改进。 + 还有不少贴心小改进，举两个例子。1 是项目中新增 plugin.ts，会默认作为插件添加，方便项目进行一些插件级的扩展；2 + 是调试问题时通常需要修改编译后的代码看看有没有改对，你把 umi.js 下下来存到项目根目录，umi + 会优先使用这份代码。 +
+ +以上是 Umi 4 目前的新功能。 + +除此之外，还有一些计划在正式版发布之前做的事情。包括 api route、umi server and adapter、route loader、稳定的 lint、更多命令、组件研发 father 4、文档工具 dumi 2 等，会在之后的 RC 版本中与大家见面。 + +欢迎大家尝鲜 Umi 4，官方文档有准备 ant-design-pro 从 Umi 3 到 4 的升级文档。同时 RC 阶段，还准备了一个手把手升级的微信交流群，欢迎 Umi 4 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。 + +
+ 
+
+ { location.pathname }
+ { location.search }
+ { location.hash }
+
+ );
+}
+```
+
+如果在 React 组件和 Hooks 之外获取当前路由信息。
+
+```ts
+// location 对象，包含 pathname、search 和 hash
+window.location.pathname;
+window.location.search;
+window.location.hash;
+```
+
+命令式路由跳转。
+
+```ts
+import { history } from 'umi';
+
+// 跳转到指定路由
+history.push('/list');
+
+// 带参数跳转到指定路由
+history.push('/list?a=b&c=d#anchor', state);
+history.push({
+ pathname: '/list',
+ search: '?a=b&c=d',
+ hash: 'anchor',
+ },
+ {
+ some: 'state-data',
+ }
+);
+
+// 跳转当前路径，并刷新 state
+history.push({}, state)
+
+// 跳转到上一个路由
+history.back();
+history.go(-1);
+```
+
+:::info{title=🚨}
+注意：history.push 和 history.replace 需要使用 `state` 需将 `state` 作为这两个 API 的第二个参数传递
+:::
+
+
+路由监听。
+
+```ts
+import { history } from 'umi';
+
+const unlisten = history.listen(({ location, action }) => {
+ console.log(location.pathname);
+});
+unlisten();
+```
+
+### Link
+
+`` 是 React 组件，是带路由跳转功能的 `` 元素。
+
+类型定义如下：
+
+```ts
+declare function Link(props: {
+ prefetch?: boolean;
+ to: string | Partial<{ pathname: string; search: string; hash: string }>;
+ replace?: boolean;
+ state?: any;
+ reloadDocument?: boolean;
+}): React.ReactElement;
+```
+
+示例：
+
+```tsx
+import { Link } from 'umi';
+
+function IndexPage({ user }) {
+ return {user.name};
+}
+```
+
+`` 支持相对路径跳转；`` 不做路由跳转，等同于 `` 的跳转行为。
+
+若开启了 `prefetch` 则当用户将鼠标放到该组件上方时，Umi 就会自动开始进行跳转路由的组件 js 文件和数据预加载。
+
+### matchPath
+
+`matchPath` 可以将给定的路径以及一个已知的路由格式进行匹配，并且返回匹配结果。
+
+类型定义如下：
+
+```ts
+declare function matchPath-
+
isActive ? { color: 'red' } : undefined}>Messages
+ isActive ? 'active' : undefined}>Tasks
+ {({ isActive }) => Blog}
+
+
+ );
+}
+
+function DashboardWithContext() {
+ return (
+ Dashboard
+
+
+ );
+}
+```
+
+`Outlet` 组件的 `context` 可以使用 API `useOutletContext` 在子组件中获取。
+
+### resolvePath
+
+用于在客户端解析前端路由跳转路径。
+
+类型定义如下：
+
+```ts
+declare function resolvePath(
+ to: PartialDashboard
+
+ {outlet}
+
+}
+```
+
+### useOutletContext
+
+`useOutletContext` 用于返回 `Outlet` 组件上挂载的 `context` 。
+
+类型定义如下：
+```ts
+declare function useOutletContext
+
+}
+
+const SomeRouteComponentUnderLayout = () => {
+ const layoutContext = useOutletContext();
+
+ return JSON.stringify(layoutContext) // {"prop":"from Layout"}
+}
+```
+
+### useParams
+
+`useParams` 钩子函数返回动态路由的匹配参数键值对对象；子路由中会集成父路由的动态参数。
+
+类型定义如下：
+```ts
+declare function useParams<
+ K extends string = string
+>(): Readonly1 :
+ }
+
+ if (lastRoute?.extraProp) {
+ return 2 :
+ }
+
+ return
+ Hello World {this.props.location.pathname}
+
+ );
+ }
+}
+
+export default withRouter(HelloWorld);
+```
diff --git a/docs/docs/docs/api/commands.en-US.md b/docs/docs/docs/api/commands.en-US.md
new file mode 100644
index 000000000000..dbfb2d85406c
--- /dev/null
+++ b/docs/docs/docs/api/commands.en-US.md
@@ -0,0 +1,308 @@
+---
+order: 4
+toc: content
+---
+# 命令行
+
+umi 提供了很多内置的命令行用于启动，构建项目，另外还有一些辅助开发的命令，如生成器等。
+
+要获取可用的命令列表，你可以在项目目录中运行 help 命令：
+
+```bash
+umi help
+```
+
+你应该能看到类似如下的日志：
+
+```bash
+Usage: umi params: {JSON.stringify(this.props.match.params)}
+ +{data}
;
+}
+
+export async function clientLoader() {
+ const data = await fetch('/api/data');
+ return data;
+}
+```
+
+## codeSplitting
+
+- 类型：`{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }`
+- 默认值：`null`
+
+提供 code splitting 的策略方案。
+
+bigVendors 是大 vendors 方案，会将 async chunk 里的 node_modules 下的文件打包到一起，可以避免重复。同时缺点是，1）单文件的尺寸过大，2）毫无缓存效率可言。
+
+depPerChunk 和 bigVendors 类似，不同的是把依赖按 package name + version 进行拆分，算是解了 bigVendors 的尺寸和缓存效率问题。但同时带来的潜在问题是，可能导致请求较多。我的理解是，对于非大型项目来说其实还好，因为，1）单个页面的请求不会包含非常多的依赖，2）基于 HTTP/2，几十个请求不算问题。但是，对于大型项目或巨型项目来说，需要考虑更合适的方案。
+
+granularChunks 在 bigVendors 和 depPerChunk 之间取了中间值，同时又能在缓存效率上有更好的利用。无特殊场景，建议用 granularChunks 策略。
+
+## conventionLayout
+
+- 类型：`boolean`
+- 默认值：`undefined`
+
+`src/layouts/index.[tsx|vue|jsx|js]` 为约定式布局，默认开启。可通过配置 `conventionLayout: false` 关闭该默认行为。
+
+## conventionRoutes
+
+- 类型：`{ base: string; exclude: RegExp[] }`
+- 默认值：`null`
+
+修改默认的约定式路由规则，仅在使用 umi 约定式路由时有效，约定式路由也叫文件路由，就是不需要手写配置，文件系统即路由，通过目录和文件及其命名分析出路由配置。
+
+使用约定式路由时，约定 `src/pages` 下所有的 `(j|t)sx?` 文件即路由。
+
+> 你可以从[约定式路由](../guides/routes#约定式路由)查看更多说明。
+
+### base
+
+`base` 用于设置约定的路由的基础路径，默认从 `src/pages` 读取，如果是文档站点可能会需要将其改成 `./docs`；
+
+### exclude
+
+你可以使用 `exclude` 配置过滤一些不需要的文件，比如用于过滤 components、models 等。
+
+示例，
+
+```js
+// 不识别 components 和 models 目录下的文件为路由
+conventionRoutes: {
+ exclude: [/\/components\//, /\/models\//],
+}
+```
+
+## copy
+
+- 类型：`Array{data}
;
+}
+
+export async function clientLoader() {
+ const data = await fetch('/api/data');
+ return data;
+}
+```
+
+如上代码，在 `clientLoader` 函数返回的数据，可以在组件内调用 `useClientLoaderData` 获取。
+
+## 优化效果
+
+考虑一个三层嵌套路由的场景：
+
+1. 我们需要先等第一层路由的组件加载完成，然后第一层路由的组件发起数据请求
+2. 第一层路由的数据请求完成后，开始请求第二层路由的组件，第二层路由的组件加载好以后请求第二层路由需要的数据
+3. 第二层路由的数据请求完成后，开始请求第三层路由的组件，第三层路由的组件加载好以后请求第三层路由需要的数据
+4. 第三层路由的数据请求完成后，整个页面才完成渲染
+
+这样的瀑布流请求会严重影响用户的体验，如下图所示：
+
+
+
+如果将组件请求数据的程序提取到 `clientLoader` 中，则 Umi 可以并行地请求这些数据：
+
+
diff --git a/docs/docs/docs/guides/debug.en-US.md b/docs/docs/docs/guides/debug.en-US.md
new file mode 100644
index 000000000000..653a0052d394
--- /dev/null
+++ b/docs/docs/docs/guides/debug.en-US.md
@@ -0,0 +1,77 @@
+---
+order: 14
+toc: content
+---
+
+# 调试
+
+除了使用浏览器的调试工具来完成开发中的调试外，Umi 还推荐以下调试方式来协助项目的调试。
+
+## 调试 dev 产物
+
+如果你需要在 dev 阶段调试项目的构建产物，以 `umi.js` 举例。先将原来的 `umi.js` 下载到当前项目根目录下。根据调试需要进行编辑后，刷新浏览器，项目使用的 `umi.js` 就替换成了根目录下的 `umi.js` 文件。如果调试完毕需要恢复，直接删除根目录的 `umi.js` 即可。
+
+举例：
+```bash
+# 下载当前项目的 umi.js
+$curl http://127.0.0.1:8000/umi.js -O
+
+# 增加想调试的内容，举例增加 "debug!!!" 弹窗
+$ echo -e '\n;alert("debug!!!");\n' >> umi.js
+# 打开浏览器就能看到 alert 弹窗
+
+# 退出调试，恢复到正常状态
+$rm umi.js
+```
+
+以此类推即可调试其他的 JavaScript 文件。
+
+## XSwitch
+
+如果需要在特定的域名环境调试或者验证当前的修改的代码，推荐使用 Chrome 插件 [XSwitch](https://chrome.google.com/webstore/detail/xswitch/idkjhjggpffolpidfkikidcokdkdaogg)。
+
+
+
+
+
+假设我们想在线上项目地址 `https://www.myproject.com` 上调试本地代码。项目使用 `https://www.myproject.com/umi.hash.js`，为了验证本地的项目，需要将它替换成本地开发环境的 `http://127.0.0.1:000/umi.js`
+
+首先使用环境变量 `SOCKET_SERVER` 启动本地环境（防止因为连接不上 socket server 导致页面不断刷新）。
+```bash
+$SOCKET_SERVER=http://127.0.0.1:8000/ npx umi dev
+```
+
+然后，在 XSwitch 中配置资源转发规则。
+```json
+{
+ "proxy": [
+ // 数组的第 0 项的资源会被第 1 项目替换
+ [
+ "https://www.myproject.com/umi.2c8a01df.js",
+ "http://127.0.0.1:8000/umi.js"
+ ],
+ // 使用正则可以方便处理分包情况下 js 资源的加载
+ [
+ "https://www.myproject.com/(.*\.js)",
+ "http://127.0.0.1:8000/$1",
+ ],
+ // 如果需要验证视觉表现，不要忘记替换 css 资源
+ [
+ "https://www.myproject.com/umi.ae8b10e0.css",
+ "http://127.0.0.1:8000/umi.css"
+ ]
+ ]
+}
+```
+
+刷新页面，正式域名下的内容就被替换了，这个时候就能方便的指定环境下调试了。
+
+如果要退出调试，关闭 XSwitch 插件功能即可。
+
+
+
+:::success{title=💡}
+经常使用 XSwitch 的话，可新建一个规则保存。
+:::
+
+
diff --git a/docs/docs/docs/guides/directory-structure.en-US.md b/docs/docs/docs/guides/directory-structure.en-US.md
new file mode 100644
index 000000000000..6f6d68fc9df1
--- /dev/null
+++ b/docs/docs/docs/guides/directory-structure.en-US.md
@@ -0,0 +1,305 @@
+---
+order: 2
+toc: content
+---
+# 目录结构
+
+这里罗列了 Umi 项目中约定（或推荐）的目录结构，在项目开发中，请遵照这个目录结构组织代码。
+
+```bash
+.
+├── config
+│ └── config.ts
+├── dist
+├── mock
+│ └── app.ts｜tsx
+├── src
+│ ├── .umi
+│ ├── .umi-production
+│ ├── layouts
+│ │ ├── BasicLayout.tsx
+│ │ ├── index.less
+│ ├── models
+│ │ ├── global.ts
+│ │ └── index.ts
+│ ├── pages
+│ │ ├── index.less
+│ │ └── index.tsx
+│ ├── utils // 推荐目录
+│ │ └── index.ts
+│ ├── services // 推荐目录
+│ │ └── api.ts
+│ ├── app.(ts|tsx)
+│ ├── global.ts
+│ ├── global.(css|less|sass|scss)
+│ ├── overrides.(css|less|sass|scss)
+│ ├── favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)
+│ └── loading.(tsx|jsx)
+├── node_modules
+│ └── .cache
+│ ├── bundler-webpack
+│ ├── mfsu
+│ └── mfsu-deps
+├── .env
+├── plugin.ts
+├── .umirc.ts // 与 config/config 文件 2 选一
+├── package.json
+├── tsconfig.json
+└── typings.d.ts
+```
+## 根目录
+
+### package.json
+
+与 Umi 3 不同，Umi 4 不会自动注册 `package.json` 中以 `@umijs/preset-`、`@umijs/plugin-`、`umi-preset-` 和 `umi-plugin-` 开头的插件、预设，若你需要自定义额外的插件、预设，需要手动配置到 [`plugins`](../api/config#plugins) 。
+
+### .env
+
+环境变量，比如：
+
+```text
+PORT=8888
+COMPRESS=none
+```
+
+### .umirc.ts
+
+> 与 `config/config.ts` 文件功能相同，2 选 1 。`.umirc.ts` 文件优先级较高
+
+配置文件，包含 Umi 所有[非运行时配置](../api/config)（运行时配置一般定义于 [`app.ts`](#apptstsx)）。
+
+若你需要在不同环境中加载不同配置，这在 Umi 中是根据 [`UMI_ENV`](./env-variables#umi_env) 来实现的，一个不同环境启动的例子：
+
+```ts
+// package.json
+{
+ "scripts": {
+ "dev": "umi dev",
+ "dev:pre": "cross-env UMI_ENV=pre umi dev"
+ }
+}
+```
+
+### config/config.ts
+
+> 与 `.umirc.ts` 文件功能相同，2 选 1 。`.umirc.ts` 文件优先级较高
+
+与 [`.umirc.ts`](#umircts) 相同，区别是你可以单独在一个 `config` 文件夹下集中管理所有的配置，保持项目根目录整洁。
+
+### dist 目录
+
+执行 `umi build` 后产物的默认输出文件夹。可通过 [`outputPath`](../api/config#outputpath) 配置修改产物输出文件夹。
+
+### mock 目录
+
+存放 mock 文件，此目录下所有 `.ts` / `.js` 文件会被 mock 服务加载，从而提供模拟数据，使用方法详见 [Mock](./mock) 。
+
+### public 目录
+
+存放固定的静态资源，如存放 `public/image.png` ，则开发时可以通过 `/image.png` 访问到，构建后会被拷贝到输出文件夹。
+
+注：
+
+1. 对于 svg 资源，Umi 支持 [svgr](../api/config#svgr) ，可以直接导入作为组件使用：
+
+ ```ts
+ import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';
+ // 
>
+ ```
+
+### `src` 目录
+
+#### .umi 目录
+
+:::warning{title=🛎️}
+**不要提交 `.umi` 临时文件到 git 仓库，默认已在 `.gitignore` 被忽略。**
+:::
+
+dev 时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。
+
+#### .umi-production 目录
+
+:::warning{title=🛎️}
+**不要提交 `.umi-production` 临时文件到 git 仓库，默认已在 `.gitignore` 被忽略。**
+:::
+
+build 时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。
+
+#### app.[ts｜tsx]
+
+[运行时配置](../api/runtime-config) 文件，可以在这里扩展运行时的能力，比如修改路由、修改 render 方法等。
+
+运行时配置带来的逻辑会在浏览器中运行，因此当有远程配置、动态内容时，这些我们在本地开发时还不确定，不能写死，所以需要在浏览器实际运行项目时动态获取他们。
+
+#### layouts/index.tsx
+
+全局布局，默认会在所有路由下生效，比如有以下路由关系：
+
+```
+[
+ { path: '/', component: '@/pages/index' },
+ { path: '/users', component: '@/pages/users' },
+]
+```
+
+输出为：
+
+```jsx
+Hello
+}
+```
+
+默认启用 React 18，如果需要 React 17 的渲染方式，请在项目中安装 React 17 的依赖，框架会自动适配 React 版本。
+
+```bash
+$ pnpm i react@17 react-dom@17
+```
+
+## 模板
+
+默认模板如下：
+
+```html
+
+
+
+
+
+ )
+}
+```
+
+这样，访问 `/list` 和 `/admin` 就会带上 `src/layouts/index` 这个 layout 组件。
+
+### redirect
+
+* Type: `string`
+
+配置路由跳转。
+
+比如：
+
+```js
+export default {
+ routes: [
+ { path: '/', redirect: '/list' },
+ { path: '/list', component: 'list' },
+ ],
+}
+```
+
+访问 `/` 会跳转到 `/list`，并由 `src/pages/list` 文件进行渲染。
+
+### wrappers
+
+* Type: `string[]`
+
+配置路由组件的包装组件，通过包装组件可以为当前的路由组件组合进更多的功能。
+比如，可以用于路由级别的权限校验：
+
+```js
+export default {
+ routes: [
+ { path: '/user', component: 'user',
+ wrappers: [
+ '@/wrappers/auth',
+ ],
+ },
+ { path: '/login', component: 'login' },
+ ]
+}
+```
+
+然后在 `src/wrappers/auth` 中，
+
+```jsx
+import { Navigate, Outlet } from 'umi'
+
+export default (props) => {
+ const { isLogin } = useAuth();
+ if (isLogin) {
+ return
+ Users Page
+
+ )
+}
+```
+
+然后点击 `Users Page` 就会跳转到 `/users` 地址。
+
+注意：
+
+* `Link` 只用于单页应用的内部跳转，如果是外部地址跳转请使用 `a` 标签
+
+## 路由组件参数
+
+Umi 4 使用 [react-router@6](https://reactrouter.com/docs/en/v6/api) 作为路由组件，路由参数的获取使其 hooks。
+
+### match 信息
+
+[useMatch](https://reactrouter.com/docs/en/v6/api#usematch)
+
+```jsx
+const match = useMatch('/comp/:id')
+// match
+{
+ "params": {
+ "id": "paramId"
+ },
+ "pathname": "/comp/paramId/",
+ "pathnameBase": "/comp/paramId",
+ "pattern": {
+ "path": "/comp/:id",
+ "caseSensitive": false,
+ "end": true
+ }
+}
+```
+
+### location 信息
+
+[useLocation](https://reactrouter.com/docs/en/v6/api#uselocation)
+
+```jsx
+const location = useLocation();
+// location
+{
+ "pathname": "/path/",
+ "search": "",
+ "hash": "",
+ "state": null,
+ "key": "default"
+}
+```
+
+:::warning{title=🚨}
+推荐使用 `useLocation`, 而不是直接访问 `history.location`. 两者的区别是 `pathname` 的部分。
+`history.location.pathname` 是完整的浏览器的路径名；而 `useLocation` 中返回的 `pathname` 是相对项目配置的`base`的路径。
+
+举例：项目如果配置 `base: '/testbase'`,
+
+当前浏览器地址为 `https://localhost:8000/testbase/page/apple`
+
+`history.location.pathname` 为 `/testbase/page/apple`
+
+`useLocation().pathname` 为 `/page/apple`
+:::
+
+### 路由动态参数
+
+[useParams](https://reactrouter.com/docs/en/v6/api#useparams)
+
+```jsx
+// 路由配置 /comp/:id
+// 当前 location /comp/paramId
+
+const params = useParams();
+// params
+{
+ "id": "paramId"
+}
+```
+
+### query 信息
+
+[useSearchParams](https://reactrouter.com/docs/en/v6/api#usesearchparams)
+
+```jsx
+// 当前 location /comp?a=b;
+const [searchParams, setSearchParams] = useSearchParams();
+searchParams.get('a') // b
+searchParams.toString() // a=b
+
+setSearchParams({a:'c',d:'e'}) // location 变成 /comp?a=c&d=e
+```
+
+`searchParams`的 api [参考](https://developer.mozilla.org/zh-CN/docs/Web/API/URL/searchParams)
+
diff --git a/docs/docs/docs/guides/styling.en-US.md b/docs/docs/docs/guides/styling.en-US.md
new file mode 100644
index 000000000000..2e9608b14872
--- /dev/null
+++ b/docs/docs/docs/guides/styling.en-US.md
@@ -0,0 +1,154 @@
+---
+order: 7
+toc: content
+---
+
+# 样式
+
+本文介绍在 Umi 项目中使用样式的各种方式。
+
+## 使用 CSS 样式
+
+你可以在 Umi 项目中使用 `.css` 文件声明各种样式，然后在 `.js` 文件中引入即可生效。
+
+例如，在 `src/pages/index.css` 文件按照以下代码声明 `.title` 类的样式为红色：
+
+```css
+.title {
+ color: red;
+}
+```
+
+然后在 `src/pages/index.tsx` 文件中引入即可生效。
+
+```jsx
+// src/pages/index.tsx
+
+import './index.css';
+
+export default function () {
+ return Hello World
;
+}
+```
+
+按照此种引入方式的样式会在整个 Umi 项目中生效，即无论你从哪个 `.js`
+文件引入，他声明的样式可以在任何页面和组件中使用。如果你想要避免这种情况，可以使用 [CSS Modules](#使用-css-modules) 的功能来限制样式的作用域。
+
+## 使用 CSS Modules
+
+在 `js` 文件中引入样式时，如果赋予他一个变量名，就可以将样式以 CSS Module 的形式引入。
+
+```jsx
+// src/pages/index.tsx
+
+import styles from './index.css';
+
+export default function () {
+ return
+ Hello World
+
;
+}
+```
+
+上面的示例中，`index.css` 文件中声明的样式不会对全局样式造成影响，只会对从 `styles` 变量中使用的样式生效。
+
+## 使用 CSS 预处理器
+
+Umi 默认支持 LESS (推荐)，SASS 和 SCSS 样式的导入，你可以直接按照引入 CSS 文件的方式引入并使用这些由 CSS 预处理器处理的样式。
+
+:::info{title=💡}
+在 Umi 中使用 SASS (SCSS) 需要额外安装预处理依赖 如: `npm add -D sass`
+:::
+
+```jsx
+// src/pages/index.tsx
+
+import './index.less';
+import './index.sass';
+import './index.scss';
+
+export default function () {
+ return Hello World
;
+}
+```
+
+同样也支持 CSS Module 的用法：
+
+```jsx
+// src/pages/index.tsx
+
+import lessStyles from './index.less';
+import sassStyles from './index.sass';
+import scssStyles from './index.scss';
+
+export default function () {
+ return
+ Hello World
+
;
+}
+```
+
+Umi 也同时提供了对 `.styl` 和 `.stylus` 文件的内置支持。使用前必须安装 `stylus` 相应的预处理器依赖，其他用法用上面的例子
+
+```bash
+# .styl and .stylus
+npm add -D stylus
+```
+
+## 进阶设置
+
+如果你需要使用除了常见的 LESS, SASS 或 SCSS 以外的其他样式预处理器，你可以透过 Umi
+插件提供的 [chainWebpack 接口](../api/config#chainwebpack)来加入自己需要的 Loader。
+
+## 使用 Tailwindcss
+
+Umi 提供了内置的 [Tailwindcss](https://tailwindcss.com/)
+插件，并且可以直接方便地使用 [微生成器](./generator#tailwind-css-配置生成器) 来启用。
+
+## 使用 UnoCSS
+
+与 Tailwindcss 相同，Umi 也提供了内置的 [UnoCSS](https://github.com/unocss/unocss) 插件，可以按照相同方式开启。
+
+1. 安装 `plugin-unocss`
+2. 安装 `unocss` 及 `@unocss/cli`
+
+```bash
+pnpm i unocss @unocss/cli
+```
+
+3. 在 Umi 设置中启用插件，并声明会用到 `unocss` 的文件目录
+
+```js
+// .umirc.ts
+
+export default {
+ plugins: [
+ require.resolve('@umijs/plugins/dist/unocss')
+ ],
+ unocss: {
+ // 检测 className 的文件范围，若项目不包含 src 目录，可使用 `pages/**/*.tsx`
+ watch: ['src/**/*.tsx']
+ },
+};
+```
+
+4. 在项目目录下加入 `unocss.config.ts`
+ 配置文件，并加入项目需要的 [UnoCSS Presets](https://github.com/unocss/unocss#presets)
+
+```js
+// unocss.config.ts
+
+import {defineConfig, presetAttributify, presetUno} from 'unocss';
+
+export function createConfig({strict = true, dev = true} = {}) {
+ return defineConfig({
+ envMode: dev ? 'dev' : 'build', presets: [presetAttributify({strict}), presetUno()],
+ });
+}
+
+export default createConfig();
+```
+
+5. 启动项目进行开发，插件会监听设置文件中的 `unocss.watch` 字段，动态生成样式文件并自动套用
diff --git a/docs/docs/docs/guides/test.en-US.md b/docs/docs/docs/guides/test.en-US.md
new file mode 100644
index 000000000000..52a622dfd39a
--- /dev/null
+++ b/docs/docs/docs/guides/test.en-US.md
@@ -0,0 +1,202 @@
+---
+order: 15
+toc: content
+---
+# 测试
+
+自动化测试是保障质量的有效手段，Umi 4 提供单元测试的脚手架。Umi 4 推荐使用 [Jest](https://jestjs.io/) 和 [@testing-library/react](https://github.com/testing-library/react-testing-library) 来完成项目中的单元测试。
+
+## 配置
+
+使用 Umi 4 的微生成器快速地配置好 Jest [参考](./generator#jest-配置生成器)，如果你需要修改 jest 相关的配置，可以在 `jest.config.ts` 修改。
+
+
+umi 项目
+
+```ts
+import { Config, configUmiAlias, createConfig } from 'umi/test';
+
+export default async () => {
+ return (await configUmiAlias({
+ ...createConfig({
+ target: 'browser',
+ jsTransformer: 'esbuild',
+ jsTransformerOpts: { jsx: 'automatic' },
+ }),
+ // 覆盖 umi 的默认 jest 配置, 如
+ // displayName: "Umi jest",
+ })) as Config.InitialOptions;
+};
+```
+
+@umijs/max 项目
+
+```ts
+import { Config, configUmiAlias, createConfig } from '@umijs/max/test';
+
+export default async () => {
+ return (await configUmiAlias({
+ ...createConfig({
+ target: 'browser',
+ jsTransformer: 'esbuild',
+ jsTransformerOpts: { jsx: 'automatic' },
+ }),
+ // 覆盖 umi 的默认 jest 配置, 如
+ // displayName: "Umi jest",
+ })) as Config.InitialOptions;
+};
+```
+
+配置完后，就可以开始编写单元测试了。
+
+## 与 UI 无关的测试
+
+假设我们需要测试一个 utils 函数 `reverseApiData`, 它将 api 请求的结果 `data` 对象的 key 和 value 互换。
+
+我们推荐将测试文件和被测模块放在同一级目录，这样可以方便查看测试文件以便理解模块的功能。
+
+```txt
+.
+└── utils
+ ├── reverseApiData.test.tss
+ └── reverseApiData.ts
+```
+
+```ts
+// utils/reverseApiData.ts
+export async function reverseApiData(url: string, fetcher = fetch) {
+ const res = await fetcher(url);
+ const json = await res.json();
+
+ const { data = {} } = json;
+ const reversed: RecordI am blue
+I am red
++使用 Max 并不代表需要使用全部 Max 的功能，可以根据需求关闭插件，所以当你需要使用 Max 的功能时，可以总是选择创建 Max 项目。 +::: + +## 项目级插件 + +若你想在项目中快速使用插件的功能（如 [修改产物的 html](../introduce/faq#documentejs-去哪了如何自定义-html-模板) ），可以在项目的根目录创建 `plugin.ts` 编写一个项目级插件，该文件将被自动作为插件加载。 + +有关更详细的目录结构说明请参阅 [目录结构](./directory-structure) 章节。 + +## 开发插件 + +请参阅 [开发插件](./plugins) 章节。 + + + + diff --git a/docs/docs/docs/guides/use-vue.en-US.md b/docs/docs/docs/guides/use-vue.en-US.md new file mode 100644 index 000000000000..2a08f363bb0f --- /dev/null +++ b/docs/docs/docs/guides/use-vue.en-US.md @@ -0,0 +1,221 @@ +--- +order: 17 +toc: content +--- + +# 使用 Vue + +本文介绍如何在 Umi 中使用 Vue , Umi Vue 大部分配置和 React 相同，这里只列出一些 Vue 独有的配置。 + +## 启动方式 + +### 安装 + +```bash +pnpm add @umijs/preset-vue -D +``` + +### 配置预设 + +```ts +// .umirc.ts or config/config.ts 中 +export default { + presets: [require.resolve('@umijs/preset-vue')], +}; + +``` + +## 路由 + +### 配置式路由 + +:::info +这里仅列出和 React 路由配置差异部分。 +::: + +#### name + +命名路由 + +除了 `path` 之外，你还可以为任何路由提供 `name` ： + +```ts +export default { + routes: [ + { + path: '/user/:username', + name: 'user', + component: 'index' + } + ] +} +``` + +要链接到一个命名的路由，可以向 `router-link` 组件的 `to` 属性传递一个对象： + +```html +
+
+如果你不知道可以贡献什么，可以到源码里搜 TODO 或 FIXME 找找。
diff --git a/docs/docs/docs/introduce/faq.en-US.md b/docs/docs/docs/introduce/faq.en-US.md
new file mode 100644
index 000000000000..3e417a31e3e1
--- /dev/null
+++ b/docs/docs/docs/introduce/faq.en-US.md
@@ -0,0 +1,206 @@
+---
+order: 5
+toc: content
+---
+# FAQ
+
+## 可以关闭 dynamicImport 吗？
+
+可以，但不建议关闭。
+
+1、安装依赖
+
+```bash
+ pnpm i babel-plugin-dynamic-import-node -D
+```
+
+2、配置里加上 `extraBabelPlugins` ，但只针对 production 开启
+
+```ts
+// .umirc.ts
+export default {
+ extraBabelPlugins: process.env.NODE_ENV === 'production'
+ ? ['babel-plugin-dynamic-import-node']
+ : []
+}
+```
+
+## 没有 dynamicImport 怎么配置它的 loading ？
+
+定义 `src/loading.tsx` :
+
+参考 [目录结构 > loading.tsx](../guides/directory-structure#loadingtsxjsx)
+
+## 可以用 react 17 吗？
+
+由于 umi v4 升级了默认的 react 版本到 v18，使用 umi4 时注意下依赖库和 react 18 的兼容情况，如果还需要使用 react 17，请执行以下命令并重启。
+
+```bash
+ pnpm add react@^17 react-dom@^17
+```
+
+## 代理静态资源到本地后，一直 restart 刷新页面
+
+
+
+解法：配置 `SOCKET_SERVER=127.0.0.1:${port}` 启动项目
+
+```bash
+ SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
+```
+
+## Error evaluating function `round`: argument must be a number
+
+
+
+解法：新版 less 中 `/` 默认被识别为属性简写，通过配置 `lessLoader: { math: 'always' }` 恢复旧版行为（默认将 `/` 用作计算符号）。
+
+## routes 里的 layout 配置选项不生效
+
+layout 配置被移动到了 `app.ts` ，详见 [runtime-config > layout](https://umijs.org/docs/api/runtime-config#layout)
+
+
+## document.ejs 去哪了，如何自定义 HTML 模板
+
+除了可以通过 配置项 注入外部 [script](https://umijs.org/docs/api/config#scripts) 、[css](https://umijs.org/docs/api/config#styles) 外，还可以使用项目级插件更灵活的修改 HTML 产物，参见：[issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
+
+## scripts 里配置的外部 js 文件为什么默认插入到 umi.js 的后面
+
+react 只有在页面加载完毕后才会开始运行，所以插到 `umi.js` 后面不会影响项目。
+
+若需要插到 `umi.js` 前面，可参见 [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
+
+## umi4 我怎么分包
+
+Umi 4 默认按页拆包，如果你觉得还需要优化，可以使用分包策略或手动拆包，详见：[代码拆分指南](../../blog/code-splitting)
+
+如果你有将所有 js 产物打包成单 `umi.js` 文件的需求，请关闭 [dynamicImport](#可以关闭-dynamicimport-吗) 。
+
+## _layout.tsx 去哪了，我怎么嵌套路由
+
+Umi 4 使用 react-router v6 ，通过 `+
+
+## Umi 是什么？
+
+Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架。Umi 以路由为基础，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
+
+Umi 是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用，包括 Java、Node、H5 无线、离线（Hybrid）应用、纯前端 assets 应用、CMS 应用、Electron 应用、Serverless 应用等。他已经很好地服务了我们的内部用户，同时也服务了不少外部用户，包括淘系、飞猪、阿里云、字节、腾讯、口碑、美团等。在 2021 年字节的[调研报告](https://zhuanlan.zhihu.com/p/403206195)中，Umi 是其中 25.33% 开发者的选择。
+
+Umi 有很多非常有意思的特性，比如。
+
+1、**企业级**，在安全性、稳定性、最佳实践、约束能力方面会考虑更多+2、**插件化**，啥都能改，Umi 本身也是由插件构成
+3、**MFSU**，比 Vite 还快的 Webpack 打包方案
+4、基于 React Router 6 的完备路由
+5、默认最快的请求
+6、SSR & SSG
+7、稳定白盒性能好的 ESLint 和 Jest
+8、React 18 的框架级接入
+9、Monorepo 最佳实践
+... + + +## 什么时候不用 Umi？ + +如果你的项目， + +1、需要支持 IE 8 或更低版本的浏览器
+2、需要支持 React 16.8.0 以下的 React
+3、需要跑在 Node 14 以下的环境中
+4、有很强的 webpack 自定义需求和主观意愿
+5、需要选择不同的路由方案
+... + +Umi 可能不适合你。 + + +## 为什么不是？ + +### create-react-app + +create-react-app 是脚手架，和 Umi、next.js、remix、ice、modern.js 等元框架不是同一类型。脚手架可以让我们快速启动项目，对于单一的项目够用，但对于团队而言却不够。因为使用脚手架像泼出去的水，一旦启动，无法迭代。同时脚手架所能做的封装和抽象都非常有限。 + +### next.js + +如果要做 SSR，next.js 是非常好的选择（当然，Umi 也支持 SSR）；而如果只做 CSR，Umi 会是更好的选择。相比之下，Umi 的扩展性会更好；并且 Umi 做了很多更贴地气的功能，比如配置式路由、补丁方案、antd 的接入、微前端、国际化、权限等；同时 Umi 会更稳定，因为他锁了能锁的全部依赖，定期主动更新。某一个子版本的 Umi，不会因为重装依赖之后而跑不起来。 + +### remix + +Remix 是我非常喜欢的框架，Umi 4 从中
+2、插件和插件集
+3、最佳实践
+4、企业级
+5、import all from umi
+6、编译时框架
+7、依赖预打包
+8、默认快
+9、约束与开放
+ +下面仅介绍 1-5 的 5 点，剩下 6-9 的 4 点在 2022.1.8 的 SEE Conf 中有过详细分享，详见[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)。 + +## 技术收敛 + +
+
++ +技术收敛对团队而言尤其重要，他包含两层含义，1）技术栈收敛 2）依赖收敛。技术栈收敛指社区那么多技术栈，每个技术方向都有非常多选择，比如数据流应该就不下 100 种，开发者应该如何选择；收敛了技术栈之后还需要收敛依赖，团队中，开发者的项目不应该有很多细碎的依赖，每一个依赖都附带着升级成本。 + +我们希望开发者依赖 Umi 之后就无需关心 babel、webpack、postcss、react、react-router 等依赖，而依赖 @umijs/max 之后无需再关心开发中台项目的依赖和技术栈。 + +## 插件和插件集 + +
+
++ +Umi 通过提供插件和插件集的机制来满足不同场景和业务的需求。插件是为了扩展一个功能，而插件集是为了扩展一类业务。比如要支持 vue，我们可以有 `@umijs/preset-vue`，包含 vue 相关的构建和运行时；比如要支持 h5 的应用类型，可以有 `@umijs/preset-h5`，把 h5 相关的功能集合到一起。 + +如果要类比，插件集和 babel 的 preset，以及 eslint 的 config 都类似。 + +## 最佳实践 + +最佳实践是我们认为做某件事当下最好的方式，主语是我们，所以会相对比较主观。比如路由、补丁方案、数据流、请求、权限、国际化、微前端、icons 使用、编辑器使用、图表、表单等方面，Umi 都会给出我们的最佳实践。这些最佳实践大部分来自蚂蚁集团内部的实践和讨论，也有部分来自社区。他们是主观和时间敏感的，所以可能会有相对比较频繁的迭代。 + +之所以需要最佳实践，1）是社区太多方案选择，2）是很多人没有选择的精力和经验甚至意愿。尤其是针对非专业的前端，有选择比没选择好，不管这个选择如何。 + +## 企业级 + +npm 社区「世风日下」，涉政包、恶意包、广告求职包频出，所以如何确保不会「睡一觉醒来项目挂了」是面对企业生成提供服务的框架绕不开的一个点。 + +Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依赖，通过配置锁定 babel 补丁依赖等方式，让 Umi 不会在你重装 node_modules 之后就挂掉，并以此来实现「十年后依旧可用」。 + +## import all from umi + +很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 Umi 中导出。导出的方法不仅来自 Umi 自身，还来自 Umi 插件。 + +这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。 + +```ts +// 大量插件为 umi 提供额外导出内容 +import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi'; +``` + +这带来的好处是。通过 Umi 将大量依赖管理起来，用户无需手动安装；同时开发者在代码中也会少很多 import 语句。 diff --git a/docs/docs/docs/introduce/upgrade-to-umi-4.en-US.md b/docs/docs/docs/introduce/upgrade-to-umi-4.en-US.md new file mode 100644 index 000000000000..77112efa8aed --- /dev/null +++ b/docs/docs/docs/introduce/upgrade-to-umi-4.en-US.md @@ -0,0 +1,303 @@ +--- +order: 4 +toc: content +--- +# 升级到 Umi 4 + +## 升级步骤 + +升级到 Umi 4 只需要简单的几步操作就能完成，简单的描述整个过程就是 - “重装依赖，修改配置”： + +1. **依赖处理** +2. **启动命令** +3. **非官方插件升级** +4. **配置层迁移** +5. **代码层修改** + +### 依赖处理 + +项目的 `package.json` 需要升级 Umi，并替换掉对应的 Umi 插件。 + +如果 `umi@3` 中是使用 `umi` + `@umijs/preset-react` 的组合进行开发的，那可以直接使用新版的 `max` 直接升级。 + +```diff +{ + "devDependencies": { ++ "@umijs/max": "^4.0.0", +- "umi": "^3.0.0", +- "@umijs/preset-react": "^1.2.2" + } +} +``` + +删除 `node_module`，执行下 `npm install` 重装依赖。 + +### 启动命令 + +如果使用了 `@umijs/max` 可以使用 `max` 命令来替换 `umi`，`max dev`，`max build` 等。 + +`umi@4` 将一些项目前置操作放到了 `setup` 命令中，如 umi@3 中的 `umi g tmp` 等命令，需要使用 `umi setup` 替换 + +`package.json` + +```diff +{ + "scripts": { +- "build": "umi build", ++ "build": "max build", +- "postinstall": "umi g tmp", ++ "postinstall": "max setup", +- "start": "umi dev", ++ "start": "max dev", + } +} +``` + +### 非官方插件升级 + +在项目中用到的一些非 Umi 官方提供的 Umi 插件，请联系相关作者及时根据[插件 api 变动](../api/plugin-api)。 + +项目迁移时可先关闭对相应插件包的引用，如临时注释配置中的 `plugins`，移除 package.json 中以 `umi-plugin-`，`@umijs/plugin-` 和 `@umijs/preset-` 开头的所有依赖。 + +### 配置层迁移 + +**max 提供的的配置项**如下 `config/config.ts` ： + +> 需要注意的是，之前的一些插件约定开启的规则，在 `umi@4` 中几乎都要通过显式的配置开启，因为希望在 `umi@4` 中有更少的“黑盒”。 + +```typescript +import { defineConfig, utils } from 'umi'; + +export default defineConfig({ + model: {}, + antd: {}, + request: {}, + initialState: {}, + mock: { + include: ['src/pages/**/_mock.ts'], + }, + dva: {}, + layout: { + // https://umijs.org/docs/max/layout-menu#构建时配置 + title: 'UmiJS', + locale: true, + }, + // https://umijs.org/zh-CN/plugins/plugin-locale + locale: { + // default zh-CN + default: 'zh-CN', + antd: true, + // default true, when it is true, will use `navigator.language` overwrite default + baseNavigator: true, + }, +}); +``` + +**存在差异的配置项**如下 `config/config.ts` ： + +```typescript +import { defineConfig, utils } from 'umi'; + +export default defineConfig({ +- fastRefresh: {}, ++ fastRefresh: true, + dva: { + // 不再支持 hmr 这个参数 +- hmr: true, + }, +// 默认 webpack5 +- webpack5: {}, +}) +``` + +### 代码层修改 + +Umi 4 中将 `react-router@5` 升级到 `react-router@6`，所以路由相关的一些 api 存在着使用上的差异。 + +props 默认为空对象，以下属性都不能直接从 props 中取出  + +#### children + +```typescript +import { Outlet } from 'umi'; +
+- { props.children }
++
+ );
+}
+```
+
+使用了 `React.cloneElement` 方式渲染的路由组件改造，示例
+
+```diff
+import React from 'react';
++ import { Outlet } from 'umi';
+
+export default function RouteComponent(props) {
+ return (
+
+- { React.cloneElement(props.children, { someProp: 'p1' }) }
++
+ );
+}
+```
+
+组件改成从 `useOutletContext` 取值
+
+```diff
+import React from 'react';
++ import { useOutletContext } from 'umi';
+
+- export function Comp(props){
++ export function Comp() {
++ const props = useOutletContext();
+
+ return props.someProp;
+}
+```
+
+#### history
+
+```diff
++ import { history } from 'umi';
+export default function Page(props) {
+ return (
+ {
+- props.history.push('list');
++ history.push('list');
+ }}>
+
+ );
+}
+```
+
+#### location
+
+> 建议组件或 hooks 里用 useLocation 取，其他地方就用 window.location 获取。
+
+```diff
+export default function Page(props) {
++ const { location } = window;
+ return (
+
+- { props.location }
++ { location }
+
+ );
+}
+```
+
+或者
+
+```diff
++ import { useLocation } from 'umi';
+export default function Page(props) {
++ let location = useLocation();
+ return (
+
+- { props.location }
++ { location }
+
+ );
+}
+```
+
+#### match
+
+```diff
++ import { useMatch } from 'umi';
+export default function Page(props) {
++ const match = useMatch({ path: 'list/search/:type' });
+ return (
+
+- { props.match }
++ { match }
+
+ );
+}
+```
+
+在 class component 组件中的使用方式:
+
+```diff
+import { matchPath } from 'umi';
+class Page extends Component {
++ match = matchPath({ path: 'list/search/:type' }, window.location.pathname);
+ state = {}
+ render() {
+ return (
+
+- {this.props.match.type}
++ {this.match.type}
+
+ )
+ }
+}
+```
+更多 `Umi` 相关 [api](https://umijs.org/docs/api/api)
+
+需要注意 match 数据的差异：
+
+```
+// match v5
+isExact: true
+params: {}
+path: "/users/abc"
+url: "/users/abc"
+
+// match v6
+params:{ }
+pathname: "/list/search/articles"
+pathnameBase: "/list/search/articles"
+pattern: {path: 'list/search/:type'}
+```
+
+更多改动和 api 变更，请查阅 [react-router@6](https://reactrouter.com/docs/en/v6/api#uselocation)
+
+完成以上操作后，执行下 `max dev`，访问 [http://localhost:8000](http://localhost:8000)，请验证所有功能都符合预期。
+
+如果你的项目无法正常启动，你可能还需要做如下操作：
+
+## 配置变更
+
+TODO
+
+## FAQ
+
+### location 中的 query 找不到？
+
+location 中的 query 不再支持了，后续推荐用 [search](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+
+```diff
+- const { query } = history.location;
++ import { parse } from 'query-string';
++ const query = parse(history.location.search);
+```
+
+### \*.d 文件找不到，或者它的引用找不到
+
+在 `umi@3` 中通过 `import` 会自动找到同名的 `.d.ts` 文件，如：
+
+`import { ButtonType } from './button';`
+
+如果存在 `.button.d.ts` 文件，在 `umi@3` 中会正确执行，但是在 umi@4 中会发生报错，你可能需要更加规范的引用类型。
+
+```diff
+- import { ButtonType } from './button';
++ import type { ButtonType } from './button.d';
+```
diff --git a/docs/docs/docs/max/access.en-US.md b/docs/docs/docs/max/access.en-US.md
new file mode 100644
index 000000000000..b43602684ab1
--- /dev/null
+++ b/docs/docs/docs/max/access.en-US.md
@@ -0,0 +1,166 @@
+---
+order: 7
+toc: content
+---
+# 权限
+
+## 启用方式
+
+配置开启。同时需要 `src/access.ts` 提供权限配置。
+
+```ts
+export default {
+ access: {},
+ // access 插件依赖 initial State 所以需要同时开启
+ initialState: {},
+};
+```
+
+## 介绍
+
+我们约定了 `src/access.ts` 为我们的权限定义文件，该文件需要默认导出一个方法，导出的方法会在项目初始化时被执行。该方法需要返回一个对象，对象的每一个值就对应定义了一条权限。如下所示：
+
+```js
+// src/access.ts
+export default function (initialState) {
+ const { userId, role } = initialState;
+
+ return {
+ canReadFoo: true,
+ canUpdateFoo: role === 'admin',
+ canDeleteFoo: (foo) => {
+ return foo.ownerId === userId;
+ },
+ };
+}
+```
+
+其中 `initialState` 是通过初始化状态插件 `initial-state` 提供的数据，你可以使用该数据来初始化你的用户权限。
+
+## 配置
+
+### 扩展的路由配置
+
+配合 [layout](./layout-menu) 插件你可以很简单的实现针对某些页面的权限控制。如下所示，只有拥有了 canReadPageA （在 `src/access.ts` 中定义）权限，用户才可以访问该页面。否则会默认渲染 Layout 插件内置的权限错误页面。
+
+```ts
+export const routes = [
+ {
+ path: '/pageA',
+ component: 'PageA',
+ access: 'canReadPageA', // 权限定义返回值的某个 key
+ },
+];
+```
+
+### 自定义权限页面配置
+
+上面说到默认渲染 Layout 插件内置的权限错误页面，如果想配置自定义权限页面需要在 `src/app.tsx` 中定义。
+
+```tsx
+export const layout: RunTimeLayoutConfig = () => {
+ return {
+ // 自定义 403 页面
+ unAccessible: 'unAccessible'
,
+ // 自定义 404 页面
+ noFound: 'noFound'
,
+ };
+};
+```
+
+#### access
+
+- Type: `string`
+
+对应的权限名称。
+
+## API
+
+### useAccess
+
+我们提供了一个 Hooks 用于在组件中获取权限相关信息，如下所示：
+
+```js
+import React from 'react';
+import { useAccess } from 'umi';
+
+const PageA = (props) => {
+ const { foo } = props;
+ const access = useAccess();
+
+ if (access.canReadFoo) {
+ // 如果可以读取 Foo，则...
+ }
+
+ return <>TODO;
+};
+
+export default PageA;
+```
+
+配合 `Access` 组件可以很简单的实现页面内的元素的权限控制。
+
+### Access
+
+可以在业务组件中使用插件提供的 React hook `useAccess` 以及组件 `
+ Can not read foo content.
}
+ >
+ Foo content.
+
+ with antd@{version}
+{user.username}
}
+ );
+}
+```
+
+其中，`useModel()` 方法传入的参数为 Model 的**命名空间**。
+
+:::info{title=💡}
+如果您使用 VSCode 作为 Umi 项目开发的 IDE，推荐搭配 [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model)插件使用。它允许您快速跳转到定义 Model 的文件：
+
+
+:::
+
+## 性能优化
+
+`useModel()` 方法可以接受可选的第二个参数，当组件只需要使用 Model 中的部分参数，而对其它参数的变化不感兴趣时，可以传入一个函数进行过滤。以实现计数器的操作按钮为例：
+
+```tsx
+// src/components/CounterActions/index.tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { add, minus } = useModel('counterModel', (model) => ({
+ add: model.increment,
+ minus: model.decrement,
+ }));
+
+ return (
+
+
+
+
+ );
+};
+```
+
+上面的组件并不关心计数器 Model 中的 `counter` 值，只需要使用 Model 提供的 `increment()` 和 `decrement()` 方法。于是我们传入了一个函数作为 `useModel()` 方法的第二个参数，该函数的返回值将作为 `useModel()` 方法的返回值。
+
+这样，我们过滤掉了 `counter` 这一频繁变化的值，避免了组件重复渲染带来的性能损失。
+
+## 全局初始状态
+
+`@umi/max` 内置了**全局初始状态管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts)，允许您快速构建并在组件内获取 Umi 项目全局的初始状态。
+
+全局初始状态是一种特殊的 Model。
+
+全局初始状态在整个 Umi 项目的最开始创建。编写 `src/app.ts` 的导出方法 `getInitialState()`，其返回值将成为全局初始状态。例如：
+
+```ts
+// src/app.ts
+import { fetchInitialData } from '@/services/initial';
+
+export async function getInitialState() {
+ const initialData = await fetchInitialData();
+ return initialData;
+}
+```
+
+现在，各种插件和您定义的组件都可以通过 `useModel('@@initialState')` 直接获取到这份全局的初始状态，如下所示：
+
+```tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { initialState, loading, error, refresh, setInitialState } =
+ useModel('@@initialState');
+ return <>{initialState};
+};
+```
+
+| 对象属性 | 类型 | 介绍 |
+| --- | --- | --- |
+| `initialState` | `any` | 导出的 `getInitialState()` 方法的返回值 |
+| `loading` | `boolean` | `getInitialState()` 或 `refresh()` 方法是否正在进行中。在首次获取到初始状态前，页面其他部分的渲染都会**被阻止** |
+| `error` | `Error` | 如果导出的 `getInitialState()` 方法运行时报错，报错的错误信息 |
+| `refresh` | `() => void` | 重新执行 `getInitialState` 方法，并获取新的全局初始状态 |
+| `setInitialState` | `(state: any) => void` | 手动设置 `initialState` 的值，手动设置完毕会将 `loading` 置为 `false` |
+
+## Qiankun 父子应用间通信
+
+`@umi/max` 内置了 **Qiankun 微前端**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)，当使用数据流插件时，它允许微应用通过 `useModel('@@qiankunStateFromMaster')` 方法获取父应用传递给子应用的数据 Model，进而实现父子应用间的通信。
+
+具体的使用方法请查阅[微前端的父子应用通信章节](./micro-frontend#父子应用通信)。
+
+## API
+
+### `useModel`
+
+`useModel()` 是一个钩子函数，提供了使用 Model 的能力。它接受两个参数：
+
+| 参数 | 类型 | 介绍 |
+| --- | --- | --- |
+| `namespace` | `String` | Model 文件的命名空间 |
+| `updater` | `(model: any) => any` | 可选参数。传入一个函数，函数的返回值为当前组件中需要使用到的 Model 状态或数据，并作为 `useModel()` 方法的返回值。对优化组件性能具有重要意义。 |
+
+```tsx
+// src/components/AdminInfo/index.tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { user, fetchUser } = useModel('adminModel', (model) => ({
+ user: model.admin,
+ fetchUser: model.fetchAdmin,
+ }));
+
+ return <>hello;
+};
+```
diff --git a/docs/docs/docs/max/dva.en-US.md b/docs/docs/docs/max/dva.en-US.md
new file mode 100644
index 000000000000..a0ce5007371d
--- /dev/null
+++ b/docs/docs/docs/max/dva.en-US.md
@@ -0,0 +1,341 @@
+---
+order: 13
+toc: content
+---
+# dva
+
+## 为什么需要状态管理
+
+React 的组件只是通过 jsx 以及样式按照 state 构建最终的 UI，真正将页面动态化的实际上是 state 的变化实现的。对于简单的前端应用，在组件中通过组件自身的 state 加上父组件通过 props 状态的传递就能够满足应用数据管理的需求。但是当应用膨胀到一定程度后就会导致组件内维护的状态非常的复杂，加上组件之间状态的传递，很容易导致数据管理混乱。很小的修改都可能导致难以预料的副作用。
+
+所以我们需要纯净的 UI 组件，除了渲染逻辑，不再杂糅其他（比如网络请求）。这样我们就要想办法把与渲染无关的业务逻辑抽离出来，形成独立的层（在 Umi 中就是 `src/models` 文件夹中所管理的 model ）去管理。让所有组件降级为`无状态组件`，仅仅依赖 props 渲染。这样 UI 层面就不需关心渲染无关的逻辑，专注做 UI 渲染。（注：这里说的组件主要是指 page 下面的页面组件，对于 component 下的组件本身就应该是比较通用的组件，更应该仅仅依赖 props 渲染，它们也不应该有 model，数据应该通过在页面组件中通过 props 传递过去）。
+
+## 简单的数据共享
+
+对于简单的应用，不需要复杂的数据流，只需要一些简单的数据共享。我们推荐使用 [中台最佳实践简易数据流](./data-flow) 。
+
+## Umi 如何管理状态
+
+如下图所示，Umi 内置了 [Dva](https://dvajs.com) 提供了一套状态管理方案：
+
+
+
+数据统一在 `src/models` 中的 model 管理，组件内尽可能的不去维护数据，而是通过 connect 去关联 model 中的数据。页面有操作的时候则触发一个 action 去请求后端接口以及修改 model 中的数据，将业务逻辑分离到一个环形的闭环中，使得数据在其中单向流动。让应用更好维护。这样的思想最初来源于 Facebook 的 [flux](http://facebook.github.io/flux/)。接下来我们来具体看看如何在 Umi 中实现这样的逻辑。
+
+### 配置 dva
+
+首先你需要配置 `dva: {}` 打开 Umi 内置的 dva 插件。
+
+### 添加 model
+
+Umi 会默认将 `src/models` 下的 model 定义自动挂载，你只需要在 model 文件夹中新建文件即可新增一个 model 用来管理组件状态。
+
+在 2.0 后，为了更好的支持移动端的 H5 项目的按需加载和大型项目的 model 组织，对于某个 page 文件夹下面的 model 我们也会默认挂载，具体结构可以参考[目录结构说明](../guides/directory-structure)。但是需要注意的是 model 的 namespace 是全局的，你仍然需要保证你的 namesapce 唯一（默认是文件名）。对于大部分的项目，我们推荐统一放到 model 中进行管理即可，不需要使用该功能。
+
+model 的写法参考如下示例：
+
+```js
+import { queryUsers, queryUser } from '../../services/user';
+
+export default {
+ state: {
+ user: {},
+ },
+
+ effects: {
+ *queryUser({ payload }, { call, put }) {
+ const { data } = yield call(queryUser, payload);
+ yield put({ type: 'queryUserSuccess', payload: data });
+ },
+ },
+
+ reducers: {
+ queryUserSuccess(state, { payload }) {
+ return {
+ ...state,
+ user: payload,
+ };
+ },
+ },
+
+ test(state) {
+ console.log('test');
+ return state;
+ },
+};
+```
+
+### 把组件和 model connect 在一起
+
+新建完成 model 之后你就可以在组件中通过 ES6 的 [Decorator](http://es6.ruanyifeng.com/#docs/decorator) 方便的把 model 和组件 connect 到一起。然后你就可以在组件中通过`this.props.[modelName]`的方式来访问 model 中的数据了。（在对应的 model 中，默认 namespace 即为文件名）
+
+组件如下示例：
+
+```javascript
+import React, { Component } from 'react';
+import { connect } from 'umi';
+
+@connect(({ user }) => ({
+ user,
+}))
+class UserInfo extends Component {
+ constructor(props) {
+ super(props);
+ }
+ render() {
+ return {this.props.user.name}
;
+ }
+}
+
+export default UserInfo;
+```
+
+### 在组件中 dispatch 事件
+
+connect 方法同时也会添加 `dispatch` 到 `this.props` 上，你可以在用户触发某个事件的时候调用它来触发 model 中的 effects 或者 reducer 来修改 model 中的数据。如下所示：
+
+```javascript
+import React, { Component } from 'react';
+import { connect } from 'umi';
+
+@connect(({ user }) => ({
+ user,
+}))
+class UserInfo extends Component {
+ constructor(props) {
+ super(props);
+ }
+ render() {
+ return (
+ {
+ this.props.dispatch({
+ type: 'user/test',
+ });
+ }}
+ >
+ {this.props.user.name}
+
+ );
+ }
+}
+
+export default UserInfo;
+```
+
+### 修改数据
+
+dispatch 一个 action 之后会按照 action 中的 type 找到定义在 model 中的一个 effect 或者 reducer。
+
+如果是 effect，那么可以去请求后端数据，然后再触发一个 reducer 来修改数据。通过 reducer 修改数据之后组件便会按照最新的数据更新，至此，一次数据的流动就结束了。
+
+## 文档
+
+### model 定义
+
+一个 model 中可以定义如下几个部分：
+
+- namespace # model 的命名空间，唯一标识一个 model，如果与文件名相同可以省略不写
+- state # model 中的数据
+- effects # 异步 action，用来发送异步请求
+- reducers # 同步 action，用来修改 state
+
+### connect
+
+`connect` 的是用来将 model 和组件关联在一起的，它会将相关数据和 `dispatch` 添加到组件的 `props` 中。如下所示：
+
+```jsx
+import React, { Component } from 'react';
+import { connect } from 'umi';
+
+const mapModelToProps = allModels => {
+ return {
+ test: 'hello world',
+ // props you want connect to Component
+ };
+};
+
+@connect(mapModelToProps)
+class UserInfo extends Component {
+ render() {
+ return {this.props.test}
;
+ }
+}
+
+export default UserInfo;
+```
+
+推荐通过注解的方式调用 connect，它等同于 `export default connect(mapModelToProps)(UserInfo);`。connect 接收一个参数，是一个方法，在该方法中你接收到所有的 model 信息，需要返回要添加到 props 上的对象。在上面的例子中你就可以通过 `this.props.test` 得到 `hello world` 的字符串了。
+
+### dispatch
+
+在使用 `connect` 将组件和 model 关联在一起的同时框架也会添加一个 `this.props.dispatch` 的方法，通过该方法你可以触发一个 action 到 model 中。如下所示：
+
+```jsx
+render () {
+ return {
+ this.props.dispacth({
+ type: 'modelnamespace/actionname',
+ sometestdata: 'xxx',
+ othertestata: {},
+ }).then(() => {
+ // it will return a promise
+ // action success
+ });
+ }}>test
+}
+```
+
+通过 `this.props.dispatch` 触发的 action 分为 effect 和 reducer 两类，下面是对他们的更多细节说明。
+
+### Reducer
+
+reducer 是一个函数，用来处理修改数据的逻辑（同步，不能请求后端）。接受 state 和 action，返回老的或新的 state 。即：`(state, action) => state`。
+
+#### 增删改
+
+以 todos 为例。
+
+```javascript
+exports default {
+ namespace: 'todos',
+ state: [],
+ reducers: {
+ add(state, { payload: todo }) {
+ return state.concat(todo);
+ },
+ remove(state, { payload: id }) {
+ return state.filter(todo => todo.id !== id);
+ },
+ update(state, { payload: updatedTodo }) {
+ return state.map(todo => {
+ if (todo.id === updatedTodo.id) {
+ return { ...todo, ...updatedTodo };
+ } else {
+ return todo;
+ }
+ });
+ },
+ },
+};
+```
+
+#### 嵌套数据的增删改
+
+建议最多一层嵌套，以保持 state 的扁平化，深层嵌套会让 reducer 很难写和难以维护。
+
+```javascript
+app.model({
+ namespace: 'app',
+ state: {
+ todos: [],
+ loading: false,
+ },
+ reducers: {
+ add(state, { payload: todo }) {
+ const todos = state.todos.concat(todo);
+ return { ...state, todos };
+ },
+ },
+});
+```
+
+下面是深层嵌套的例子，应尽量避免。
+
+```javascript
+app.model({
+ namespace: 'app',
+ state: {
+ a: {
+ b: {
+ todos: [],
+ loading: false,
+ },
+ },
+ },
+ reducers: {
+ add(state, { payload: todo }) {
+ const todos = state.a.b.todos.concat(todo);
+ const b = { ...state.a.b, todos };
+ const a = { ...state.a, b };
+ return { ...state, a };
+ },
+ },
+});
+```
+
+### Effect
+
+effects 是定义在 model 中的。它也是一种类型的 action，主要用于和后端的异步通讯。通过 effects 请求后端发送和接收必要的数据之后可以通过 put 方法再次发送一个 reducer 来修改数据。
+
+effect 通过 ES6 中 [Generator 函数](http://es6.ruanyifeng.com/#docs/generator) 来支持通过顺序的代码实现异步的请求，示例如下：
+
+```javascript
+export default {
+ namespace: 'todos',
+ effects: {
+ *addRemote({ payload: todo }, { put, call }) {
+ yield call(addTodo, todo);
+ yield put({ type: 'add', payload: todo });
+ },
+ },
+};
+```
+
+effects 中定义的 action 都必须是通过 `*` 定义的 Generator 函数，然后在函数中通过关键字 `yield` 来触发异步逻辑。
+
+#### Effects
+
+##### put
+
+用于触发 action 。
+
+```javascript
+yield put({ type: 'todos/add', payload: 'Learn Dva' });
+```
+
+##### call
+
+用于调用异步逻辑，支持 promise 。
+
+```javascript
+const result = yield call(fetch, '/todos');
+```
+
+##### select
+
+用于从 state 里获取数据。
+
+```javascript
+const todos = yield select(state => state.todos);
+```
+
+### loading
+
+框架会默认添加一个命名空间为 loading 的 model，该 model 包含 effects 异步加载 loading 的相关信息，它的 state 格式如下：
+
+```js
+{
+ global: Boolean, // 是否真正有异步请求发送中
+ models: {
+ [modelnamespace]: Boolean, // 具体每个 model 的加载情况
+ },
+ effects: {
+ [modelnamespace/effectname]: Boolean, // 具体每个 effect 的加载情况
+ },
+}
+```
+
+你可以使用该 model 实现在组件中添加 loading 动画。
+
+## 调试
+
+### redux
+
+dva 的底层是基于 redux，所以你可以安装 redux 的[开发者工具](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=zh-CN)用来查看 model 中的数据和变化的记录。
+
+
+
+## 参考文章
+
+- [dva 官网](https://dvajs.com/)
diff --git a/docs/docs/docs/max/i18n.en-US.md b/docs/docs/docs/max/i18n.en-US.md
new file mode 100644
index 000000000000..59ce33439601
--- /dev/null
+++ b/docs/docs/docs/max/i18n.en-US.md
@@ -0,0 +1,528 @@
+---
+order: 8
+toc: content
+---
+
+# 国际化
+
+`@umi/max` 内置了[国际化插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts)，它可以轻松地将国际化功能集成到你的 Umi 应用程序之中。
+
+## 开始使用
+
+国际化插件采用约定式目录结构，我们约定在 `src/locales` 目录下引入多语言文件。
+
+多语言文件的命名需遵循此规范：`
+
+ );
+};
+```
+
+渲染的结果如下：
+
+```html
+
+欢迎光临 Umi 的世界！
+
+
+Welcome to Umi's world!
+```
+
+## 在组件的参数中使用
+
+在某些情况下，您需要将多语言内容作为参数传递给某个组件。可以通过 `intl` 对象来实现：
+
+```tsx
+import { Alert } from 'antd';
+import { useIntl } from 'umi';
+
+export default function Page() {
+ const intl = useIntl();
+ const msg = intl.formatMessage({
+ id: 'welcome',
+ });
+
+ return
+
{msg}
; +}; +``` + +注意，用于赋值的键值对对象应当作为 `formatMessage()` 方法的第二个参数传递。 + +渲染的结果如下： + +```html + +张三，今天也是美好的一天！
+ + +张三, what a nice day!
+``` + +## 切换语言 + +通过预设的 `
+
+ );
+};
+```
+
+[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/safe-remote-component.tsx)
+
+### rawMfImport
+
+加载远端模块，接口如下。
+
+```ts
+rawMfImport(opts: {
+ entry: string;
+ remoteName: string;
+ moduleName: string;
+}): Promise{JSON.stringify(masterProps)}
;
+}
+```
+
+或者可以通过高阶方法 `connectMaster()` 来获取并消费父应用透传的数据，如下所示：
+
+```tsx
+import { connectMaster } from 'umi';
+
+function MyPage(props) {
+ return {JSON.stringify(props)}
;
+}
+
+export default connectMaster(MyPage);
+```
+
+子应用也可以在生命周期钩子中能够获取并消费得到的 `props` 属性，根据需求[实现对应的生命周期钩子](#子应用配置生命周期钩子)即可。
+
+特别的，当父应用使用 `
+
+```
+
+### 子应用加载动画
+
+启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 `MOUNTED` 状态时，加载状态结束，显示子应用内容。
+
+#### 基于 antd 的加载动画
+
+当您使用 antd 作为项目组件库时，可以向子应用传入 `autoSetLoading` 属性以开启子应用加载动画，插件将会自动调用 antd 的 [`
+
+如果通过路由的模式引入子应用，可以配置如下：
+
+```ts
+// .umirc.ts
+export default {
+ routes: [
+ {
+ path: '/app1',
+ microApp: 'app1',
+ microAppProps: {
+ autoCaptureError: true,
+ },
+ },
+ ],
+};
+```
+
+如果通过组件的模式引入子应用，直接将 `autoCaptureError` 作为参数传入即可：
+
+```tsx
+import { MicroApp } from 'umi';
+
+export default function Page() {
+ return {error?.message}
;
+}
+```
+
+注意：`errorBoundary` 的优先级高于 `defaultErrorBoundary`。
+
+## 环境变量
+
+如果您有一些不能显式编写在 `.umirc.ts` 或 `src/app.ts` 中的配置信息，可以将它们存放在环境变量文件中。例如编写父应用的环境变量文件 `.env` 如下：
+
+```plaintext
+INITIAL_QIANKUN_MASTER_OPTIONS="{\"apps\":[{\"name\":\"app1\",\"entry\":\"//localhost:7001\"},{\"name\":\"app2\",\"entry\":\"//localhost:7002\"}]}"
+```
+
+在内部，微前端插件会执行 `JSON.parse(process.env.INITIAL_QIANKUN_MASTER_OPTIONS)` 方法，然后将得到的结果与已有的配置信息合并。上面编写的环境变量，合并后相当于编写了如下配置信息：
+
+```ts
+export default {
+ qiankun: {
+ master: {
+ apps: [
+ {
+ name: 'app1',
+ entry: '//localhost:7001',
+ },
+ {
+ name: 'app2',
+ entry: '//localhost:7002',
+ },
+ ],
+ // ... .umirc.ts 中其它的配置信息
+ },
+ },
+};
+```
+
+需注意的是，当存在相同的配置项时，例如 `apps` 项，写在 `.umirc.ts` 中的配置项将**覆盖**环境变量中的配置项。
+
+同理，对于子应用，可以编写环境变量 `.env` 文件如下：
+
+```plaintext
+INITIAL_QIANKUN_SLAVE_OPTIONS="{\"enable\":false}"
+```
+
+相当于编写了如下配置信息：
+
+```ts
+export default {
+ qiankun: {
+ slave: {
+ enable: false,
+ // ... .umirc.ts 中其它的配置信息
+ },
+ },
+};
+```
+
+## API
+
+### MasterOptions
+
+| 属性 | 必填 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- | --- |
+| `enable` | 否 | 启用 Qiankun 微应用插件，设置为 `false` 时为不启用 | `boolean` | `undefined` |
+| `apps` | 是 | 微应用配置 | [`App[]`](#app) | `undefined` |
+| `routes` | 否 | 微应用运行时的路由 | [`Route[]`](#route) | `undefined` |
+| `defaultErrorBoundary` | 否 | 子应用默认的错误捕获组件，值为文件路径 | `string` | - |
+| `defaultLoader` | 否 | 子应用默认的加载动画，值为文件路径 | `string` | - |
+| `sandbox` | 否 | 是否开启沙箱模式 | `boolean \| { strictStyleIsolation: boolean, experimentalStyleIsolation: boolean }` | `true` |
+| `prefetch` | 否 | 是否启用微应用预加载 | `boolean \| 'all' \| string[] \| (( apps: RegistrableApp[] ) => { criticalAppNames: string[]; minorAppsName: string[] })` | `true` |
+
+关于沙箱和预加载的介绍可见[此页面](https://qiankun.umijs.org/zh/api/#startopts)。
+
+### SlaveOptions
+
+| 属性 | 必填 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- | --- |
+| `enable` | 否 | 启用 Qiankun 微应用插件，设置为 `false` 时为不启用 | `boolean` | `undefined` |
+
+### App
+
+| 属性 | 必填 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- | --- |
+| `name` | 是 | 微应用的名称 | `string` |
+| `entry` | 是 | 微应用的 HTML 地址 | `string` | `{ script: string[], styles: [] }` |
+| `credentials` | 否 | 拉取微应用时同时拉取 Cookies，详见[此介绍](https://qiankun.umijs.org/zh/faq#%E5%A6%82%E4%BD%95%E8%A7%A3%E5%86%B3%E6%8B%89%E5%8F%96%E5%BE%AE%E5%BA%94%E7%94%A8-entry-%E6%97%B6-cookie-%E6%9C%AA%E6%90%BA%E5%B8%A6%E7%9A%84%E9%97%AE%E9%A2%98) | `boolean` | `false` |
+| `props` | 否 | 父应用传递给微应用的数据，详见[父子应用通信章节](#父子应用通信) | `object` | `{}` |
+
+### Route
+
+| 属性 | 必填 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- | --- |
+| `path` | 是 | 路由 PATH | `string` |
+| `microApp` | 是 | 关联的微应用名称 | `string` |
+| `microAppProps` | 否 | 微应用的配置 | [`MicroAppProps`](#microappprops) | `{}` |
+
+### MicroAppProps
+
+| 属性 | 必填 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- | --- |
+| `autoSetLoading` | 否 | 自动设置微应用的加载状态 | `boolean` | `false` |
+| `loader` | 否 | 自定义的微应用加载状态组件 | `(loading) => React.ReactNode` | `undefined` |
+| `autoCaptureError` | 否 | 自动设置微应用的错误捕获 | `boolean` | `false` |
+| `errorBoundary` | 否 | 自定义的微应用错误捕获组件 | `(error: any) => React.ReactNode` | `undefined` |
+| `className` | 否 | 微应用的样式类 | `string` | `undefined` |
+| `wrapperClassName` | 否 | 包裹微应用加载组件、错误捕获组件和微应用的样式类，仅在启用加载组件或错误捕获组件时有效 | `string` | `undefined` |
+
+## FAQ
+
+### 子应用的生命周期钩子加载了，但是页面没有渲染
+
+如果页面没有报错，且通过查看 DOM 发现子应用的根节点已经有了，只是内容是空，这种基本可以确定是因为当前 url 没有匹配到子应用的任何路由导致的。
+
+比如我们在主应用中配置了：
+
+```js
+{
+ path: '/app1',
+ microApp: 'app1',
+}
+```
+
+子应用的路由配置是：
+
+```js
+{
+ path: '/user',
+ component: './User',
+}
+```
+
+那么我们必须通过 `/app1/user` 路径才能正常的访问到子应用的 user 页面。
diff --git a/docs/docs/docs/max/react-query.en-US.md b/docs/docs/docs/max/react-query.en-US.md
new file mode 100644
index 000000000000..180ec5932bd1
--- /dev/null
+++ b/docs/docs/docs/max/react-query.en-US.md
@@ -0,0 +1,92 @@
+---
+order: 11
+toc: content
+---
+# react-query
+
+@umijs/max 内置了 [react-query](https://tanstack.com/query/)（和 @tanstack/react-query 是同一个）请求方案。
+
+## 启用方式
+
+如果是 @umijs/max，配置开启。
+
+```ts
+export default {
+ reactQuery: {},
+}
+```
+
+如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
+
+```bash
+$ pnpm i @umijs/plugins -D
+```
+
+```ts
+export default {
+ plugins: ['@umijs/plugins/dist/react-query'],
+ reactQuery: {},
+}
+```
+
+## 特性
+
+插件帮你做了几件事，
+
+1、dev 模式下开启 react query 的 devtool，可通过 `reactQuery: { devtool: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { devtool }` 配置。
+
+2、注册全局的 QueryClient，可通过 `reactQuery: { queryClient: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { queryClient }` 配置。
+
+3、大部分 react-query 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
+
+## 配置项
+
+可以在 `reactQuery` 中做以下配置。
+
+- `devtool`: boolean，是否开启 react query 官方 devtool 工具，默认 `true`
+- `queryClient`: boolean, 是否注册全局的 QueryClient 和 QueryClientProvier，默认 `true`
+
+比如：
+
+```ts
+export default {
+ reactQuery: {
+ devtool: false,
+ queryClient: false,
+ },
+}
+```
+
+注：以上两个配置的运行时配置需在 `app.ts` 里进行配置。
+
+## 运行时配置项
+
+包含以下配置。
+
+- `devtool`：object
+- `queryClient`: object
+
+比如：
+
+```ts
+const API_SERVER = '/path/to/api/server';
+export const reactQuery = {
+ devtool: {
+ initialIsOpen: true,
+ },
+ queryClient: {
+ defaultOptions: {
+ queries: {
+ queryFn: async ({ queryKey }) => {
+ const res = await fetch(`${API_SERVER}/${queryKey.join('/')}`);
+ if (res.status !== 200) {
+ throw new Error(res.statusText);
+ }
+ return res.json();
+ }
+ }
+ }
+ },
+};
+```
+
diff --git a/docs/docs/docs/max/request.en-US.md b/docs/docs/docs/max/request.en-US.md
new file mode 100644
index 000000000000..06a9b62039de
--- /dev/null
+++ b/docs/docs/docs/max/request.en-US.md
@@ -0,0 +1,405 @@
+---
+order: 6
+toc: content
+---
+
+# 请求
+
+`@umijs/max` 内置了插件方案。它基于 [axios](https://axios-http.com/) 和 [ahooks](https://ahooks-v2.surge.sh) 的 `useRequest` 提供了一套统一的网络请求和错误处理方案。
+
+```js
+import { request, useRequest } from 'umi';
+
+request;
+useRequest;
+```
+
+## 配置
+### 构建时配置
+```js
+export default {
+ request: {
+ dataField: 'data'
+ },
+};
+```
+
+构建时配置可以为 useRequest 配置 `dataField` ，该配置的默认值是 `data`。该配置的主要目的是方便 useRequest 直接消费数据。如果你想要在消费数据时拿到后端的原始数据，需要在这里配置 `dataField` 为 `''` 。
+
+比如你的后端返回的数据格式如下。
+
+```js
+{
+ success: true,
+ data: 123,
+ code: 1,
+}
+```
+
+那么 useRequest 就可以直接消费 `data`。其值为 123，而不是 `{ success, data, code }` 。
+
+### 运行时配置
+
+在 `src/app.ts` 中你可以通过配置 request 项，来为你的项目进行统一的个性化的请求设定。
+
+```ts
+import type { RequestConfig } from 'umi';
+
+export const request: RequestConfig = {
+ timeout: 1000,
+ // other axios options you want
+ errorConfig: {
+ errorHandler(){
+ },
+ errorThrower(){
+ }
+ },
+ requestInterceptors: [],
+ responseInterceptors: []
+};
+```
+
+除了 `errorConfig`, `requestInterceptors`, `responseInterceptors` 以外其它配置都直接透传 [axios](https://axios-http.com/docs/req_config) 的 request 配置。**在这里配置的规则将应用于所有的** `request` 和 `useRequest` **方法**。
+
+下面分别介绍 `plugin-request` 的运行时配置项。本节的末尾，我们会给出一个完整的运行时配置示例，并且对它的功能进行一个详细的描述。
+
+#### errorConfig
+如果你想要为自己的请求设定统一的错误处理方案，可以在这里进行配置。
+
+其中 `errorThrower` 接收你后端返回的数据并且需要抛出一个你自己设定的 error， 你可以在这里根据后端的数据进行一定的处理。
+
+我们的 `request` 会 catch `errorThrower` 抛出的错误，并且执行你的 `errorHandler` 方法，该方法接收两个参数，第一个参数是 catch 到的 error，第二个参数则是 request 的 opts。
+
+这里面的 `errorHandler` 和 `errorThrower` 需要配套使用。文档的末尾有一个完整的例子。
+
+如果你觉得这种方式进行错误处理过于繁琐，可以直接在拦截器中实现自己的错误处理。
+
+:::info{title=🚨}
+`errorThrower` 是利用 `responseInterceptors` 实现的，它的触发条件是: 当 `data.success` 为 `false` 时。
+:::
+
+#### requestInterceptors
+为 request 方法添加请求阶段的拦截器。
+
+传入一个数组，每个元素都是一个拦截器，它们会被按顺序依次注册到 axios 实例上。拦截器的写法同 axios request interceptor 一致，它需要接收 request config 作为参数，并且将它返回。
+
+我们建议你使用 `RequestConfig`，它能帮助你规范地书写你的拦截器。
+
+e.g.
+```ts
+const request: RequestConfig = {
+ requestInterceptors: [
+ // 直接写一个 function，作为拦截器
+ (url, options) =>
+ {
+ // do something
+ return { url, options }
+ },
+ // 一个二元组，第一个元素是 request 拦截器，第二个元素是错误处理
+ [(url, options) => {return { url, options }}, (error) => {return Promise.reject(error)}],
+ // 数组，省略错误处理
+ [(url, options) => {return { url, options }}]
+ ]
+
+}
+```
+
+另外，为了更好的兼容 umi-request，我们允许 umi-request 的拦截器写法，尽管它不能够通过 typescript 的语法检查。
+
+#### responseInterceptors
+为 request 方法添加响应阶段的拦截器。
+
+传入一个数组，每个元素都是一个拦截器，它们会被按顺序依次注册到 axios 实例上。拦截器的写法同 axios response interceptor一致。接收 axios 的 response 作为参数，并且将它返回。
+
+我们建议你使用 `RequestConfig`，它能帮助你规范地书写你的拦截器。
+
+e.g.
+```ts
+const request: RequestConfig = {
+ responseInterceptors: [
+ // 直接写一个 function，作为拦截器
+ (response) =>
+ {
+ // 不再需要异步处理读取返回体内容，可直接在data中读出，部分字段可在 config 中找到
+ const { data = {} as any, config } = response;
+ // do something
+ return response
+ },
+ // 一个二元组，第一个元素是 request 拦截器，第二个元素是错误处理
+ [(response) => {return response}, (error) => {return Promise.reject(error)}],
+ // 数组，省略错误处理
+ [(response) => {return response}]
+ ]
+
+}
+```
+
+**注意： 我们会按照你的数组顺序依次注册拦截器，但是其执行顺序参考 axios，request 是后添加的在前，response 是后添加的在后**
+
+## API
+### useRequest
+插件内置了 [@ahooksjs/useRequest](https://ahooks-v2.js.org/hooks/async) ，你可以在组件内通过该 Hook 简单便捷的消费数据。示例如下：
+```typescript
+import { useRequest } from 'umi';
+
+export default function Page() {
+ const { data, error, loading } = useRequest(() => {
+ return services.getUserList('/api/test');
+ });
+ if (loading) {
+ return loading...
;
+ }
+ if (error) {
+ return {error.message}
;
+ }
+ return {data.name}
;
+};
+```
+上面代码中 data 并不是你后端返回的数据，而是其内部的 data，（因为构建时配置默认是 'data')
+
+需要注意的是，ahooks 已经更新到3.0，而我们为了让 `umi@3` 的项目升级起来不那么困难，继续沿用了 ahooks2.0
+
+
+### request
+通过 `import { request } from '@@/plugin-request'` 你可以使用内置的请求方法。
+
+`request` 接收的 `options`除了透传 [axios](https://axios-http.com/docs/req_config) 的所有 config 之外，我们还额外添加了几个属性 `skipErrorHandler`，`getResponse`，`requestInterceptors` 和 `responseInterceptors` 。
+
+示例如下：
+```typescript
+request('/api/user', {
+ params: { name : 1 },
+ timeout: 2000,
+ // other axios options
+ skipErrorHandler: true,
+ getResponse: false,
+ requestInterceptors: [],
+ responseInterceptors: [],
+}
+```
+
+当你的某个请求想要跳过错误处理时，可以通过将`skipErrorHandler`设为 `true` 来实现
+
+request 默认返回的是你后端的数据，如果你想要拿到 axios 完整的 response 结构，可以通过传入 `{ getResponse: true }` 来实现。
+
+`requestInterceptors` 和 `responseInterceptors` 的写法同运行时配置中的拦截器写法相同，它们为 request 注册拦截器。区别在于这里注册的拦截器是 "一次性" 的。另外，这里写的拦截器会在运行时配置中的拦截器之后被注册。
+
+**注意： 当你使用了 errorHandler 时，在这里注册的 response 拦截器会失效，因为在 errorHandler 就会 throw error**
+
+### RequestConfig
+这是一个接口的定义，可以帮助你更好地配置运行时配置。
+```typescript
+import type { RequestConfig } from 'umi';
+
+export const request:RequestConfig = {};
+```
+注意，在导入时要加 type
+
+## umi@3 到 umi@4
+在 `umi@3` 到 `umi@4` 的升级中，我们弃用了 umi-request ，选用了 axios 作为默认的请求方案。在这个更换中，我们的功能也发生了一些变化。
+
+### 运行时配置的变动
+相比于 `umi@3`， `umi@4` 的运行时配置发生了较大的变化。
+```diff
+ export const request: RequestConfig = {
+ errorConfig: {
+++ errorHandler: () => {},
+++ errorThrower: () => {}
+-- errorPage: '',
+-- adaptor: ()=>{},
+ };
+-- middlewares: [],
+++ requestInterceptors: [],
+++ responseInterceptors: [],
+ ... // umi-request 和 axios 的区别。
+ };
+```
+
+- umi-request 的配置项变成了 axios 的配置项
+- 去除了 middlewares 中间件。你可以使用 axios 的 [拦截器](https://axios-http.com/docs/interceptors) 来实现相同的功能。
+- errorConfig 删除了原来的所有配置，新增了 errorHandler 和 errorThrower 来进行统一错误处理的设定。
+
+中间件的替换方式。对于一个 `umi@3` 的中间件，`next()` 方法之前的需要放在 `requestInterceptors` 中，`next()` 方法之后的内容则需要放在 `responseInterceptors` 中。
+
+```ts
+
+// 中间件
+async function middleware(ctx, next) {
+ const { url, options } = req;
+ if (url.indexOf('/api') !== 0) {
+ ctx.req.url = `/api/v1/${url}`;
+ }
+ await next();
+ if (!ctx.res.success) {
+ // do something
+ }
+}
+
+// 拦截器
+{
+ requestInterceptors:[
+ (config) => {
+ if (config.url.indexOf('/api') !== 0) {
+ config.url = `/api/v1/${url}`;
+ }
+ return config;
+ }
+ ],
+ responseInterceptors: [
+ (response) => {
+ if(!response.data.success){
+ // do something
+ }
+ }
+ ]
+}
+```
+
+### request 方法的参数变动
+[umi-request](https://github.com/umijs/umi-request#request-options) 和 [axios](https://axios-http.com/docs/req_config) 的配置项有着一定的区别。具体可以查看其各自的文档进行比较。
+
+### GET 请求参数序列化
+
+[Umi@3](https://github.com/umijs/umi-request/blob/master/src/middleware/simpleGet.js) 默认会用相同的 Key 来序列化数组。Umi@4 请求基于 axios，默认是带括号 `[]` 的形式序列化。
+
+```tsx
+// Umi@3
+import { useRequest } from 'umi';
+// a: [1,2,3] => a=1&a=2&a=3
+
+// Umi@4
+import { useRequest } from '@umijs/max';
+// a: [1,2,3] => a[]=1&a[]=2&a[]=3
+```
+
+如果希望保持 Umi@3 这种形式，可以这样做：
+
+```ts
+// src/app.[ts|tsx]
+
+/** @doc https://github.com/sindresorhus/query-string#arrayformat-1 */
++ import queryString from 'query-string';
+
+export const request: RequestConfig = {
++ paramsSerializer(params) {
++ return queryString.stringify(params);
++ },
+ ...
+}
+```
+
+## 运行时配置示例
+这里给出一个完整的运行时配置示例，以帮助你能够更好的去为自己的项目设定个性化的请求方案。
+
+```ts
+import { RequestConfig } from './request';
+
+// 错误处理方案： 错误类型
+enum ErrorShowType {
+ SILENT = 0,
+ WARN_MESSAGE = 1,
+ ERROR_MESSAGE = 2,
+ NOTIFICATION = 3,
+ REDIRECT = 9,
+}
+// 与后端约定的响应数据格式
+interface ResponseStructure {
+ success: boolean;
+ data: any;
+ errorCode?: number;
+ errorMessage?: string;
+ showType?: ErrorShowType;
+}
+
+// 运行时配置
+export const request: RequestConfig = {
+ // 统一的请求设定
+ timeout: 1000,
+ headers: {'X-Requested-With': 'XMLHttpRequest'},
+
+ // 错误处理： umi@3 的错误处理方案。
+ errorConfig: {
+ // 错误抛出
+ errorThrower: (res: ResponseStructure) => {
+ const { success, data, errorCode, errorMessage, showType } = res;
+ if (!success) {
+ const error: any = new Error(errorMessage);
+ error.name = 'BizError';
+ error.info = { errorCode, errorMessage, showType, data };
+ throw error; // 抛出自制的错误
+ }
+ },
+ // 错误接收及处理
+ errorHandler: (error: any, opts: any) => {
+ if (opts?.skipErrorHandler) throw error;
+ // 我们的 errorThrower 抛出的错误。
+ if (error.name === 'BizError') {
+ const errorInfo: ResponseStructure | undefined = error.info;
+ if (errorInfo) {
+ const { errorMessage, errorCode } = errorInfo;
+ switch (errorInfo.showType) {
+ case ErrorShowType.SILENT:
+ // do nothing
+ break;
+ case ErrorShowType.WARN_MESSAGE:
+ message.warn(errorMessage);
+ break;
+ case ErrorShowType.ERROR_MESSAGE:
+ message.error(errorMessage);
+ break;
+ case ErrorShowType.NOTIFICATION:
+ notification.open({
+ description: errorMessage,
+ message: errorCode,
+ });
+ break;
+ case ErrorShowType.REDIRECT:
+ // TODO: redirect
+ break;
+ default:
+ message.error(errorMessage);
+ }
+ }
+ } else if (error.response) {
+ // Axios 的错误
+ // 请求成功发出且服务器也响应了状态码，但状态代码超出了 2xx 的范围
+ message.error(`Response status:${error.response.status}`);
+ } else if (error.request) {
+ // 请求已经成功发起，但没有收到响应
+ // \`error.request\` 在浏览器中是 XMLHttpRequest 的实例，
+ // 而在node.js中是 http.ClientRequest 的实例
+ message.error('None response! Please retry.');
+ } else {
+ // 发送请求时出了点问题
+ message.error('Request error, please retry.');
+ }
+ },
+
+ },
+
+ // 请求拦截器
+ requestInterceptors: [
+ (config) => {
+ // 拦截请求配置，进行个性化处理。
+ const url = config.url.concat('?token = 123');
+ return { ...config, url};
+ }
+ ],
+
+ // 响应拦截器
+ responseInterceptors: [
+ (response) => {
+ // 拦截响应数据，进行个性化处理
+ const { data } = response;
+ if(!data.success){
+ message.error('请求失败！');
+ }
+ return response;
+ }
+ ]
+};
+```
+
+上面的例子中的错误处理方案来自于 `umi@3` 的内置错误处理。在这个版本中，我们把它删除了，以方便用户更加自由地定制错误处理方案。如果你仍然想要使用它，可以将这段运行时配置粘贴到你的项目中。
+
+你也可以通过写响应拦截器的方式来进行自己的错误处理，**不一定局限于 errorConfig**。
diff --git a/docs/docs/docs/max/styled-components.en-US.md b/docs/docs/docs/max/styled-components.en-US.md
new file mode 100644
index 000000000000..bc8d461752c2
--- /dev/null
+++ b/docs/docs/docs/max/styled-components.en-US.md
@@ -0,0 +1,93 @@
+---
+order: 10
+toc: content
+---
+# styled-components
+
+@umijs/max 内置了 [styled-components](https://styled-components.com/) 样式方案。
+
+## 启用方式
+
+如果是 @umijs/max，配置开启。
+
+```ts {2}
+export default {
+ styledComponents: {},
+}
+```
+
+如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
+
+```bash
+$ pnpm i @umijs/plugins -D
+```
+
+```ts
+export default {
+ plugins: ['@umijs/plugins/dist/styled-components'],
+ styledComponents: {},
+}
+```
+
+## 特性
+
+插件帮你做了几件事，
+
+1、大部分 styled-components 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
+
+2、支持通过配置的方式开启 styled-components 的 babel 插件，仅 dev 模式有效。
+
+3、支持通过运行时配置的方式声明全局样式。
+
+## 配置项
+
+可以在 `styledComponents` 中做以下配置。
+
+- `babelPlugin`: Object，开启 styled-components 的 babel 插件，仅 dev 模式有效
+
+比如：
+
+```ts
+export default {
+ styledComponents: {
+ babelPlugin: {},
+ },
+}
+```
+
+当你的导入来源不是 `umi` / `@umijs/max` 时，需将导入来源配置到 `topLevelImportPaths` 才可以使该 babel 插件生效，如：
+
+```ts
+import { styled } from 'alita'
+```
+
+```ts
+export default {
+ styledComponents: {
+ babelPlugin: {
+ topLevelImportPaths: ['alita']
+ },
+ },
+}
+```
+
+## 运行时配置项
+
+包含以下配置。
+
+- `GlobalStyle`：ReactComponent
+
+比如：
+
+```ts
+import { createGlobalStyle } from "umi";
+
+export const styledComponents = {
+ GlobalStyle: createGlobalStyle`
+ h1 {
+ background: #ccc;
+ }
+ `
+}
+```
+
diff --git a/docs/docs/docs/max/valtio.en-US.md b/docs/docs/docs/max/valtio.en-US.md
new file mode 100644
index 000000000000..fdca95ffb71e
--- /dev/null
+++ b/docs/docs/docs/max/valtio.en-US.md
@@ -0,0 +1,197 @@
+---
+order: 12
+toc: content
+---
+# valtio
+
+@umijs/max 内置了 valtio 数据流方案。
+
+## 启用 valtio
+
+配置开启。
+
+```ts
+export default {
+ valtio: {},
+}
+```
+
+## 开始使用
+
+### 基本用法
+
+极其简单。
+
+```ts
+import { proxy, useSnapshot } from 'umi';
+
+// 1、定义数据
+const state = proxy({ count: 0 });
+// 2、使用数据
+const snap = useSnapshot(state);
+snap.count;
+// 3、更新数据
+state.count += 1;
+```
+
+### React 外访问
+
+天然支持。
+
+```ts
+import { proxy } from 'umi';
+
+const state = proxy({ count: 0 });
+state.count;
+state.count += 1;
+```
+
+### 数据推导
+
+```ts
+import { proxyWithComputed } from 'umi';
+
+const state = proxyWithComputed({
+ count: 0,
+}, {
+ double: snap => snap.count * 2,
+});
+```
+
+### Action 和异步 Action
+
+两种用法，可以和 state 放一起，也可以分开。
+
+```ts
+import { proxy } from 'umi';
+
+// 方法一：放一起
+const state = proxy({
+ count: 0,
+ actions: {
+ add() {
+ // 注意这里别用 this.count，基于 snap 调用时会报错
+ state.count += 1;
+ },
+ }
+});
+// 方法二：分开放
+const state = proxy({ count: 0 });
+const actions = {
+ add() {
+ state.count += 1;
+ },
+ // 异步 action
+ async addAsync() {
+ state.count += await fetch('/api/add');
+ },
+};
+```
+
+### 数据结构的拆分与组合
+
+```ts
+import { proxy } from 'umi';
+
+// 比如如下定义
+// state.foo 和 state.bar 都是 proxy，可拆分使用
+const state = proxy({
+ foo: { a: 1 },
+ bar: { b: 1 },
+});
+
+// 组合
+const foo = proxy({ a: 1 });
+const bar = proxy({ b: 1 });
+const state = proxy({ foo, bar });
+```
+
+### 组件封装
+
+如果 props 内容和 state 无关，可以不处理；如果有关，按以下方式用 context 包一下，同时做 props 到 state 的数据同步即可。
+
+```ts
+import { proxy } from 'umi';
+
+// 1、createContext
+const MyContext = createContext();
+// 2、Provider
+const value = useRef(proxy({ count: 0 })).current;
+