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
```