Umi

https://umijs.org
Admin
Umi is an extensible enterprise-level React framework with built-in routing, plugin system, MFSU...
Tokens:201,628
Snippets:1,627
Trust Score:9.2
Update:6 days ago
Show doc for...
Tokens:
Raw
### Setup postinstall script

Source: https://umijs.org/docs/api/commands

Add `umi setup` to the `postinstall` script in package.json to initialize the project after installation.

```json
{
  "scripts": { "postinstall": "umi setup" }
}
```

--------------------------------

### addOnDemandDeps example

Source: https://umijs.org/docs/api/plugin-api

Adds dependencies that are installed on demand when the project starts. The callback returns an array of dependency objects.

```typescript
api.addOnDemandDeps(() => [{ name: '@swc/core', version: '^1.0.0', dev: true }])
```

--------------------------------

### matchPath usage example

Source: https://umijs.org/docs/api/api

Example of using matchPath to match a pathname against a pattern and get the match result with params.

```ts
import { matchPath } from 'umi';
const match = matchPath(
  { path: "/users/:id" },
  "/users/123",
);
// {
//   "params": { "id": "123" },
//   "pathname": "/users/123",
//   "pathnameBase": "/users/123",
//   "pattern": { "path": "/users/:id" }
// }
```

--------------------------------

### 使用 vite 模式运行 example

Source: https://umijs.org/docs/introduce/contributing

在 example 目录下运行 pnpm dev --vite 以使用 vite 模式。

```bash
$ pnpm dev --vite
```

--------------------------------

### useNavigate go back example

Source: https://umijs.org/docs/api/api

Example of using useNavigate to go back to the previous page by passing -1.

```ts
import { useNavigate } from 'umi';


let navigate = useNavigate();
navigate(-1);
```

--------------------------------

### useNavigate navigate to path example

Source: https://umijs.org/docs/api/api

Example of using useNavigate to navigate to a relative path with replace option.

```ts
import { useNavigate } from 'umi';


let navigate = useNavigate();
navigate("../success", { replace: true });
```

--------------------------------

### View Umi config with list and get

Source: https://umijs.org/docs/api/commands

Use `umi config list` to list all config keys and `umi config get <key>` to get a specific config value. The output shows the current config values.

```bash
$ umi config list
 - [key: polyfill] false
 - [key: externals] { esbuild: true }


$ umi config get mfsu
 - [key: externals] { esbuild: true }
```

--------------------------------

### links configuration example

Source: https://umijs.org/docs/api/config

Adds extra link tags to the HTML. The example adds a preload link for a CSS file.

```javascript
links: [{ href: '/foo.css', rel: 'preload' }],
```

--------------------------------

### Start dev server

Source: https://umijs.org/docs/api/commands

Run `umi dev` to start the local development server. The output shows the local and network addresses and a successful compilation message.

```bash
$ umi dev
        ╔═════════════════════════════════════════════════════╗
        ║ App listening at:                                   ║
        ║  >   Local: https://127.0.0.1:8001                  ║
ready - ║  > Network: https://192.168.1.1:8001                ║
        ║                                                     ║
        ║ Now you can open browser with the above addresses👆 ║
        ╚═════════════════════════════════════════════════════╝
event - compiled successfully in 1051 ms (416 modules)
```

--------------------------------

### Start dev server with SOCKET_SERVER

Source: https://umijs.org/docs/guides/debug

Start the Umi dev server with the SOCKET_SERVER environment variable to prevent page refresh issues when using XSwitch.

```bash
$SOCKET_SERVER=http://127.0.0.1:8000/ npx umi dev
```

--------------------------------

### Define runtime config with defineApp for TypeScript hints

Source: https://umijs.org/docs/api/runtime-config

Use `defineApp` from 'umi' to get TypeScript hints when writing runtime configuration. The example sets a layout title to 'umi'.

```javascript
import { defineApp } from 'umi';
export default defineApp({
  layout: () => {
    return {
      title: 'umi',
    };
  },
});
```

--------------------------------

### useRouteProps route configuration example

Source: https://umijs.org/docs/api/api

Example of defining custom props in the route configuration file (.umirc.ts).

```ts
// .umirc.ts
routes: [
  {
    path: '/',
    custom_key: '1',
  }
]
```

--------------------------------

### List routes for exportStatic example

Source: https://umijs.org/docs/api/config

Example routes used to illustrate exportStatic behavior. These routes are used to show how output HTML files are generated.

```bash
/
/docs
/docs/a
```

--------------------------------

### vite configuration example

Source: https://umijs.org/docs/api/config

Merges custom configuration into Vite's default configuration. The example changes the temporary file path to 'node_modules/.bin/.vite'.

```typescript
// 更改临时文件路径到 node_modules/.bin/.vite 文件夹
vite: {
  cacheDir: 'node_modules/.bin/.vite',
}

```

--------------------------------

### MF plugin configuration example

Source: https://umijs.org/docs/max/mf

Example configuration for the MF plugin in .umirc.ts, defining name, remotes, and shared modules.

```ts
// .umirc.ts
export default defineConfig({
  mf: {
    name: 'remoteMFName',
    remotes: [
      {
        name: 'remote1',
        entry: 'https://to.the.remote.com/remote.js',
      },
      {
        aliasName: 'aliasRemote',
        name: 'remote2',
        entry: 'https://to.the.remote.com/remote2.js',
      },
    ],
    shared: {
      react: {
        singleton: true,
        eager: true,
      },
      'react-dom': {
        singleton: true,
        eager: true,
      },
    }
  },
});
```

--------------------------------

### history.push and navigation usage example

Source: https://umijs.org/docs/api/api

Example of imperative route navigation using history.push, history.back, and history.go. Note: state must be passed as the second argument to history.push and history.replace.

```ts
import { history } from 'umi';


// 跳转到指定路由
history.push('/list');


// 带参数跳转到指定路由
history.push('/list?a=b&c=d#anchor', state);
history.push({
    pathname: '/list',
    search: '?a=b&c=d',
    hash: 'anchor',
  },
  {
    some: 'state-data',
  }
);


// 跳转当前路径，并刷新 state
history.push({}, state)


// 跳转到上一个路由
history.back();
history.go(-1);
```

--------------------------------

### 修改启动命令：使用 max 替换 umi，并更新 setup 命令

Source: https://umijs.org/docs/introduce/upgrade-to-umi-4

在 package.json 的 scripts 中，将 build、start 命令中的 umi 替换为 max，并将 postinstall 中的 umi g tmp 替换为 max setup。

```diff
{
  "scripts": {
-    "build": "umi build",
+    "build": "max build",
-    "postinstall": "umi g tmp",
+    "postinstall": "max setup",
-    "start": "umi dev",
+    "start": "max dev",
  }
}
```

--------------------------------

### Show help for all commands

Source: https://umijs.org/docs/api/commands

Run `umi help` to display a list of available commands and general usage information.

```bash
$ umi help
Usage: umi <command> [options]


Commands:


    build     build app for production
    config    umi config cli
    dev       dev server for development
    help      show commands help
    setup     setup project
    version   show umi version
    plugin    inspect umi plugins
    generate  generate code snippets quickly


Run `umi help <command>` for more information of specific commands.
Visit https://umijs.org/ to learn more about Umi.
```

--------------------------------

### 运行 example

Source: https://umijs.org/docs/introduce/contributing

进入 examples/boilerplate 目录并运行 pnpm dev 以启动示例。

```bash
$ cd examples/boilerplate
$ pnpm dev
```

--------------------------------

### window.location usage example

Source: https://umijs.org/docs/api/api

Example of getting current route information outside React components and hooks using window.location.

```ts
// location 对象，包含 pathname、search 和 hash
window.location.pathname;
window.location.search;
window.location.hash;
```

--------------------------------

### useRouteData usage example

Source: https://umijs.org/docs/api/api

Example of using useRouteData to get the current route object, including path, id, parentId, and file.

```ts
import { useRouteData } from 'umi';


const route = useRouteData();
/* route
{
  route: {
    path: 'a/page',
    id: 'a/page/index',
    parentId: '@@/global-layout',
    file: 'a/page/index.tsx'
  }
}
*/
```

--------------------------------

### Show help for build command

Source: https://umijs.org/docs/api/commands

Run `umi help build` to see detailed help for the build command, including options like `--clean` and environment variable `COMPRESS=none`.

```bash
$ umi help build
Usage: umi build [options]
build app for production.


Details:
    umi build


    # build without compression
    COMPRESS=none umi build


    # clean and build
    umi build --clean
```

--------------------------------

### useLocation usage example

Source: https://umijs.org/docs/api/api

Example of using useLocation hook to get current route information (pathname, search, hash) inside components or hooks.

```ts
// 建议组件或 hooks 里用 useLocation 取
import { useLocation } from 'umi';
export default function Page() {
  let location = useLocation();
  return (
    <div>
     { location.pathname }
     { location.search }
     { location.hash }
    </div>
  );
}
```

--------------------------------

### Preview with custom port

Source: https://umijs.org/docs/api/commands

Run `umi preview --port 9527` to start a static server on port 9527 for previewing the built output.

```bash
$ umi preview --port 9527
```

--------------------------------

### useParams usage example

Source: https://umijs.org/docs/api/api

Example of using useParams to get dynamic route parameters. For route 'user/:uId/repo/:rId' and path 'user/abc/repo/def', returns { uId: 'abc', rId: 'def'}.

```ts
import { useParams } from 'umi';


// 假设有路由配置  user/:uId/repo/:rId
// 当前路径       user/abc/repo/def
const params = useParams()
/* params
{ uId: 'abc', rId: 'def'}
*/
```

--------------------------------

### Show Umi CLI help

Source: https://umijs.org/docs/api/commands

Run `umi help` to list all available commands. The output shows the command list and usage instructions.

```bash
umi help
```

```bash
Usage: umi <command> [options]


Commands:


    build     build app for production
    config    umi config cli
    dev       dev server for development
    help      show commands help
    lint      lint source code using eslint and stylelint
    setup     setup project
    deadcode  check dead code
    version   show umi version
    v         show umi version
    plugin    inspect umi plugins
    verify-commit verify the commit message, which is usually used with husky.
    preview   locally preview production build
    run       run the script commands, support for ts and zx
    generate  generate code snippets quickly
    g         generate code snippets quickly


Run `umi help <command>` for more information of specific commands.
Visit https://umijs.org/ to learn more about Umi.
```

--------------------------------

### Helmet usage example

Source: https://umijs.org/docs/api/api

Example of using the Helmet component from Umi (react-helmet-async) to dynamically configure head tags like title. Note: use Umi's Helmet instead of installing react-helmet separately for SSR to work.

```tsx
import { Helmet } from 'umi';


export default function Page() {
  return (
    <Helmet>
      <title>Hello World</title>
    </Helmet>
  );
}
```

--------------------------------

### TypeScript configuration with defineConfig in .umirc.ts

Source: https://umijs.org/docs/guides/typescript

Wrap the Umi configuration in defineConfig() to get TypeScript syntax hints. The example shows a routes configuration in .umirc.ts.

```typescript
// .umirc.ts

import { defineConfig } from 'umi';

export default defineConfig({
  routes: [
    { path: '/', component: '@/pages/index' },
  ],
});
```

--------------------------------

### Build project for production

Source: https://umijs.org/docs/api/commands

Run `umi build` to build the app for production deployment.

```bash
$ umi build
```

--------------------------------

### Alias with require.resolve for dependencies

Source: https://umijs.org/docs/api/config

Shows the recommended way to alias a dependency using require.resolve to get the absolute path. The first example is incorrect because it uses a bare module name.

```JavaScript
// ⛔
{
  alias: {
    foo: 'foo',
  }
}


// ✅
{
  alias: {
    foo: require.resolve('foo'),
  }
}
```

--------------------------------

### onStart

Source: https://umijs.org/docs/api/plugin-api

Hook that is called at startup. The provided function receives no arguments.

```APIDOC
## onStart

### Description
Called at startup. The provided function receives no arguments.
```

--------------------------------

### Install lint-staged

Source: https://umijs.org/docs/guides/lint

Install lint-staged as a dev dependency using npm or pnpm.

```bash
$ npm i lint-staged -D
#or
$ pnpm add lint-staged -D
```

--------------------------------

### Install @utoo/lint

Source: https://umijs.org/docs/guides/lint

Install the @utoo/lint package as a dev dependency. Requires Node.js 20 or higher.

```bash
$ pnpm add -D @utoo/lint
```

--------------------------------

### useRoutes usage example

Source: https://umijs.org/docs/api/api

Example of using useRoutes to render a route configuration with nested routes.

```ts
import * as React from "react";
import { useRoutes } from "umi";


function App() {
  let element = useRoutes([
    {
      path: "/",
      element: <Dashboard />,
      children: [
        {
          path: "messages",
          element: <DashboardMessages />,
        },
        { path: "tasks", element: <DashboardTasks /> },
      ],
    },
    { path: "team", element: <AboutPage /> },
  ]);


  return element;
}
```

--------------------------------

### Example pages directory structure

Source: https://umijs.org/docs/guides/directory-structure

Shows a sample pages directory structure with a users folder and an index file. This is used to illustrate how conventional routing generates routes.

```text
+ pages/
  + users/
    - index.tsx
  - index.tsx
```

--------------------------------

### 使用 .env.local 覆盖环境变量

Source: https://umijs.org/docs/guides/env-variables

在 .env.local 中覆盖 .env 的配置，例如将端口改为 4000。执行 umi dev 后，Umi 会以 4000 端口启动，同时保持禁用 babel 缓存。

```text
# file .env.local
PORT=4000

```

--------------------------------

### Install @umijs/plugins for Umi

Source: https://umijs.org/docs/max/react-query

Install the @umijs/plugins package as a dev dependency to use the react-query plugin in Umi.

```Bash
$ pnpm i @umijs/plugins -D
```

--------------------------------

### Run Prisma migration and generate client

Source: https://umijs.org/blog/develop-blog-using-umi

Commands to migrate the MySQL database to match the schema and generate a tailored Prisma client package. Run in the command line after creating the schema file.

```shell
npx prisma migrate dev --name init
```

```shell
npx prisma generate
```

--------------------------------

### Install @umijs/lint with npm or pnpm

Source: https://umijs.org/docs/guides/lint

Install the @umijs/lint package as a dev dependency using npm or pnpm.

```bash
$ npm i @umijs/lint -D
# or
$ pnpm add @umijs/lint -D
```

--------------------------------

### Install @babel/runtime as dev dependency

Source: https://umijs.org/docs/api/config

Command to install @babel/runtime as a dev dependency, as required after configuring transformRuntime.

```bash
$ npm install @babel/runtime --save-dev

```

--------------------------------

### registerMfRemote usage example

Source: https://umijs.org/docs/max/mf

Example of using registerMfRemote to register a remote, then using safeMfImport to load a module from it.

```ts
registerMfRemote({
  aliasName: 'registered',
  remoteName: 'remoteCounter',
  entry: 'http://127.0.0.1:8001/remote.js',
});


const RemoteCounter = React.lazy(() => {
  return safeMfImport('registered/Counter', { default: null });
});
```

--------------------------------

### 使用 pnpm create umi 创建项目

Source: https://umijs.org/docs/guides/boilerplate

运行此命令会安装 create-umi 脚手架并自动运行，提供选择 Npm 客户端和源的向导。第二个命令会在当前目录的 my-umi-app 文件夹下创建项目。

```bash
# 在向导中输入文件夹名称
pnpm create umi
# 在当前目录的 my-umi-app 文件夹下创建项目
pnpm create umi my-umi-app
```

--------------------------------

### useRouteProps usage example

Source: https://umijs.org/docs/api/api

Example of using useRouteProps to access custom route props in a page component.

```ts
import { useRouteProps } from 'umi'


export default function Page() {
  const routeProps = useRouteProps()


  // use `routeProps.custom_key`
}
```

--------------------------------

### List all plugins

Source: https://umijs.org/docs/api/commands

Run `umi plugin list` to list all registered plugins.

```bash
$ umi plugin list
- @umijs/core/dist/service/servicePlugin
- @umijs/preset-umi (from preset)
- @umijs/preset-umi/dist/registerMethods (from preset)
- @umijs/preset-umi/dist/features/appData/appData (from preset)
- @umijs/preset-umi/dist/features/check/check (from preset)
- @umijs/preset-umi/dist/features/configPlugins/configPlugins (from preset)
- virtual: config-styles
- virtual: config-scripts
- virtual: config-routes
- virtual: config-plugins
...
```

--------------------------------

### 使用 bun 创建 Umi 项目

Source: https://umijs.org/docs/guides/getting-started

使用 bunx create-umi 创建项目，并选择 pnpm 作为包管理器，npm 作为 npm 源。

```bash
$ bunx create-umi
✔ Pick Umi App Template › Simple App
✔ Pick Npm Client › pnpm
✔ Pick Npm Registry › npm
Write: .gitignore
Write: .npmrc
Write: .umirc.ts
Write: package.json
Copy:  src/assets/yay.jpg
Copy:  src/layouts/index.less
Write: src/layouts/index.tsx
Copy:  src/pages/docs.tsx
Copy:  src/pages/index.tsx
Write: tsconfig.json
Copy:  typings.d.ts
ready - Git initialized successfully
```

--------------------------------

### useOutlet usage example

Source: https://umijs.org/docs/api/api

Example of using useOutlet in a layout component to render the child route element.

```ts
import { useOutlet } from 'umi';


const Layout = ()=>{
  const outlet = useOutlet()


  return <div className="fancyLayout">
    {outlet}
  </div>
}
```

--------------------------------

### 在 .env 文件中设置环境变量

Source: https://umijs.org/docs/guides/env-variables

在项目根目录的 .env 文件中定义共享环境变量，例如 PORT=3000 和 BABEL_CACHE=none。执行 umi dev 后，Umi 会以 3000 端口启动并禁用 babel 缓存。

```text
# file .env
PORT=3000
BABEL_CACHE=none

```

```bash
$ umi dev

```

--------------------------------

### generatePath usage example

Source: https://umijs.org/docs/api/api

Example of generatePath, which generates an actual route path from a path pattern and params.

```ts
import { generatePath } from 'umi';


generatePath("/users/:id", { id: "42" }); // "/users/42"
generatePath("/files/:type/*", {
  type: "img",
  "*": "cat.jpg",
}); // "/files/img/cat.jpg"
```

--------------------------------

### mfsu configuration examples

Source: https://umijs.org/docs/api/config

Shows three mfsu configurations: using esbuild for precompilation, disabling mfsu, and modifying webpack config via chainWebpack. The first two are shown together as alternatives.

```javascript
// 用 esbuild 做依赖预编译
mfsu: {
  esbuild: true,
}


// 关闭 mfsu 功能
mfsu: false;
```

```javascript
// webpack 配置修改
mfsu: {
  chainWebpack(memo, args) {
    // 添加额外插件
    memo.plugin('hello').use(Plugin, [...args]);
    return memo;
  }
}
```

--------------------------------

### 在 .env 文件中使用变量拼接

Source: https://umijs.org/docs/guides/env-variables

在 .env 文件中支持变量拼接，例如 CONCAT=$FOO$BAR 会得到 CONCAT=foobar。

```text
# file .env.local
FOO=foo
BAR=bar


CONCAT=$FOO$BAR # CONCAT=foobar

```

--------------------------------

### Install babel-plugin-dynamic-import-node

Source: https://umijs.org/docs/introduce/faq

Install the babel plugin needed to disable dynamicImport in production. Run this command in your project root.

```bash
pnpm i babel-plugin-dynamic-import-node -D
```

--------------------------------

### 修改 package.json 中的 build 脚本（修改后）

Source: https://umijs.org/blog/develop-blog-using-umi

展示修改后的 build 脚本，在构建前先执行 prisma generate，确保 Prisma 客户端已生成。

```json
"scripts": {
  "dev": "umi dev",
  "build": "prisma generate && umi build",
  "postinstall": "umi setup",
  "start": "npm run dev"
},
```

--------------------------------

### rawMfImport usage example

Source: https://umijs.org/docs/max/mf

Example of using rawMfImport with React.lazy to load a remote Counter component from a remote entry.

```ts
const RemoteCounter = React.lazy(() => {
  return rawMfImport({
    entry: 'http://localhost:8001/remote.js',
    moduleName: 'Counter',
    remoteName: 'remoteCounter',
  });
});
```

--------------------------------

### Dynamic route example for extraRoutePaths

Source: https://umijs.org/docs/api/config

Example dynamic route used to illustrate extraRoutePaths configuration for static generation.

```bash
/news/:id
```

--------------------------------

### 修改 package.json 中的 build 脚本（修改前）

Source: https://umijs.org/blog/develop-blog-using-umi

展示修改前的 package.json 中 scripts 部分，build 脚本为 "umi build"。

```json
"scripts": {
  "dev": "umi dev",
  "build": "umi build",
  "postinstall": "umi setup",
  "start": "npm run dev"
},
```

--------------------------------

### useOutletContext usage example

Source: https://umijs.org/docs/api/api

Example of using useOutletContext to access context passed from a layout to a child route component.

```ts
import { useOutletContext, Outlet } from 'umi';


const Layout = () => {
  return <div className="fancyLayout">
    <Outlet context={{ prop: 'from Layout'}} />
  </div>
}


const SomeRouteComponentUnderLayout = () => {
  const layoutContext = useOutletContext();


  return JSON.stringify(layoutContext)   // {"prop":"from Layout"}
}
```

--------------------------------

### Configure proxy for API requests

Source: https://umijs.org/docs/api/config

Sets up a proxy for API requests. The example proxies '/api' to 'http://jsonplaceholder.typicode.com/' with path rewriting. Note: proxy only works in dev mode.

```javascript
proxy: {
  '/api': {
    'target': 'http://jsonplaceholder.typicode.com/',
    'changeOrigin': true,
    'pathRewrite': { '^/api' : '' },
  }
}
```

--------------------------------

### history.listen usage example

Source: https://umijs.org/docs/api/api

Example of listening to route changes with history.listen. The returned unlisten function stops the listener.

```ts
import { history } from 'umi';


const unlisten = history.listen(({ location, action }) => {
  console.log(location.pathname);
});
unlisten();
```

--------------------------------

### 添加 MFSU 中间件（webpack 5）

Source: https://umijs.org/blog/mfsu-independent-usage

在 webpack 5 的 devServer.setupMiddlewares 中添加 MFSU 中间件，用于提供打包后的资源。

```javascript
// webpack.config.js


module.exports = {
  devServer: {
    // [mfsu] 2. add mfsu middleware
    setupMiddlewares(middlewares, devServer) {
      middlewares.unshift(...mfsu.getMiddlewares());
      return middlewares;
    },
  },
};
```

--------------------------------

### Mock file with omitted GET method

Source: https://umijs.org/docs/guides/mock

When the HTTP method is GET, the method part can be omitted; only the path is needed.

```ts
// ./mock/users.ts


export default {


  '/api/users': [
    { id: 1, name: 'foo' },
    { id: 2, name: 'bar' }
  ],


  '/api/users/1': { id: 1, name: 'foo' },


}
```

--------------------------------

### legacy configuration example

Source: https://umijs.org/docs/api/config

Enables legacy browser support with default settings. Setting buildOnly: false allows it to run in dev, and checkOutput: true runs es-check on build output.

```typescript
legacy: {}
```

--------------------------------

### Install react-compiler-runtime for React 18

Source: https://umijs.org/docs/api/config

Installs the react-compiler-runtime package as a production dependency, required when using utoopack.reactCompiler with React 18.

```bash
npm install react-compiler-runtime

```
Tokens:
Raw