0
# Umi
1
2
Umi is an enterprise-level, plugin-based React application framework designed to provide a simple and enjoyable web development experience. It offers out-of-the-box functionality including built-in routing, building, deployment, testing, and linting capabilities. The framework is battle-tested in enterprise environments, being used by 10,000+ applications at companies like Alibaba, Tencent, ByteDance, NetEase, and Meituan.
3
4
## Package Information
5
6
- **Package Name**: umi
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install umi`
10
11
## Core Imports
12
13
```typescript
14
import { defineConfig, defineMock, run, Service, RUNTIME_TYPE_FILE_NAME } from "umi";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { defineConfig, defineMock, run, Service, RUNTIME_TYPE_FILE_NAME } = require("umi");
21
```
22
23
Client-side plugin imports:
24
25
```typescript
26
import { PluginManager, ApplyPluginsType } from "umi/client";
27
```
28
29
Testing utilities:
30
31
```typescript
32
import { configUmiAlias, getUmiAlias } from "umi/test";
33
```
34
35
## Basic Usage
36
37
```typescript
38
import { defineConfig } from "umi";
39
40
// Define configuration with TypeScript support
41
export default defineConfig({
42
routes: [
43
{ path: "/", component: "@/pages/index" },
44
{ path: "/users", component: "@/pages/users" },
45
],
46
plugins: ["@umijs/plugin-react"],
47
devServer: {
48
port: 3000,
49
},
50
});
51
```
52
53
## Architecture
54
55
Umi is built around several key components:
56
57
- **Core Service**: Central service class that manages the application lifecycle, plugins, and configuration
58
- **Plugin System**: Extensible plugin architecture with both server-side and client-side plugin management
59
- **CLI Interface**: Command-line tools for development, building, and deployment
60
- **Configuration System**: Type-safe configuration with helper functions
61
- **Testing Integration**: Built-in testing utilities with alias resolution and Jest configuration
62
- **Build System**: Dual build engines (Vite and Webpack) with performance optimizations
63
64
## Capabilities
65
66
### Configuration Management
67
68
Type-safe configuration system with helper functions for defining app configuration and mock data. Essential for setting up routing, plugins, build options, and development settings.
69
70
```typescript { .api }
71
function defineConfig(config: ConfigType): ConfigType;
72
function defineMock(mockData: { [key: string]: MockDeclare }): typeof mockData;
73
```
74
75
[Configuration](./configuration.md)
76
77
### CLI and Service Management
78
79
Command-line interface and service management for running development servers, building applications, and executing framework commands.
80
81
```typescript { .api }
82
function run(opts?: IOpts): Promise<void>;
83
84
class Service extends CoreService {
85
constructor(opts?: any);
86
run2(opts: { name: string; args?: any }): Promise<any>;
87
}
88
```
89
90
[CLI and Service](./cli-service.md)
91
92
### Plugin System
93
94
Comprehensive plugin system supporting both server-side and client-side plugins with hook management, plugin registration, and execution control.
95
96
```typescript { .api }
97
enum ApplyPluginsType {
98
compose = "compose",
99
modify = "modify",
100
event = "event"
101
}
102
103
class PluginManager {
104
constructor(opts: { validKeys: string[] });
105
register(plugin: IPlugin): void;
106
applyPlugins(opts: ApplyPluginsOpts): any;
107
static create(opts: { validKeys: string[]; plugins: IPlugin[] }): PluginManager;
108
}
109
```
110
111
[Plugin System](./plugin-system.md)
112
113
### Testing Utilities
114
115
Testing integration utilities for Jest configuration, alias resolution, and umi-specific testing setup.
116
117
```typescript { .api }
118
function configUmiAlias(config: Config.InitialOptions): Promise<Config.InitialOptions>;
119
function getUmiAlias(): Promise<Record<string, string>>;
120
function getAliasPathWithKey(alias: Record<string, string>, key: string): string;
121
```
122
123
[Testing](./testing.md)
124
125
## Types
126
127
```typescript { .api }
128
// Main plugin API interface
129
interface IApi extends PluginAPI, IServicePluginAPI {
130
// Extensive plugin API with add, modify, and event methods
131
}
132
133
// Route configuration
134
interface IRoute {
135
path: string;
136
component?: string;
137
routes?: IRoute[];
138
exact?: boolean;
139
[key: string]: any;
140
}
141
142
// API request/response classes for API routes
143
class UmiApiRequest {
144
params: Record<string, string>;
145
body: any;
146
headers: Record<string, string>;
147
method: string;
148
query: Record<string, string | string[]>;
149
cookies: Record<string, string>;
150
url: string;
151
pathName: string;
152
readBody(): Promise<any>;
153
}
154
155
class UmiApiResponse {
156
status(code: number): UmiApiResponse;
157
header(key: string, value: string): UmiApiResponse;
158
setCookie(key: string, value: string): UmiApiResponse;
159
end(data?: string): void;
160
text(data: string): void;
161
html(data: string): void;
162
json(data: any): void;
163
}
164
165
// Configuration types
166
type ConfigType = IConfigFromPlugins & IConfig;
167
168
// Mock data types
169
type MockDeclare = string | number | null | undefined | boolean | Record<string, any> | RequestHandler;
170
171
// CLI options
172
interface IOpts {
173
presets?: string[];
174
}
175
176
// Plugin interfaces
177
interface IPlugin {
178
path?: string;
179
apply: Record<string, any>;
180
}
181
182
interface ApplyPluginsOpts {
183
key: string;
184
type: ApplyPluginsType;
185
initialValue?: any;
186
args?: object;
187
async?: boolean;
188
}
189
```