- @@ -125,6 +97,6 @@ export const Features = () => {
订阅 Umi 的最新动态
- -
@@ -88,10 +39,7 @@ export const Footer = () => {
-
-
+
-
+ 快速上手 →
@@ -174,6 +42,6 @@ export const Hero = () => {
{props.title}
- +- @@ -85,6 +67,6 @@ export const WhoIsUsing = () => { />
+ {!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/develop-blog-using-umi.md b/docs/docs/blog/develop-blog-using-umi.md
index a0216e261333..43b3d49e9c2b 100644
--- a/docs/docs/blog/develop-blog-using-umi.md
+++ b/docs/docs/blog/develop-blog-using-umi.md
@@ -31,9 +31,9 @@ group:
## 环境准备
-首先，你必须确保你的本地环境已经准备好进行一个 Umi.js 项目的开发。如果你目前还没有开发过 Umi.js 项目，也没有在本地搭建过开发环境，建议你先阅读 [开发环境](../guides/prepare) 这篇教学。
+首先，你必须确保你的本地环境已经准备好进行一个 Umi.js 项目的开发。如果你目前还没有开发过 Umi.js 项目，也没有在本地搭建过开发环境，建议你先阅读 [开发环境](../docs/guides/prepare) 这篇教学。
-配置完本地环境以后，你已经准备好开始开发 Umi.js 项目了！跟着 [脚手架](../guides/boilerplate) 这篇文档的教学，快速初始化一个 Umi.js 项目吧。
+配置完本地环境以后，你已经准备好开始开发 Umi.js 项目了！跟着 [脚手架](../docs/guides/boilerplate) 这篇文档的教学，快速初始化一个 Umi.js 项目吧。
### 调整目录结构
@@ -188,7 +188,7 @@ src
### 配置 umi 项目
-最后一步，就是要来对 Umi 项目进行配置，完整的配置可以参考 [配置](../api/config) 这篇教学文档，在本次的教学中，只要按照以下配置即可：
+最后一步，就是要来对 Umi 项目进行配置，完整的配置可以参考 [配置](../docs/api/config) 这篇教学文档，在本次的教学中，只要按照以下配置即可：
```ts
// .umirc.ts
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..0d0ed3424bf5
--- /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://cdnjs.cloudflare.com/polyfill/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 (alicdn)](http://polyfill.alicdn.com/v3/polyfill.min.js) 或 [polyfill.io (CloudFlare)](https://cdnjs.cloudflare.com/polyfill/) 服务。另外，你还可以使用 [polyfill-service](https://github.com/cdnjs/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/legacy-browser.md b/docs/docs/blog/legacy-browser.md
index d3b3d7e09c74..2fc5d5753431 100644
--- a/docs/docs/blog/legacy-browser.md
+++ b/docs/docs/blog/legacy-browser.md
@@ -82,7 +82,7 @@ export default {
export default {
headScripts: [
- 'http://polyfill.alicdn.com/v3/polyfill.min.js', // or https://polyfill.io/v3/polyfill.min.js
+ 'http://polyfill.alicdn.com/v3/polyfill.min.js',
],
legacy: {},
};
@@ -94,7 +94,7 @@ export default {
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 下发服务。 |
+| 动态 polyfill 服务 | 使用根据当前浏览器请求 UA 动态下发所需 polyfill 的服务，比如 [polyfill.io (alicdn)](http://polyfill.alicdn.com/v3/polyfill.min.js) 或 [polyfill.io (CloudFlare)](https://cdnjs.cloudflare.com/polyfill/) 服务。另外，你还可以使用 [polyfill-service](https://github.com/cdnjs/polyfill-service) 自建相同的动态 polyfill 下发服务。 |
注：
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-faster-than-vite.md b/docs/docs/blog/mfsu-faster-than-vite.md index b6337e1071dc..19df5e5a07f9 100644 --- a/docs/docs/blog/mfsu-faster-than-vite.md +++ b/docs/docs/blog/mfsu-faster-than-vite.md @@ -19,8 +19,7 @@ Umi 4 中同时支持 webpack 和 vite 两种构建方式，跑通了后，迫 两个示例、四种模式、四个维度的对比。 - 两个示例分别是大型的全量 ant-design-pro 和小型的 libs example；四种模式分别是 webpack、webpack - + MFSU、webpack + MFSU with esbuild mode、Vite in umi；四个维度分别是无缓存的冷启动、有缓存的热启动、修改代码后的热更新、页面打开速度。 + 两个示例分别是大型的全量 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 的特性，改完后要等请求过来后处理完才算结束，无法统计，但肯定是很快的。 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 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。 + +
+ 
+
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 运行。 + 《比 Vite 更快的 MFSU》。基于此，我们自信地把这个功能在Umi 4 中默认开启。还有值得一提的是，MFSU 可脱离 Umi 运行。
 @@ -138,9 +137,9 @@ group: 以上是 Umi 4 目前的新功能。 -除此之外，还有一些计划在正式版发布之前做的事情。包括 api route、umi server and adapter、route loader、稳定的 lint、更多命令、组件研发 father 4、文档工具 dumi 2 等，会在之后的 RC 版本中与大家见面。 +除此之外，还有一些计划在正式版发布之前做的事情。包括 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 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。 +欢迎大家尝鲜 Umi 4，官方文档有准备 ant-design-pro 从 Umi 3 到 4 的升级文档。同时 RC 阶段，还准备了一个手把手升级的微信交流群，欢迎 Umi 4 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。
) {
+ const hash = createHash('md5');
+ hash.update(JSON.stringify(env));
+ const result = hash.digest('hex');
+ return result;
+}
+```
+
+请格外注意：
+
+1. 你的项目有哪些文件、依赖会影响项目，配置他们作为依赖，变更时可以使得缓存失效。
+
+2. 因为 `process.env` 包括了所有的 nodejs 环境变量，这非常多，如果环境变量在 CI 中每次构建都存在差异，请挑选所需的环境变量，或者排除掉会变化的。
+
+ ```ts
+ // 如挑选可能会影响项目内容的环境变量
+ createEnvironmentHash({
+ NODE_ENV: process.env.NODE_ENV,
+ // ...
+ });
+ ```
+
+### Monorepo 中的项目
+
+在 monorepo 中，如何缓存需要前置构建的其他子包，比如构建 `apps/project-umi` 需要先构建好他依赖的子包 `libs/component` ，但是下次 `libs/component` 没有代码改动，如何跳过这部分前置依赖的构建？
+
+此时推荐你使用 [Turborepo](https://turbo.build/repo) 来做 monorepo 构建方案，具体使用方法请参见 [官方文档](https://turbo.build/repo/docs) 和 [examples](https://github.com/vercel/turbo/tree/main/examples) 。
+
+注：如果在 CI 中构建，同样需要容器支持恢复上次的 turbo 缓存，可以通过 [`--cache-dir`](https://turbo.build/repo/docs/reference/command-line-reference#--cache-dir) 选项更改缓存位置。
diff --git a/docs/docs/docs/api/api.en-US.md b/docs/docs/docs/api/api.en-US.md
new file mode 100644
index 000000000000..5c7432892927
--- /dev/null
+++ b/docs/docs/docs/api/api.en-US.md
@@ -0,0 +1,741 @@
+---
+order: 1
+toc: content
+translated_at: '2024-03-17T10:47:17.550Z'
+---
+
+# API
+
+For ease of search, the following content is sorted alphabetically.
+
+## umi
+
+### createBrowserHistory
+
+Creates a `BrowserHistory` that uses the browser's built-in `history` to track application navigation. It is recommended for use in modern web browsers that support the HTML5 `history` API.
+
+Type definition is as follows:
+```ts
+function createBrowserHistory(options?: { window?: Window }) => BrowserHistory;
+```
+
+Usage example:
+```ts
+// create a BrowserHistory
+import { createBrowserHistory } from 'umi';
+const history = createBrowserHistory();
+// or a iframe BrowserHistory
+import { createBrowserHistory } from 'umi';
+const history = createBrowserHistory({
+ window: iframe.contentWindow,
+});
+```
+### createHashHistory
+
+`createHashHistory` returns a `HashHistory` instance. The default `window` is the current document's `defaultView`.
+
+The main difference between `HashHistory` and `BrowserHistory` is that `HashHistory` stores the current location in the hash part of the URL, which means it does not send a request to the server when switching routes. If you are hosting your site on a server that you cannot fully control, or in a single-page Electron application, `HashHistory` is recommended.
+
+Usage example:
+```ts
+// create a HashHistory
+import { createHashHistory } from 'umi';
+const history = createHashHistory();
+```
+
+### createMemoryHistory
+
+`MemoryHistory` is not operated or read from the address bar. It is also very suitable for testing and other rendering environments.
+
+```ts
+const history = createMemoryHistory(location)
+```
+
+### createSearchParams
+
+A utility function that wraps `new URLSearchParams(init)`, supports creating with arrays and objects
+
+```ts
+import { createSearchParams } from 'umi';
+
+
+// Assuming the path http://a.com?foo=1&bar=2
+createSearchParams(location.search);
+createSearchParams("foo=1&bar=2");
+createSearchParams("?foo=1&bar=2");
+
+// Key-value pair object
+createSearchParams({ foo: 'bar', qux: 'qoo'}).toString()
+// foo=bar&qux=qoo
+
+// Key-value tuple array
+createSearchParams([["foo", "1"], ["bar", "2"]]).toString()
+// foo=1&bar=2
+```
+
+[URLSearchParams documentation](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams)
+
+### generatePath
+
+Generates the actual route to be accessed using the given path with parameters and the corresponding params.
+
+```ts
+import { generatePath } from 'umi';
+
+generatePath("/users/:id", { id: "42" }); // "/users/42"
+generatePath("/files/:type/*", {
+ type: "img",
+ "*": "cat.jpg",
+}); // "/files/img/cat.jpg"
+```
+
+### Helmet
+
+The Helmet component provided by [react-helmet-async](https://github.com/staylor/react-helmet-async), used to dynamically configure tags in the `head` of the page, such as the `title`.
+
+> Note: To ensure Helmet still works during SSR, be sure to use the Helmet provided by Umi instead of installing react-helmet separately
+
+```tsx
+import { Helmet } from 'umi';
+
+export default function Page() {
+ return (
+
+ { location.pathname }
+ { location.search }
+ { location.hash }
+
+ );
+}
+```
+
+To get the current route information outside of React components and Hooks.
+
+```ts
+// location object, contains pathname, search, and hash
+window.location.pathname;
+window.location.search;
+window.location.hash;
+```
+
+Imperative route navigation.
+
+```ts
+import { history } from 'umi';
+
+// Jump to a specific route
+history.push('/list');
+
+// Jump to a specific route with parameters
+history.push('/list?a=b&c=d#anchor', state);
+history.push({
+ pathname: '/list',
+ search: '?a=b&c=d',
+ hash: 'anchor',
+ },
+ {
+ some: 'state-data',
+ }
+);
+
+// Jump to the current path and refresh state
+history.push({}, state)
+
+// Jump back to the previous route
+history.back();
+history.go(-1);
+```
+
+:::info{title=🚨}
+Note: `history.push` and `history.replace` require using `state` as the second parameter passed to these two APIs
+:::
+
+
+Route listening.
+
+```ts
+import { history } from 'umi';
+
+const unlisten = history.listen(({ location, action }) => {
+ console.log(location.pathname);
+});
+unlisten();
+```
+
+### Link
+
+`` is a React component, an `` element with routing jump functionality.
+
+Type definition is as follows:
+
+```ts
+declare function Link(props: {
+ prefetch?: boolean;
+ to: string | Partial<{ pathname: string; search: string; hash: string }>;
+ replace?: boolean;
+ state?: any;
+ reloadDocument?: boolean;
+}): React.ReactElement;
+```
+
+Example:
+
+```tsx
+import { Link } from 'umi';
+
+function IndexPage({ user }) {
+ return {user.name};
+}
+```
+
+`` supports relative path navigation; `` does not do routing navigation and is equivalent to the jump behavior of ``.
+
+If `prefetch` is enabled, then when the user hovers over the component, Umi will automatically start preloading the component js files and data for the routing jump.
+
+### matchPath
+
+`matchPath` can match a given path with a known route format and return the match result.
+
+Type definition is as follows:
+
+```ts
+declare function matchPath-
+
isActive ? { color: 'red' } : undefined}>Messages
+ isActive ? 'active' : undefined}>Tasks
+ {({ isActive }) => Blog}
+
+
+ );
+}
+
+function DashboardWithContext() {
+ return (
+ Dashboard
+
+
+ );
+}
+```
+
+The `context` of the `Outlet` component can be retrieved in the child component using the API `useOutletContext`.
+
+### resolvePath
+
+Used to resolve front-end routing jump paths on the client side.
+
+Type definition is as follows:
+
+```ts
+declare function resolvePath(
+ to: PartialDashboard
+
+ {outlet}
+
+}
+```
+
+### useOutletContext
+
+`useOutletContext` is used to return the `context` mounted on the `Outlet` component.
+
+Type definition is as follows:
+```ts
+declare function useOutletContext
+
+}
+
+const SomeRouteComponentUnderLayout = () => {
+ const layoutContext = useOutletContext();
+
+ return JSON.stringify(layoutContext) // {"prop":"from Layout"}
+}
+```
+
+### useParams
+
+The `useParams` hook function returns a read-only key-value pair object of dynamic route matching parameters; child routes will inherit dynamic parameters from parent routes.
+
+Type definition is as follows:
+```ts
+declare function useParams<
+ K extends string = string
+>(): Readonly1 :
+ }
+
+ if (
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..279d7db56cd0
--- /dev/null
+++ b/docs/docs/docs/api/commands.en-US.md
@@ -0,0 +1,308 @@
+---
+order: 4
+toc: content
+translated_at: '2024-03-17T10:43:51.227Z'
+---
+
+# Command Line
+
+umi offers many built-in command line interfaces to start and build projects, as well as some auxiliary development commands, such as generators.
+
+To get a list of available commands, you can run the help command in the project directory:
+
+```bash
+umi help
+```
+
+You should see logs similar to the following:
+
+```bash
+Usage: umi {data}
;
+}
+
+export async function clientLoader() {
+ const data = await fetch('/api/data');
+ return data;
+}
+```
+
+## codeSplitting
+
+- Type: `{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }`
+- Default value: `null`
+
+Provide code splitting strategy solutions.
+
+bigVendors is the big vendors scheme, which packs the files under node_modules in the async chunk together, which can avoid repetition. At the same time, the disadvantages are, 1) the size of a single file is too large, 2) there is no caching efficiency to speak of.
+
+depPerChunk is similar to bigVendors, but different in that dependencies are split by package name + version, solving bigVendors’ issues with size and caching efficiency. However, it also brings potential problems, possibly leading to more requests. My understanding is that for non-large projects it’s actually fine because, 1) a single page's requests will not include a very large number of dependencies, 2) based on HTTP/2, dozens of requests are not a problem. But, for large or huge projects, a more suitable solution is needed.
+
+granularChunks take a middle value between bigVendors and depPerChunk, while also having better utilization of caching efficiency. Unless there are special circumstances, the granularChunks strategy is recommended.
+
+## conventionLayout
+
+- Type: `boolean`
+- Default value: `undefined`
+
+`src/layouts/index.[tsx|vue|jsx|js]` is conventionally set as layout, enabled by default. It can be disabled by setting `conventionLayout: false`.
+
+## conventionRoutes
+
+- Type: `{ base: string; exclude: RegExp[] }`
+- Default value: `null`
+
+Modify the default convention-based route rules, only valid when using umi's convention-based routing. Convention-based routing, also known as file-based routing, means that you don’t need to write configurations manually, as the file system is the routes, and the routing configuration is analyzed through directories and files and their naming.
+
+When using convention-based routing, it's conventioned that all `(j|t)sx?` files under `src/pages` are routes.
+
+> You can see more details in [Convention-based Routing](../guides/routes#conventional-routing).
+
+### base
+
+`base` is used to set the base path for the routes by convention, by default reading from `src/pages`. If it is a site for documentation, you might need to change it to `./docs`;
+
+### exclude
+
+You can use `exclude` to filter some files that are not needed, such as you can use it to exclude files under components, models, etc.
+
+Example,
+
+```js
+// Do not recognize files under components and models directories as routes
+conventionRoutes: {
+ exclude: [/\/components\//, /\/models\//],
+}
+```
+
+## copy
+
+- Type: `Array
+
+If you don't know what you can contribute, you can search TODO or FIXME in the source code.
diff --git a/docs/docs/docs/introduce/contributing.md b/docs/docs/docs/introduce/contributing.md
index eb8c87ab4377..164c7f602fe5 100644
--- a/docs/docs/docs/introduce/contributing.md
+++ b/docs/docs/docs/introduce/contributing.md
@@ -11,7 +11,7 @@ toc: content
### Node.js 和 pnpm
-开发 Umi 需要 Node.js 16+ 和 `pnpm` v8。
+开发 Umi 需要 Node.js 18+ 和 `pnpm` v8。
推荐使用 [`nvm`](https://github.com/nvm-sh/nvm) 管理 Node.js，避免权限问题的同时，还能够随时切换当前使用的 Node.js 的版本。在 Windows 系统下的开发者可以使用 [`nvm-windows`](https://github.com/coreybutler/nvm-windows)。
@@ -76,7 +76,7 @@ Time: 13.658 s
Ran all test suites.
```
-如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 只开了 turborepo 功能的。
+如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 是开了 turborepo 功能的。
比如，
@@ -180,6 +180,14 @@ $ pnpm build:deps --dep webpack-manifest-plugin
$ pnpm release
```
+## 通过 dist-tag 回滚
+
+比如要回滚到 4.0.81 。
+
+```bash
+$ pnpm -rc --filter "./packages/**" exec pnpm dist-tag add \$PNPM_PACKAGE_NAME@4.0.81 latest
+```
+
## 加入 Contributor 群
提交过 Bugfix 或 Feature 类 PR 的同学，如果有兴趣一起参与维护 Umi，可先用钉钉扫下方二维码（注明 github id）加我钉钉，然后我会拉到群里。
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..67ddc5e83423
--- /dev/null
+++ b/docs/docs/docs/introduce/faq.en-US.md
@@ -0,0 +1,207 @@
+---
+order: 5
+toc: content
+translated_at: '2024-03-17T09:54:04.320Z'
+---
+
+# FAQ
+
+## Can I disable dynamicImport?
+
+Yes, but it is not recommended to do so.
+
+1. Install dependencies
+
+```bash
+ pnpm i babel-plugin-dynamic-import-node -D
+```
+
+2. Add `extraBabelPlugins` to the configuration, but only enable it for production
+
+```ts
+// .umirc.ts
+export default {
+ extraBabelPlugins: process.env.NODE_ENV === 'production'
+ ? ['babel-plugin-dynamic-import-node']
+ : []
+}
+```
+
+## How to configure loading for dynamicImport when it's not present?
+
+Define `src/loading.tsx`:
+
+See [Directory Structure > loading.tsx](../guides/directory-structure#loadingtsxjsx)
+
+## Can I use React 17?
+
+Since Umi v4 has upgraded the default version of React to v18, be aware of compatibility between dependency libraries and React 18 when using Umi4. If you still need to use React 17, run the following commands and restart.
+
+```bash
+ pnpm add react@^17 react-dom@^17
+```
+
+## Constantly restarting and refreshing the page after proxying static resources locally
+
+
+
+Solution: Configure `SOCKET_SERVER=127.0.0.1:${port}` to start the project
+
+```bash
+ SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
+```
+
+## Error evaluating function `round`: argument must be a number
+
+
+
+Solution: In the new version of less, `/` is recognized as property shorthand by default. To restore the old behavior (where `/` was used as a calculation symbol by default), configure `lessLoader: { math: 'always' }`.
+
+## The layout configuration option in routes does not take effect
+
+The layout configuration has been moved to `app.ts`, see [Runtime Config > layout](https://umijs.org/docs/api/runtime-config#layout)
+
+## Where did document.ejs go and how do I customize the HTML template
+
+In addition to the injection through the configuration of external [script](https://umijs.org/docs/api/config#scripts), [css](https://umijs.org/docs/api/config#styles), you can also use the project-level plugin to more flexibly modify HTML products, see: [issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
+
+## Why are external js files configured in scripts by default inserted after umi.js
+
+React only starts running after the page has fully loaded, so inserting after `umi.js` will not affect the project.
+
+If you need to insert it before `umi.js`, see [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
+
+## How do I code split with Umi4?
+
+Umi 4 splits code by page by default. If you feel the need for further optimization, you can use sub-package strategies or manual splitting, see: [Code Splitting Guide](../../blog/code-splitting)
+
+If you have the requirement to pack all js products into a single `umi.js` file, please disable [dynamicImport](#can-i-disable-dynamicimport).
+
+## Where did _layout.tsx go and how do I nest routes?
+
+Umi 4 uses react-router v6, and nested route content is displayed through `+
+
+## What is Umi?
+
+Umi, pronounced as "Wu Mi" in Chinese, is an extensible enterprise-level front-end application framework. Umi is based on routing, supporting both configuration-based routing and convention-based routing, ensuring the completeness of routing features and further extending functionalities based on this. Accompanied by a plugin system with a complete lifecycle, it covers every lifecycle from the source code to the build product, supporting various functional extensions and business needs.
+
+Umi is the underlying front-end framework of Ant Group, serving directly or indirectly over 10,000 applications, including Java, Node, H5 Wireless, Hybrid applications, pure front-end assets applications, CMS applications, Electron applications, Serverless applications, and more. It has served our internal users well and many external users, including Taobao system, Feizhu, Alibaba Cloud, ByteDance, Tencent, Koubei, Meituan, etc. In ByteDance's [research report](https://zhuanlan.zhihu.com/p/403206195) in 2021, Umi was the choice of 25.33% of developers.
+
+Umi has many interesting features, such as:
+
+1. **Enterprise-level**, considering more in terms of security, stability, best practices, and constraint ability+2. **Plugin-based**, everything can be modified, and Umi itself is also composed of plugins
+3. **MFSU**, a Webpack packaging solution faster than Vite
+4. Complete routing based on React Router 6
+5. The fastest request by default
+6. SSR & SSG
+7. Stable white-box performance with ESLint and Jest
+8. Framework-level integration of React 18
+9. Best practices for Monorepo
+... + +## When Not to Use Umi? + +If your project, + +1. Needs to support IE 8 or lower browsers
+2. Needs to support React versions below 16.8.0
+3. Needs to run in environments below Node 14
+4. Has strong webpack customization needs and subjective willingness
+5. Needs to choose different routing solutions
+... + +Umi might not be suitable for you. + + +## Why Not? + +### create-react-app + +create-react-app is a scaffolding tool and not the same type as meta frameworks like Umi, next.js, remix, ice, modern.js, etc. Scaffolding can quickly start a project, which is sufficient for individual projects, but not enough for teams. Because using scaffolding is like spilt water; once it starts, it cannot iterate. Meanwhile, the encapsulation and abstraction that scaffolding can do are very limited. + +### next.js + +If SSR is needed, next.js is a very good choice (of course, Umi also supports SSR); but if only CSR is needed, Umi would be a better choice. By comparison, Umi has better extensibility; and Umi offers many more down-to-earth features, such as configuration-based routing, patch scheme, integration of antd, micro frontends, internationalization, permissions, etc.; at the same time, Umi is more stable, because it locks all dependencies that can be locked and proactively updates regularly. A certain subversion of Umi will not fail to run due to reinstallation of dependencies. + +### remix + +Remix is a framework I really like, and Umi 4 has
+
++ +Technological convergence is particularly important for teams, encompassing two meanings: 1) convergence of technology stacks and 2) convergence of dependencies. Convergence of technology stacks refers to the plethora of technology stacks available in the community, with numerous choices for each technical direction, such as data flows which alone could number over 100, and how developers should make their choice; After converging the technology stack, it's also necessary to converge dependencies, as the projects of developers within a team should not have many fragmented dependencies, each of which comes with an upgrading cost. + +We hope that once developers depend on Umi, they no longer need to worry about dependencies like babel, webpack, postcss, react, react-router, etc., and by depending on @umijs/max, they need not be concerned with dependencies and technology stacks of developing mid-end projects. + +## Plugins and Plugin Collections + +
+
++ +Umi satisfies different scenarios and business needs through the mechanism of plugins and plugin collections. A plugin is to extend a function, whereas a plugin collection is to extend a category of business. For example, to support vue, we could have `@umijs/preset-vue`, including build and runtime related to vue; to support the H5 application type, there could be `@umijs/preset-h5`, aggregating H5 related functionalities together. + +As an analogy, plugin collections are similar to babel's presets and eslint's configs. + +## Best Practices + +Best practice is what we believe to be the best way to do something at the moment. The subject is us, so it could be relatively subjective. For instance, in aspects like routing, patch solutions, data flow, requests, permissions, internationalization, micro-frontends, icons usage, editor usage, charts, forms, etc., Umi will offer our best practices. Most of these practices come from internal practices and discussions at Ant Group, with some from the community. They are subjective and time-sensitive, so there might be relatively frequent iterations. + +The need for best practices arises, 1) because there are too many solutions in the community to choose from, and 2) many people lack the energy, experience, or even willingness to make choices. Especially for non-professional front-end developers, having choices is better than having none, regardless of what those choices might be. + +## Enterprise-Level + +The npm community is "deteriorating" with political, malicious, advertisement, and job-seeking packages frequently appearing. Thus, how to ensure your project won’t “crash overnight” is an unavoidable issue for frameworks providing services to enterprises. + +Umi achieves this by locking down versions, prepacking dependencies, hacking eslint to lock eslint's dependencies, and using configuration to lock down babel patch dependencies, so that Umi won't crash after you reinstall node_modules, aiming to be "Still Usable in Ten Years". + +## import all from umi + +Many may be hearing about this for the first time. import all from umi means all imports come from `umi`. For instance, dva is not `import { connect } from 'dva'`, but `import { connect } from 'umi'`, exported from Umi. The methods exported not only come from Umi itself but also from Umi plugins. + +```ts +// A large number of plugins provide additional exports for umi +import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi'; +``` + +The advantage is that Umi manages a large number of dependencies so users don’t need to manually install them; at the same time, developers will also have fewer import statements in their code. diff --git a/docs/docs/docs/introduce/philosophy.md b/docs/docs/docs/introduce/philosophy.md index 32f39b67644f..0fc950eed242 100644 --- a/docs/docs/docs/introduce/philosophy.md +++ b/docs/docs/docs/introduce/philosophy.md @@ -54,7 +54,7 @@ Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依 ## import all from umi -很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 umi 中导出。导出的方法不仅来自 umi 自身，还来自 umi 插件。 +很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 Umi 中导出。导出的方法不仅来自 Umi 自身，还来自 Umi 插件。 这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。 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..21a6c645535d --- /dev/null +++ b/docs/docs/docs/introduce/upgrade-to-umi-4.en-US.md @@ -0,0 +1,305 @@ +--- +order: 4 +toc: content +translated_at: '2024-03-17T09:50:41.558Z' +--- + +# Upgrade to Umi 4 + +## Upgrade Steps + +Upgrading to Umi 4 can be completed in just a few easy steps, which can simply be described as - "Reinstall dependencies, modify configuration": + +1. **Dependency Handling** +2. **Start Command** +3. **Upgrading Non-Official Plugins** +4. **Configuration Layer Migration** +5. **Code Layer Modifications** + +### Dependency Handling + +Your project's `package.json` needs to upgrade Umi and replace the corresponding Umi plugins. + +If `umi@3` was developed using a combination of `umi` + `@umijs/preset-react`, then you can directly upgrade using the new `max`. + +```diff +{ + "devDependencies": { ++ "@umijs/max": "^4.0.0", +- "umi": "^3.0.0", +- "@umijs/preset-react": "^1.2.2" + } +} +``` + +Delete `node_module`, then execute `npm install` to reinstall dependencies. + +### Start Command + +If using `@umijs/max`, you can replace `umi` with the `max` command, such as `max dev`, `max build`, etc. + +`umi@4` moved some pre-project operations to the `setup` command, such as `umi g tmp` commands in umi@3, which need to be replaced with `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", + } +} +``` + +### Upgrading Non-Official Plugins + +For some non-Umi official Umi plugins used in the project, please contact the relevant authors to update them in a timely manner according to [plugin api changes](../api/plugin-api). + +When migrating the project, you can first turn off references to the corresponding plugin packages, such as temporarily commenting out the `plugins` in the configuration, and removing all dependencies starting with `umi-plugin-`, `@umijs/plugin-`, and `@umijs/preset-` in package.json. + +### Configuration Layer Migration + +**Configurations provided by max** are as follows in `config/config.ts`: + +> It’s worth noting that some rules that were conventionally enabled by plugins need to be explicitly configured in `umi@4`, as we want less 'black box' behavior in `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#configuration-at-build-time + 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, + }, +}); +``` + +**Configurations with differences** are as follows in `config/config.ts`: + +```typescript +import { defineConfig, utils } from 'umi'; + +export default defineConfig({ +- fastRefresh: {}, ++ fastRefresh: true, + dva: { + // The parameter hmr is no longer supported +- hmr: true, + }, +// Default webpack5 +- webpack5: {}, +}) +``` + +### Code Layer Modifications + +Umi 4 upgrades `react-router@5` to `react-router@6`, so there are some differences in the use of related api. + +Props are empty objects by default, the following properties cannot be taken directly from props  + +#### children + +```typescript +import { Outlet } from 'umi'; +
+- { props.children }
++
+ );
+}
+```
+
+Change the way that route components rendered with `React.cloneElement`, for example:
+
+```diff
+import React from 'react';
++ import { Outlet } from 'umi';
+
+export default function RouteComponent(props) {
+ return (
+
+- { React.cloneElement(props.children, { someProp: 'p1' }) }
++
+ );
+}
+```
+
+Change components to get values from `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
+
+> It’s recommended to use useLocation in components or hooks, and window.location elsewhere.
+
+```diff
+export default function Page(props) {
++ const { location } = window;
+ return (
+
+- { props.location }
++ { location }
+
+ );
+}
+```
+
+Or
+
+```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 }
+
+ );
+}
+```
+
+In the use of class component components:
+
+```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}
+
+ )
+ }
+}
+```
+For more `Umi` related [api](https://umijs.org/docs/api/api)
+
+Pay attention to the difference in match data:
+
+```
+// 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'}
+```
+
+For more changes and API updates, please refer to [react-router@6](https://reactrouter.com/docs/en/v6/api#uselocation)
+
+After completing the above operations, execute `max dev`, and visit [http://localhost:8000](http://localhost:8000), please verify all functions meet expectations.
+
+If your project cannot start normally, you may need to do the following:
+
+## Configuration Changes
+
+TODO
+
+## FAQ
+
+### Can't find query in location?
+
+Query in location is no longer supported, later it’s recommended to use [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);
+```
+
+### Can't find *.d file, or its reference
+
+In `umi@3`, importing would automatically find the corresponding `.d.ts` file, such as:
+
+`import { ButtonType } from './button';`
+
+If there is a `.button.d.ts` file, it will correctly execute in `umi@3`, but it will cause an error in umi@4, you may need more standardized type references.
+
+```diff
+- import { ButtonType } from './button';
++ import type { ButtonType } from './button.d';
+```
diff --git a/docs/docs/docs/introduce/upgrade-to-umi-4.md b/docs/docs/docs/introduce/upgrade-to-umi-4.md
index 2680d91e93fb..77112efa8aed 100644
--- a/docs/docs/docs/introduce/upgrade-to-umi-4.md
+++ b/docs/docs/docs/introduce/upgrade-to-umi-4.md
@@ -34,7 +34,7 @@ toc: content
### 启动命令
-如果使用了 `@umijs/max` 可以使用 `max` 命令来替换 `umi`，`max dev`，`max build` 等
+如果使用了 `@umijs/max` 可以使用 `max` 命令来替换 `umi`，`max dev`，`max build` 等。
`umi@4` 将一些项目前置操作放到了 `setup` 命令中，如 umi@3 中的 `umi g tmp` 等命令，需要使用 `umi setup` 替换
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..3b5a950219e1
--- /dev/null
+++ b/docs/docs/docs/max/access.en-US.md
@@ -0,0 +1,168 @@
+---
+order: 7
+toc: content
+translated_at: '2024-03-17T09:49:43.250Z'
+---
+
+# Permissions
+
+## How to Enable
+
+Configuring activation. Requires `src/access.ts` to provide permission configuration.
+
+```ts
+export default {
+ access: {},
+ // access plugin depends on the initial State so it needs to be enabled at the same time
+ initialState: {},
+};
+```
+
+## Introduction
+
+We have agreed that `src/access.ts` is our permission definition file, which needs to export a function by default. The method will be executed when the project is initialized. This method needs to return an object, where each value of the object corresponds to a defined permission. As shown below:
+
+```js
+// src/access.ts
+export default function (initialState) {
+ const { userId, role } = initialState;
+
+ return {
+ canReadFoo: true,
+ canUpdateFoo: role === 'admin',
+ canDeleteFoo: (foo) => {
+ return foo.ownerId === userId;
+ },
+ };
+}
+```
+
+Where `initialState` is the data provided by the initialization state plugin `initial-state`, you can use this data to initialize your user permissions.
+
+## Configuration
+
+### Extended Routing Configuration
+
+With the [layout](./layout-menu) plugin, you can easily implement permission control for some pages. As shown below, users can access the page only if they have the canReadPageA permission (defined in `src/access.ts`). Otherwise, it will render the default permission error page built into the Layout plugin by default.
+
+```ts
+export const routes = [
+ {
+ path: '/pageA',
+ component: 'PageA',
+ access: 'canReadPageA', // Some key of the permission definition return value
+ },
+];
+```
+
+### Custom Permission Page Configuration
+
+As mentioned above, to configure a custom permission page, you need to define it in `src/app.tsx`.
+
+```tsx
+export const layout: RunTimeLayoutConfig = () => {
+ return {
+ // Customize the 403 page
+ unAccessible: 'unAccessible'
,
+ // Customize the 404 page
+ noFound: 'noFound'
,
+ };
+};
+```
+
+#### access
+
+- Type: `string`
+
+The corresponding permission name.
+
+## API
+
+### useAccess
+
+We provide a hook for obtaining permission-related information in components, as shown below:
+
+```js
+import React from 'react';
+import { useAccess } from 'umi';
+
+const PageA = (props) => {
+ const { foo } = props;
+ the access = useAccess();
+
+ if (access.canReadFoo) {
+ // If can read Foo, then...
+ }
+
+ return <>TODO;
+};
+
+export default PageA;
+```
+
+Combined with the `Access` component, it's easy to control the permissions of elements within pages.
+
+### Access
+
+You can use the `useAccess` hook and the `
+ Can not read foo content.
}
+ >
+ Foo content.
+
+ with antd@{version}
+with antd@{version}
+{user.username}
}
+ );
+}
+```
+
+The `useModel()` method's argument is the Model's **namespace**.
+
+:::info{title=💡}
+If you use VSCode as the IDE for developing Umi projects, it's recommended to use it in conjunction with the [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model) plugin. It allows you to quickly jump to the file that defines the Model:
+
+
+:::
+
+## Performance Optimization
+
+The `useModel()` method can accept an optional second parameter. When a component only needs to use part of the Model and is not interested in changes to other parameters, you can pass in a function to filter. Take the operation button for the counter as an example:
+
+```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 (
+
+
+
+
+ );
+};
+```
+
+The above component is not interested in the `counter` value in the counter Model, and only needs to use the `increment()` and `decrement()` methods provided by the Model. Therefore, we passed in a function as the second argument for the `useModel()` method, and its return value will be used as the return value of the `useModel()` method.
+
+This way, we have filtered out the frequently changing `counter` value, avoiding the performance loss caused by the component's repetitive rendering.
+
+## Global Initial State
+
+`@umi/max` has a built-in **global initial state management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts), which allows you to quickly build and access the global initial state of Umi projects within components.
+
+The global initial state is a special Model.
+
+The global initial state is created at the very beginning of the entire Umi project. Write the export method `getInitialState()` in `src/app.ts`, and its return value will become the global initial state. For example:
+
+```ts
+// src/app.ts
+import { fetchInitialData } from '@/services/initial';
+
+export async function getInitialState() {
+ const initialData = await fetchInitialData();
+ return initialData;
+}
+```
+
+Now, various plugins and your defined components can directly access this global initial state through `useModel('@@initialState')` as shown below:
+
+```tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { initialState, loading, error, refresh, setInitialState } =
+ useModel('@@initialState');
+ return <>{initialState};
+};
+```
+
+| Object Property | Type | Description |
+| --- | --- | --- |
+| `initialState` | `any` | The return value of the exported `getInitialState()` method |
+| `loading` | `boolean` | Whether the `getInitialState()` or `refresh()` method is in progress. Before the initial state is obtained for the first time, the rendering of other parts of the page will be **blocked** |
+| `error` | `Error` | If an error occurs while running the exported `getInitialState()` method, the error message |
+| `refresh` | `() => void` | Re-execute the `getInitialState` method and obtain a new global initial state |
+| `setInitialState` | `(state: any) => void` | Manually set the value of `initialState`, after manually setting it, `loading` will be set to `false` |
+
+## Qiankun Parent-Child Communication
+
+`@umi/max` has a built-in **Qiankun Micro-Frontend** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts), which allows micro-applications to obtain the data Model passed from the parent application through the `useModel('@@qiankunStateFromMaster')` method, thereby achieving communication between parent and child applications.
+
+For specific usage, please refer to the [micro-frontend's parent-child communication chapter](./micro-frontend#parent-child-communication).
+
+## API
+
+### `useModel`
+
+`useModel()` is a hook function that provides the ability to use a Model. It accepts two parameters:
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `namespace` | `String` | The namespace of the Model file |
+| `updater` | `(model: any) => any` | Optional parameter. Passing in a function, the return value of which is the Model state or data currently needed by the component, and it serves as the return value of the `useModel()` method. It plays a significant role in optimizing component performance. |
+
+```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..1504bc32848b
--- /dev/null
+++ b/docs/docs/docs/max/dva.en-US.md
@@ -0,0 +1,343 @@
+---
+order: 13
+toc: content
+translated_at: '2024-03-17T09:17:48.666Z'
+---
+
+# dva
+
+## Why We Need State Management
+
+React components are essentially built through JSX and styles according to the state to form the final UI. It is the change in state that actually dynamizes the page. For simple frontend applications, the application data management needs can be met by the component's own state plus the parent component passing state via props. However, when the application scales to a certain degree, it will lead to very complex states maintained within components. Coupled with the state transfer between components, data management can easily become chaotic. A minor modification can lead to unpredictable side effects.
+
+Therefore, we need pure UI components that, apart from rendering logic, do not mix other logics (such as network requests). This requires us to find a way to extract business logic unrelated to rendering, forming an independent layer (which is managed by the model in the `src/models` folder in Umi) to manage. All components are downgraded to `stateless components` that solely depend on props for rendering. In this way, the UI layer no longer needs to worry about rendering unrelated logics and focuses on UI rendering. (Note: The components mentioned here mainly refer to the page components under page, whereas the components under component should be relatively universal components that should also rely solely on props for rendering, and they should not have a model. Data should be passed to them via props in the page components).
+
+## Simple Data Sharing
+
+For simple applications that do not require complex data flows, only some simple data sharing is needed. We recommend using [Middle Platform Best Practices Simple Data Flow](./data-flow).
+
+## How Umi Manages State
+
+As shown in the figure below, Umi has built in [Dva](https://dvajs.com) to provide a set of state management solutions:
+
+
+
+Data is uniformly managed in the models of `src/models`, components strive not to maintain data as much as possible, but to associate with the data in the model through connect. When there is an operation on the page, an action is triggered to request the backend interface and modify the data in the model, separating the business logic into a cyclic closed loop, allowing the data to flow unidirectionally within it, making the application easier to maintain. This idea originally came from Facebook's [flux](http://facebook.github.io/flux/). Let's take a closer look at how to implement such logic in Umi.
+
+### Configuring dva
+
+First, you need to configure `dva: {}` to activate the dva plugin built into Umi.
+
+### Adding a model
+
+Umi will automatically mount the model definition in `src/models` by default, you just need to create a new file in the model folder to add a model to manage component states.
+
+After 2.0, to better support the demand loading of mobile H5 projects and the organization of models in large projects, we will also default mount the model under a certain page folder, you can refer to [Directory Structure Explanation](../guides/directory-structure) for specific structure. However, it is worth noting that the namespace of the model is global, and you still need to ensure your namespace is unique (the default is the file name). For most projects, we recommend managing them uniformly in the model, without using this function.
+
+The model writing refers to the following example:
+
+```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;
+ },
+};
+```
+
+### Connecting the Component and Model
+
+After creating the model, you can conveniently connect the model and component together in the component through the ES6 [Decorator](http://es6.ruanyifeng.com/#docs/decorator). Then you can access the data in the model through `this.props.[modelName]` in the component. (In the corresponding model, the default namespace is the file name)
+
+Component example is as follows:
+
+```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;
+```
+
+### Dispatching Events in Components
+
+The connect method also adds `dispatch` to `this.props`, and you can call it to trigger the effects or reducer in the model to modify the data in the model when the user triggers a certain event. As shown below:
+
+```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;
+```
+
+### Modifying Data
+
+After dispatching an action, it will find an effect or reducer defined in the model according to the type in the action.
+
+If it's an effect, it can request back-end data, and then trigger a reducer to modify the data. After the data is modified by the reducer, the component will update according to the latest data, thus completing a data flow.
+
+## Documentation
+
+### Model Definition
+
+A model can define the following parts:
+
+- namespace # The namespace of the model, uniquely identifying a model, can be omitted if it is the same as the file name
+- state # Data in the model
+- effects # Asynchronous actions, used to send asynchronous requests
+- reducers # Synchronous actions, used to modify state
+
+### Connect
+
+`Connect` is used to associate a model and a component, adding related data and `dispatch` to the component's `props`. As shown below:
+
+```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;
+```
+
+It is recommended to call connect through annotation, which is equivalent to `export default connect(mapModelToProps)(UserInfo);`. Connect accepts a parameter, a method, where you receive all the model information and need to return the object to be added to props. In the example above, you can get the string 'hello world' through `this.props.test`.
+
+### Dispatch
+
+At the same time as using `connect` to associate the component and the model, the framework will also add a `this.props.dispatch` method. With this method, you can trigger an action to the model. As shown below:
+
+```jsx
+render () {
+ return {
+ this.props.dispacth({
+ type: 'modelnamespace/actionname',
+ sometestdata: 'xxx',
+ othertestata: {},
+ }).then(() => {
+ // it will return a promise
+ // action success
+ });
+ }}>test
+}
+```
+
+The actions triggered by `this.props.dispatch` are divided into two categories: effect and reducer. Below are more details on them.
+
+### Reducer
+
+Reducer is a function that handles the logic of modifying data (synchronously, cannot request back-end). It accepts state and action, returning the old or new state. That is: `(state, action) => state`.
+
+#### Add, Delete, Modify
+
+Taking todos as an example.
+
+```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;
+ }
+ });
+ },
+ },
+};
+```
+
+#### Add, Delete, Modify Nested Data
+
+It is recommended to keep at most one layer of nesting to maintain state flatness. Deep nesting makes reducer hard to write and maintain.
+
+```javascript
+app.model({
+ namespace: 'app',
+ state: {
+ todos: [],
+ loading: false,
+ },
+ reducers: {
+ add(state, { payload: todo }) {
+ const todos = state.todos.concat(todo);
+ return { ...state, todos };
+ },
+ },
+});
+```
+
+Below is an example of deep nesting, which should be avoided as much as possible.
+
+```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 are defined in the model. It is also a type of action, mainly used for asynchronous communication with the back-end. After requesting and receiving the necessary data from the back-end through effects, you can again send a reducer through the put method to modify the data.
+
+Effect supports asynchronous request through ES6 [Generator function](http://es6.ruanyifeng.com/#docs/generator), see the example below:
+
+```javascript
+export default {
+ namespace: 'todos',
+ effects: {
+ *addRemote({ payload: todo }, { put, call }) {
+ yield call(addTodo, todo);
+ yield put({ type: 'add', payload: todo });
+ },
+ },
+};
+```
+
+Actions defined in effects must be Generator functions defined through `*`, and asynchronous logic is triggered through the keyword `yield` in the function.
+
+#### Effects
+
+##### put
+
+Used to trigger an action.
+
+```javascript
+yield put({ type: 'todos/add', payload: 'Learn Dva' });
+```
+
+##### call
+
+Used to call asynchronous logic, supporting promise.
+
+```javascript
+const result = yield call(fetch, '/todos');
+```
+
+##### select
+
+Used to get data from state.
+
+```javascript
+const todos = yield select(state => state.todos);
+```
+
+### loading
+
+The framework will by default add a model with the namespace loading, containing information related to loading of asynchronous effects in this model, its state format is as follows:
+
+```js
+{
+ global: Boolean, // Whether there is really asynchronous request being sent
+ models: {
+ [modelnamespace]: Boolean, // The loading situation for each specific model
+ },
+ effects: {
+ [modelnamespace/effectname]: Boolean, // The loading situation for each specific effect
+ },
+}
+```
+
+You can use this model to implement loading animations in components.
+
+## Debugging
+
+### redux
+
+Since the underlying layer of dva is based on redux, you can install redux's [development tools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=zh-CN) to view the data and change records in the model.
+
+
+
+## References
+
+- [dva official website](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..979082ac6a6c
--- /dev/null
+++ b/docs/docs/docs/max/i18n.en-US.md
@@ -0,0 +1,529 @@
+---
+order: 8
+toc: content
+translated_at: '2024-03-17T09:15:38.373Z'
+---
+
+# Internationalization
+
+`@umi/max` comes with the [Internationalization plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts), which easily integrates internationalization features into your Umi application.
+
+## Getting Started
+
+The internationalization plugin adopts a convention-based directory structure, where we conventionally import multilingual files in the `src/locales` directory.
+
+The naming of multilingual files should follow this specification: `
+
+ );
+};
+```
+
+The rendered result is as follows:
+
+```html
+
+欢迎光临 Umi 的世界！
+
+
+Welcome to Umi's world!
+```
+
+## Using in Component Parameters
+
+In some cases, you need to pass multilingual content as a parameter to a certain component. This can be achieved through the `intl` object:
+
+```tsx
+import { Alert } from 'antd';
+import { useIntl } from 'umi';
+
+export default function Page() {
+ const intl = useIntl();
+ const msg = intl.formatMessage({
+ id: 'welcome',
+ });
+
+ return
+
{msg}
; +}; +``` + +Note that the key-value pair object used for assignment should be passed as the second parameter of the `formatMessage()` method. + +The rendered result is as follows: + +```html + +张三，今天也是美好的一天！
+ + +张三, what a nice day!
+``` + +## Switching Languages + +The preset `
+
+ );
+};
+```
+
+[Example code](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/safe-remote-component.tsx)
+
+### rawMfImport
+
+Loading remote modules, interface as follows.
+
+```ts
+rawMfImport(opts: {
+ entry: string;
+ remoteName: string;
+ moduleName: string;
+}): Promise{JSON.stringify(masterProps)}
;
+}
+```
+
+Or you can obtain and consume the data passed by the parent application through the higher-order method `connectMaster()`, as shown below:
+
+```tsx
+import { connectMaster } from 'umi';
+
+function MyPage(props) {
+ return {JSON.stringify(props)}
;
+}
+
+export default connectMaster(MyPage);
+```
+
+The child application can also obtain and consume the `props` properties in the lifecycle hooks [configured according to the requirements](#child-application-configures-lifecycle-hooks).
+
+Especially, when the parent application introduces the child application through the `{JSON.stringify(masterProps)}
;
-};
+}
```
或者可以通过高阶方法 `connectMaster()` 来获取并消费父应用透传的数据，如下所示：
@@ -509,14 +512,14 @@ import { MicroApp } from 'umi';
export default function Page() {
return 
+
如果通过路由的模式引入子应用，可以配置如下：
```ts
@@ -600,13 +616,32 @@ import { MicroApp } from 'umi';
export default function Page() {
return {error?.message}
;
+}
+```
+
+注意：`errorBoundary` 的优先级高于 `defaultErrorBoundary`。
+
## 环境变量
如果您有一些不能显式编写在 `.umirc.ts` 或 `src/app.ts` 中的配置信息，可以将它们存放在环境变量文件中。例如编写父应用的环境变量文件 `.env` 如下：
@@ -683,9 +742,10 @@ export default {
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `enable` | 否 | 启用 Qiankun 微应用插件，设置为 `false` 时为不启用 | `boolean` | `undefined` |
-| `loader` | 否 | 统一配置微应用加载动画的文件，设置文件路径即可 | `string` | - |
| `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` |
@@ -725,25 +785,28 @@ export default {
| `className` | 否 | 微应用的样式类 | `string` | `undefined` |
| `wrapperClassName` | 否 | 包裹微应用加载组件、错误捕获组件和微应用的样式类，仅在启用加载组件或错误捕获组件时有效 | `string` | `undefined` |
-
## FAQ
### 子应用的生命周期钩子加载了，但是页面没有渲染
+
如果页面没有报错，且通过查看 DOM 发现子应用的根节点已经有了，只是内容是空，这种基本可以确定是因为当前 url 没有匹配到子应用的任何路由导致的。
比如我们在主应用中配置了：
+
```js
{
path: '/app1',
microApp: 'app1',
}
```
+
子应用的路由配置是：
+
```js
{
path: '/user',
component: './User',
}
```
-那么我们必须通过 `/app1/user` 路径才能正常的访问到子应用的 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..591826297fe1
--- /dev/null
+++ b/docs/docs/docs/max/react-query.en-US.md
@@ -0,0 +1,93 @@
+---
+order: 11
+toc: content
+translated_at: '2024-03-17T08:46:49.932Z'
+---
+
+# react-query
+
+@umijs/max comes with the [react-query](https://tanstack.com/query/) request strategy (which is the same as @tanstack/react-query).
+
+## How to enable
+
+If using @umijs/max, enable by configuring.
+
+```ts
+export default {
+ reactQuery: {},
+}
+```
+
+If using umi, first install the `@umijs/plugins` dependency, then enable through configuration.
+
+```bash
+$ pnpm i @umijs/plugins -D
+```
+
+```ts
+export default {
+ plugins: ['@umijs/plugins/dist/react-query'],
+ reactQuery: {},
+}
+```
+
+## Features
+
+The plugin does a few things for you,
+
+1. Enable react query's devtool in dev mode, which can be disabled with `reactQuery: { devtool: false }`, and the option is configured in app.ts through `export const reactQuery = { devtool }`.
+
+2. Register a global QueryClient, which can be disabled with `reactQuery: { queryClient: false }`, and the option is configured in app.ts through `export const reactQuery = { queryClient }`.
+
+3. Most of react-query's exports can be imported and used from `umi` or `@umijs/max`.
+
+## Configuration
+
+The following configurations can be done in `reactQuery`.
+
+- `devtool`: boolean, whether to enable the official react query devtool, default `true`
+- `queryClient`: boolean, whether to register a global QueryClient and QueryClientProvider, default `true`
+
+For example:
+
+```ts
+export default {
+ reactQuery: {
+ devtool: false,
+ queryClient: false,
+ },
+}
+```
+
+Note: The above two configurations need to be configured in `app.ts` at runtime.
+
+## Runtime Configuration
+
+Includes the following configurations.
+
+- `devtool`: object
+- `queryClient`: object
+
+For example:
+
+```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/react-query.md b/docs/docs/docs/max/react-query.md
index 180ec5932bd1..29552d7f49f5 100644
--- a/docs/docs/docs/max/react-query.md
+++ b/docs/docs/docs/max/react-query.md
@@ -29,6 +29,14 @@ export default {
}
```
+:::info
+注：在使用时，请务必检查关于 `refetchOnWindowFocus` 的配置项，详见 [运行时配置项](#运行时配置项) 。
+:::
+
+## 版本
+
+默认使用的是 [TanStack Query](https://tanstack.com/query/latest) v4 版本，若需使用最新 v5 版本，手动安装 v5 版本的 `@tanstack/react-query` 与 `@tanstack/react-query-devtools` 依赖即可。
+
## 特性
插件帮你做了几件事，
@@ -44,7 +52,7 @@ export default {
可以在 `reactQuery` 中做以下配置。
- `devtool`: boolean，是否开启 react query 官方 devtool 工具，默认 `true`
-- `queryClient`: boolean, 是否注册全局的 QueryClient 和 QueryClientProvier，默认 `true`
+- `queryClient`: boolean, 是否注册全局的 QueryClient 和 QueryClientProvider，默认 `true`
比如：
@@ -66,27 +74,26 @@ export default {
- `devtool`：object
- `queryClient`: object
-比如：
+例子：
```ts
-const API_SERVER = '/path/to/api/server';
-export const reactQuery = {
+// src/app.ts
+
+import { RuntimeReactQueryType } from 'umi';
+
+export const reactQuery: RuntimeReactQueryType = {
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();
- }
- }
- }
+ defaultOptions: {
+ queries: {
+ // 🟡 此配置具有的表现往往令人出乎意料，若无特殊需求，请默认关闭
+ refetchOnWindowFocus: false,
+ },
+ },
},
};
```
+注：绝大多数项目中，**你都应该默认设定 `refetchOnWindowFocus: false`** ，否则将引发出人意料的反复获取数据效果（这在 SWR 中被称为 [`revalidateOnFocus`](https://swr.vercel.app/zh-CN/docs/api#options) ）。
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..1312e80d4481
--- /dev/null
+++ b/docs/docs/docs/max/request.en-US.md
@@ -0,0 +1,406 @@
+---
+order: 6
+toc: content
+translated_at: '2024-03-17T08:46:03.932Z'
+---
+
+# Request
+
+`@umijs/max` has built-in plugin solution. It offers a unified network request and error handling solution based on [axios](https://axios-http.com/) and ahooks' `useRequest` from [ahooks](https://ahooks-v2.surge.sh).
+
+```js
+import { request, useRequest } from 'umi';
+
+request;
+useRequest;
+```
+
+## Configuration
+### Build-time configuration
+```js
+export default {
+ request: {
+ dataField: 'data'
+ },
+};
+```
+
+Build-time configuration allows configuring `dataField` for useRequest, with its default being `data`. This setting primarily facilitates direct data consumption by useRequest. If you wish to access the raw data returned by the backend when consuming data, configure `dataField` to `''` here.
+
+For example, if your backend returns data in the following format.
+
+```js
+{
+ success: true,
+ data: 123,
+ code: 1,
+}
+```
+
+Then useRequest can directly consume the `data`, which would be 123, instead of `{ success, data, code }`.
+
+### Runtime configuration
+
+In `src/app.ts`, you can customize the request settings for your project by configuring the request item.
+
+```ts
+import type { RequestConfig } from 'umi';
+
+export const request: RequestConfig = {
+ timeout: 1000,
+ // other axios options you want
+ errorConfig: {
+ errorHandler(){
+ },
+ errorThrower(){
+ }
+ },
+ requestInterceptors: [],
+ responseInterceptors: []
+};
+```
+
+Besides `errorConfig`, `requestInterceptors`, and `responseInterceptors`, other configurations are directly passed through to [axios](https://axios-http.com/docs/req_config)'s request configuration. **The rules configured here apply to all** `request` and `useRequest` **methods**.
+
+The runtime configuration options of `plugin-request` are introduced below. At the end of this section, we will provide a complete runtime configuration example, describing its functionality in detail.
+
+#### errorConfig
+If you want to set a unified error handling scheme for your requests, you can configure it here.
+
+`errorThrower` takes the data returned by your backend and needs to throw an error you define. You can process the backend data here as needed.
+
+Our `request` will catch the error thrown by `errorThrower` and execute your `errorHandler` method, which accepts two arguments. The first argument is the caught error, and the second argument is the request's opts.
+
+`errorHandler` and `errorThrower` need to be used together. A complete example is provided at the end of the document.
+
+If you find this way of error handling too complicated, you can directly implement your error handling in the interceptors.
+
+:::info{title=🚨}
+`errorThrower` is implemented using `responseInterceptors`, triggered when `data.success` is `false`.
+:::
+
+#### requestInterceptors
+Add request phase interceptors to the request method.
+
+Pass in an array where each element is an interceptor. They will be registered on the axios instance in order. The syntax for writing interceptors is consistent with axios request interceptor. It needs to take the request config as an argument and return it.
+
+We recommend using `RequestConfig`, which helps you write your interceptors in a standardized manner.
+
+e.g.
+```ts
+const request: RequestConfig = {
+ requestInterceptors: [
+ // directly write a function as an interceptor
+ (url, options) =>
+ {
+ // do something
+ return { url, options }
+ },
+ // a tuple, the first element is the request interceptor, the second is the error handler
+ [(url, options) => {return { url, options }}, (error) => {return Promise.reject(error)}],
+ // array, omitting error handler
+ [(url, options) => {return { url, options }}]
+ ]
+
+}
+```
+
+Furthermore, to better accommodate umi-request, we allow umi-request interceptor syntax, even though it might not pass TypeScript's syntax check.
+
+#### responseInterceptors
+Add response phase interceptors to the request method.
+
+Pass in an array where each element is an interceptor. They will be registered on the axios instance in order. The syntax for writing interceptors is consistent with axios response interceptor. It takes the axios response as an argument and returns it.
+
+We recommend using `RequestConfig`, which helps you write your interceptors in a standardized manner.
+
+e.g.
+```ts
+const request: RequestConfig = {
+ responseInterceptors: [
+ // directly write a function as an interceptor
+ (response) =>
+ {
+ // No need for asynchronous processing to read response body content, can directly read from data, some fields can be found in the config
+ const { data = {} as any, config } = response;
+ // do something
+ return response
+ },
+ // a tuple, the first element is the request interceptor, the second is the error handler
+ [(response) => {return response}, (error) => {return Promise.reject(error)}],
+ // array, omitting error handler
+ [(response) => {return response}]
+ ]
+
+}
+```
+
+**Note: We will register interceptors according to your array sequence, but their execution order follows axios's convention, with request interceptors added later executing first, and response interceptors added later executing last**
+
+## API
+### useRequest
+The plugin has built-in [@ahooksjs/useRequest](https://ahooks-v2.js.org/hooks/async), allowing you to consume data simply and conveniently within components. The example is as follows:
+```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}
;
+};
+```
+In the above code, `data` is not the data returned by your backend, but its internal `data`, (because the default build-time configuration is 'data')
+
+It should be noted that ahooks has been updated to 3.0, but for making it less difficult for `umi@3` projects to upgrade, we continued to use ahooks 2.0
+
+
+### request
+By `import { request } from '@@/plugin-request'`, you can use the built-in request method.
+
+`request` accepts `options` in addition to passing through all of [axios](https://axios-http.com/docs/req_config)'s config, we also added a few extra attributes `skipErrorHandler`, `getResponse`, `requestInterceptors` and `responseInterceptors`.
+
+The example is as follows:
+```typescript
+request('/api/user', {
+ params: { name : 1 },
+ timeout: 2000,
+ // other axios options
+ skipErrorHandler: true,
+ getResponse: false,
+ requestInterceptors: [],
+ responseInterceptors: [],
+}
+```
+
+When you want a particular request to skip error handling, you can achieve this by setting `skipErrorHandler` to `true`.
+
+request returns the data from your backend by default, if you wish to receive the complete response structure from axios, it can be achieved by passing `{ getResponse: true }`.
+
+`requestInterceptors` and `responseInterceptors` are written in the same way as the interceptors in runtime configuration, but the difference is that the interceptors registered here are "one-off". Furthermore, the interceptors written here will be registered after those in the runtime configuration.
+
+**Note: When you have used errorHandler, the response interceptors registered here will be ineffective, because errorHandler will throw error**
+
+### RequestConfig
+This is an interface definition that can help you better configure runtime settings.
+```typescript
+import type { RequestConfig } from 'umi';
+
+export const request:RequestConfig = {};
+```
+Note that you should add type when importing
+
+## umi@3 to umi@4
+In the upgrade from `umi@3` to `umi@4`, we discontinued umi-request and chose axios as the default request solution. Some functionality changes occurred in this switch.
+
+### Changes in runtime configuration
+Compared to `umi@3`, `umi@4`'s runtime configuration has undergone significant changes.
+```diff
+ export const request: RequestConfig = {
+ errorConfig: {
+++ errorHandler: () => {},
+++ errorThrower: () => {}
+-- errorPage: '',
+-- adaptor: ()=>{},
+ };
+-- middlewares: [],
+++ requestInterceptors: [],
+++ responseInterceptors: [],
+ ... // Differences between umi-request and axios.
+ };
+```
+
+- umi-request's configuration items have become axios's configuration items.
+- Removed the middlewares middleware. You can use axios's [interceptors](https://axios-http.com/docs/interceptors) to achieve the same functionality.
+- errorConfig removed all original settings, adding errorHandler and errorThrower for unified error handling settings.
+
+Replacing middleware. For a `umi@3` middleware, content before the `next()` method should be placed in `requestInterceptors`, while content after the `next()` method should be placed in `responseInterceptors`.
+
+```ts
+
+// Middleware
+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
+ }
+}
+
+// Interceptor
+{
+ requestInterceptors:[
+ (config) => {
+ if (config.url.indexOf('/api') !== 0) {
+ config.url = `/api/v1/${url}`;
+ }
+ return config;
+ }
+ ],
+ responseInterceptors: [
+ (response) => {
+ if(!response.data.success){
+ // do something
+ }
+ }
+ ]
+}
+```
+
+### Changes in request method parameters
+[umi-request](https://github.com/umijs/umi-request#request-options) and [axios](https://axios-http.com/docs/req_config) have some differences in configuration items. You can compare them by referring to their respective documentation.
+
+### GET request parameter serialization
+
+[Umi@3](https://github.com/umijs/umi-request/blob/master/src/middleware/simpleGet.js) uses the same Key to serialize arrays by default. Umi@4 requests based on axios, by default, serialize in the form with brackets `[]`.
+
+```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
+```
+
+If you wish to maintain the Umi@3 form, you can do so:
+
+```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);
++ },
+ ...
+}
+```
+
+## Runtime configuration example
+Here's a complete example of runtime configuration, to help you better customize the request scheme for your project.
+
+```ts
+import { RequestConfig } from './request';
+
+// Error handling scheme: Error types
+enum ErrorShowType {
+ SILENT = 0,
+ WARN_MESSAGE = 1,
+ ERROR_MESSAGE = 2,
+ NOTIFICATION = 3,
+ REDIRECT = 9,
+}
+// Response data structure agreed with the backend
+interface ResponseStructure {
+ success: boolean;
+ data: any;
+ errorCode?: number;
+ errorMessage?: string;
+ showType?: ErrorShowType;
+}
+
+// Runtime configuration
+export const request: RequestConfig = {
+ // Unified request settings
+ timeout: 1000,
+ headers: {'X-Requested-With': 'XMLHttpRequest'},
+
+ // Error handling: umi@3's error handling scheme.
+ errorConfig: {
+ // Error throwing
+ 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; // Throw custom error
+ }
+ },
+ // Error catching and handling
+ errorHandler: (error: any, opts: any) => {
+ if (opts?.skipErrorHandler) throw error;
+ // The errors thrown by our 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 error
+ // The request was made, and the server responded with a status code that falls out of the range of 2xx
+ message.error(`Response status:${error.response.status}`);
+ } else if (error.request) {
+ // The request was made but no response was received
+ // \`error.request\` is an instance of XMLHttpRequest in the browser and an instance of
+ // http.ClientRequest in node.js
+ message.error('None response! Please retry.');
+ } else {
+ // Something happened in setting up the request that triggered an error
+ message.error('Request error, please retry.');
+ }
+ },
+
+ },
+
+ // Request interceptors
+ requestInterceptors: [
+ (config) => {
+ // Intercept request configurations for personalized processing.
+ const url = config.url.concat('?token = 123');
+ return { ...config, url};
+ }
+ ],
+
+ // Response interceptors
+ responseInterceptors: [
+ (response) => {
+ // Intercept the response data for personalized processing
+ const { data } = response;
+ if(!data.success){
+ message.error('Request failed!');
+ }
+ return response;
+ }
+ ]
+};
+```
+
+The above example's error handling scheme is derived from `umi@3`'s built-in error handling. In this version, we removed it to allow users greater freedom in customizing their error handling schemes. If you still want to use it, you can paste this runtime configuration into your project.
+
+You can also write your own error handling through response interceptors, **not limited to 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..2a36b8e4acef
--- /dev/null
+++ b/docs/docs/docs/max/styled-components.en-US.md
@@ -0,0 +1,94 @@
+---
+order: 10
+toc: content
+translated_at: '2024-03-17T08:11:13.382Z'
+---
+
+# styled-components
+
+@umijs/max comes with the [styled-components](https://styled-components.com/) styling solution built-in.
+
+## Enabling
+
+For @umijs/max, enable by configuring.
+
+```ts {2}
+export default {
+ styledComponents: {},
+}
+```
+
+For umi, first install `@umijs/plugins` dependency, then enable through configuration.
+
+```bash
+$ pnpm i @umijs/plugins -D
+```
+
+```ts
+export default {
+ plugins: ['@umijs/plugins/dist/styled-components'],
+ styledComponents: {},
+}
+```
+
+## Features
+
+The plugin does a few things for you,
+
+1. Most of the styled-components exports can be imported from `umi` or `@umijs/max`.
+
+2. Supports enabling the styled-components babel plugin through configuration in dev mode only.
+
+3. Supports declaring global styles via runtime configuration.
+
+## Configuration Options
+
+The following configurations can be made in `styledComponents`.
+
+- `babelPlugin`: Object, enable the styled-components babel plugin, effective in dev mode only
+
+For example:
+
+```ts
+export default {
+ styledComponents: {
+ babelPlugin: {},
+ },
+}
+```
+
+When your import source is not `umi` / `@umijs/max`, you need to configure the import source to `topLevelImportPaths` to make the babel plugin work, such as:
+
+```ts
+import { styled } from 'alita'
+```
+
+```ts
+export default {
+ styledComponents: {
+ babelPlugin: {
+ topLevelImportPaths: ['alita']
+ },
+ },
+}
+```
+
+## Runtime Configuration Options
+
+Includes the following configurations.
+
+- `GlobalStyle`: ReactComponent
+
+For example:
+
+```ts
+import { createGlobalStyle } from "umi";
+
+export const styledComponents = {
+ GlobalStyle: createGlobalStyle`
+ h1 {
+ background: #ccc;
+ }
+ `
+}
+```
diff --git a/docs/docs/docs/max/styled-components.md b/docs/docs/docs/max/styled-components.md
index 0bb77889390c..bc8d461752c2 100644
--- a/docs/docs/docs/max/styled-components.md
+++ b/docs/docs/docs/max/styled-components.md
@@ -55,6 +55,22 @@ export default {
}
```
+当你的导入来源不是 `umi` / `@umijs/max` 时，需将导入来源配置到 `topLevelImportPaths` 才可以使该 babel 插件生效，如：
+
+```ts
+import { styled } from 'alita'
+```
+
+```ts
+export default {
+ styledComponents: {
+ babelPlugin: {
+ topLevelImportPaths: ['alita']
+ },
+ },
+}
+```
+
## 运行时配置项
包含以下配置。
@@ -64,7 +80,7 @@ export default {
比如：
```ts
-import {createGlobalStyle} from "umi";
+import { createGlobalStyle } from "umi";
export const styledComponents = {
GlobalStyle: createGlobalStyle`
diff --git a/docs/docs/docs/max/tailwindcss.mdd b/docs/docs/docs/max/tailwindcss.md
similarity index 100%
rename from docs/docs/docs/max/tailwindcss.mdd
rename to docs/docs/docs/max/tailwindcss.md
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..60a0a8b488d5
--- /dev/null
+++ b/docs/docs/docs/max/valtio.en-US.md
@@ -0,0 +1,198 @@
+---
+order: 12
+toc: content
+translated_at: '2024-03-17T08:10:46.432Z'
+---
+
+# valtio
+
+@umijs/max comes with a built-in valtio data flow solution.
+
+## Enable valtio
+
+Configure to enable.
+
+```ts
+export default {
+ valtio: {},
+}
+```
+
+## Getting Started
+
+### Basic Usage
+
+Extremely simple.
+
+```ts
+import { proxy, useSnapshot } from 'umi';
+
+// 1. Define data
+const state = proxy({ count: 0 });
+// 2. Use data
+const snap = useSnapshot(state);
+snap.count;
+// 3. Update data
+state.count += 1;
+```
+
+### Access Outside React
+
+Naturally supported.
+
+```ts
+import { proxy } from 'umi';
+
+const state = proxy({ count: 0 });
+state.count;
+state.count += 1;
+```
+
+### Data Deduction
+
+```ts
+import { proxyWithComputed } from 'umi';
+
+const state = proxyWithComputed({
+ count: 0,
+}, {
+ double: snap => snap.count * 2,
+});
+```
+
+### Actions and Async Actions
+
+Two ways to use, can be combined with state or separated.
+
+```ts
+import { proxy } from 'umi';
+
+// Method one: Combine
+const state = proxy({
+ count: 0,
+ actions: {
+ add() {
+ // Note, do not use this.count, will error when called based on snap
+ state.count += 1;
+ },
+ }
+});
+// Method two: Separate
+const state = proxy({ count: 0 });
+const actions = {
+ add() {
+ state.count += 1;
+ },
+ // Async action
+ async addAsync() {
+ state.count += await fetch('/api/add');
+ },
+};
+```
+
+### Splitting and Combining Data Structures
+
+```ts
+import { proxy } from 'umi';
+
+// For example, as follows defined
+// state.foo and state.bar are both proxies, can be split and used
+const state = proxy({
+ foo: { a: 1 },
+ bar: { b: 1 },
+});
+
+// Combination
+const foo = proxy({ a: 1 });
+const bar = proxy({ b: 1 });
+const state = proxy({ foo, bar });
+```
+
+### Component Encapsulation
+
+If the content of props is unrelated to state, it can be left unhandled; if related, wrap it with context as follows, while synchronizing props to state data.
+
+```ts
+import { proxy } from 'umi';
+
+// 1. createContext
+const MyContext = createContext();
+// 2. Provider
+const value = useRef(proxy({ count: 0 })).current;
+index page
{intl.formatMessage({ id: 'HELLO' })}
- {intl.formatMessage({ id: 'HELLO' })}
+
+ {intl.formatMessage({ id: 'user.welcome' })}
+
+