0
# Umi Types
1

2
Umi Types provides comprehensive TypeScript type definitions for the Umi framework, a React-based frontend development framework. It enables full type safety and IntelliSense support for Umi plugin development, configuration, UI components, routing, webpack configuration, and internationalization.
3

4
## Package Information
5

6
- **Package Name**: umi-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install umi-types`
10

11
## Core Imports
12

13
```typescript
14
import { IApi } from 'umi-types';
15
```
16

17
For configuration types:
18

19
```typescript
20
import { IConfig, IPlugin, IRoute } from 'umi-types';
21
```
22

23
For UI development:
24

25
```typescript
26
import { IUi } from 'umi-types';
27
```
28

29
For internationalization:
30

31
```typescript
32
import { IApi, IModifyHTMLWithASTFunc } from 'umi-types';
33
```
34

35
## Basic Usage
36

37
The most common usage is for plugin development using the main IApi interface:
38

39
```typescript
40
import { IApi } from 'umi-types';
41

42
export default function(api: IApi) {
43
  // Register a new command
44
  api.registerCommand('my-command', {
45
    description: 'My custom command',
46
    usage: 'umi my-command [options]',
47
  }, (args) => {
48
    api.log.success('Command executed successfully');
49
  });
50

51
  // Modify webpack configuration
52
  api.modifyWebpackConfig((config) => {
53
    config.resolve.alias = {
54
      ...config.resolve.alias,
55
      '@': api.paths.absSrcPath,
56
    };
57
    return config;
58
  });
59

60
  // Add HTML modifications
61
  api.modifyHTMLWithAST(($, { route, getChunkPath }) => {
62
    $('head').append(`<script src="${getChunkPath('custom.js')}"></script>`);
63
  });
64
}
65
```
66

67
## Architecture
68

69
Umi Types is organized around several key areas:
70

71
- **Plugin API**: Core `IApi` interface providing system-level, tool, event, and application APIs
72
- **Configuration System**: Type definitions for Umi and webpack configuration options
73
- **UI Framework**: Components and interfaces for Umi's plugin UI system
74
- **Type System**: Complete TypeScript definitions with generic type preservation
75
- **Event System**: Lifecycle hooks and event handlers for plugin development
76

77
## Capabilities
78

79
### Plugin Development API
80

81
Core plugin development interface providing system-level APIs, tool utilities, event handlers, and application modification methods. Essential for all Umi plugin development.
82

83
```typescript { .api }
84
interface IApi {
85
  // System level variables
86
  API_TYPE: typeof API_TYPE;
87
  config: IConfig;
88
  cwd: string;
89
  pkg: IPkg;
90
  webpackConfig: IWebpack.Configuration;
91
  service: any;
92
  locale: any;
93
  paths: {
94
    cwd: string;
95
    outputPath: string;
96
    absOutputPath: string;
97
    absNodeModulesPath: string;
98
    pagesPath: string;
99
    absPagesPath: string;
100
    absSrcPath: string;
101
    tmpDirPath: string;
102
    absTmpDirPath: string;
103
  };
104
  routes: IRoute[];
105

106
  // System level API methods
107
  register: IRegister;
108
  registerPlugin: IRegisterPlugin;
109
  registerMethod: IRegisterMethod;
110
  applyPlugins: IApplyPlugins;
111
  restart: IReDo<string>;
112
  rebuildTmpFiles: IReDo<string>;
113
  refreshBrowser: IReDo<void>;
114
  rebuildHTML: IReDo<void>;
115
  changePluginOption: IChangePluginOption;
116
  registerCommand: IRegisterCommand;
117
  _registerConfig: IRegisterConfig;
118
  _modifyCommand: IModifyCommand;
119
  _modifyHelpInfo: IModify<IModifyHelpInfoOpts>;
120

121
  // Tool class API methods
122
  log: { [key in DefaultMethods]: ILog<any> };
123
  _: typeof lodash;
124
  winPath: IWinPath;
125
  relativeToTmp: IRelativeToTmp;
126
  debug: ILog;
127
  writeTmpFile: IWriteTmpFile;
128
  getRoutes: IGetRoutes;
129
  getRouteComponents: IGetRouteComponents;
130
  findJS: IFind;
131
  findCSS: IFind;
132
  compatDirname: ICompatDirname;
133
  UmiError: any;
134

135
  // Event class API methods  
136
  beforeDevServer: IBeforeDevServer;
137
  _beforeDevServerAsync: IBeforeDevServerAsync;
138
  afterDevServer: IAfterDevServer;
139
  beforeBlockWriting: IBeforeBlockWriting;
140
  onStart: IOnStart;
141
  onPrintUmiError: onPrintUmiError;
142
  onStartAsync: IEventAsync;
143
  onDevCompileDone: IOnDevCompileDone;
144
  onOptionChange: IOnOptionChange;
145
  onBuildSuccess: IOnBuildSuccess;
146
  onBuildSuccessAsync: IOnBuildSuccessAsync;
147
  onBuildFail: IOnBuildFail;
148
  onHTMLRebuild: IOnHTMLRebuild;
149
  onGenerateFiles: IOnGenerateFiles;
150
  onPatchRoute: IOnPatchRoute;
151
  onUISocket: IOnUISocket;
152
  onRouteChange: (callback: () => void) => void;
153

154
  // Application class API methods
155
  modifyDefaultConfig: IModify<object>;
156
  addUmiExports: IAdd<object>;
157
  addPageWatcher: IAdd<string>;
158
  addHTMLMeta: IAdd<object, { route?: IRoute }>;
159
  addHTMLLink: IAdd<object, { route?: IRoute }>;
160
  addHTMLStyle: IAdd<object, { route?: IRoute }>;
161
  addHTMLScript: IAdd<object, { route?: IRoute }>;
162
  addHTMLHeadScript: IAdd<object, { route?: IRoute }>;
163
  modifyHTMLChunks: IModify<string[], { route?: IRoute }>;
164
  modifyHTMLWithAST: IModifyHTMLWithAST;
165
  modifyHTMLContext: IModify<object, { route?: IRoute }>;
166
  modifyPublicPathStr: IModify<string>;
167
  modifyRoutes: IModify<IRoute[]>;
168
  addEntryImportAhead: IAdd<IAddImportOpts>;
169
  addEntryPolyfillImports: IAdd<IAddImportOpts>;
170
  addEntryImport: IAdd<IAddImportOpts>;
171
  addEntryCodeAhead: IAdd<string>;
172
  addEntryCode: IAdd<string>;
173
  addUIPlugin: IAdd<string>;
174
  addRouterImport: IAdd<IAddImportOpts>;
175
  addRouterImportAhead: IAdd<IAddImportOpts>;
176
  addRendererWrapperWithComponent: IAdd<string, () => string>;
177
  addRendererWrapperWithModule: IAdd<string>;
178
  modifyEntryRender: IModify<string>;
179
  modifyEntryHistory: IModify<string>;
180
  modifyRouteComponent: IModify<string, IModifyRouteComponentArgs>;
181
  modifyRouterRootComponent: IModify<string>;
182
  modifyWebpackConfig: IModify<IWebpack.Configuration>;
183
  modifyAFWebpackOpts: IModify<IAFWebpackConfig>;
184
  chainWebpackConfig: IChangeWebpackConfig<IWebpackChainConfig, IAFWebpackConfig>;
185
  addMiddleware: IAdd<IMiddlewareFunction>;
186
  addMiddlewareAhead: IAdd<IMiddlewareFunction>;
187
  addMiddlewareBeforeMock: IAdd<IMiddlewareFunction>;
188
  addMiddlewareAfterMock: IAdd<IMiddlewareFunction>;
189
  addVersionInfo: IAdd<string>;
190
  addRuntimePlugin: IAdd<string>;
191
  addRuntimePluginKey: IAdd<string>;
192
  addBlockUIResource: IAdd<object>;
193
  modifyBlockUIResources: IModify<object[]>;
194
  _modifyBlockPackageJSONPath: IModify<string>;
195
  _modifyBlockDependencies: IModify<IBlockDependencies>;
196
  _modifyBlockFile: IModify<string, IModifyBlockFileArgs>;
197
  _modifyBlockTarget: IModify<string, IModifyBlockTargetArgs>;
198
  _modifyBlockNewRouteConfig: IModify<any>;
199
}
200
```
201

202
[Plugin Development](./plugin-development.md)
203

204
### Configuration Types
205

206
Type definitions for Umi configuration options, webpack settings, routing, and plugin configuration. Provides complete type safety for umi configuration files.
207

208
```typescript { .api }
209
interface IConfig extends IAFWebpackConfig {
210
  // Basic config options
211
  block?: object;
212
  chainWebpack?: IChangeWebpackConfigFunc<IWebpackChainConfig, IAFWebpackConfig>;
213
  context?: object;
214
  disableRedirectHoist?: boolean;
215
  exportStatic?: boolean | IExportStaticOpts;
216
  outputPath?: string;
217
  plugins?: IPlugin[];
218
  routes?: IRoute[] | null;
219
  runtimePublicPath?: boolean | string;
220
  singular?: boolean;
221
  mock?: IMockOpts;
222
  treeShaking?: boolean;
223
  dva?: any;
224
  locale?: any;
225

226
  // Plugin-implemented options
227
  base?: string;
228
  history?: 'browser' | 'hash' | 'memory';
229
  mountElementId?: string;
230
  targets?: {
231
    [key: string]: number;
232
  };
233
  ssr?: IExportSSROpts;
234
}
235

236
type IPlugin<T = any> = string | [string, T];
237

238
interface IRoute {
239
  path?: string;
240
  component?: ReactNode;
241
  routes?: IRoute[];
242
  Routes?: string[];
243
  redirect?: string;
244
  [key: string]: any;
245
}
246
```
247

248
[Configuration](./configuration.md)
249

250
### UI Components and Dashboard
251

252
UI system types for Umi's plugin dashboard, panels, forms, and components. Used for developing Umi UI plugins and dashboard extensions.
253

254
```typescript { .api }
255
interface IPanel extends IRoute {
256
  path: string;
257
  component: FunctionComponent | ComponentClass;
258
  icon: IconType | string;
259
  actions?: IPanelAction;
260
  beta?: boolean;
261
  headerTitle?: ReactNode;
262
  renderTitle?: (title: string) => ReactNode;
263
}
264

265
interface IDashboard {
266
  key: string;
267
  enable?: boolean;
268
  title: ReactNode;
269
  description: ReactNode;
270
  icon: ReactNode;
271
  right?: ReactNode;
272
  colClassName?: string;
273
  backgroundColor?: string;
274
  content: ReactNode | ReactNode[];
275
}
276

277
class IApiClass {
278
  addPanel: IAddPanel;
279
  addDashboard: IAddDashboard;
280
  TwoColumnPanel: FC<ITwoColumnPanel>;
281
  Terminal: FC<ITerminalProps>;
282
  DirectoryForm: FC<IDirectoryForm>;
283
  StepForm: IStepForm;
284
  ConfigForm: FC<IConfigFormProps>;
285
  Field: FC<IFieldProps>;
286
}
287
```
288

289
[UI Components](./ui-components.md)
290

291
### Internationalization
292

293
React Intl type definitions and locale management functions for multi-language Umi applications. Provides formatting components and utility functions.
294

295
```typescript { .api }
296
// Formatting functions
297
function formatMessage(
298
  messageDescriptor: MessageDescriptor,
299
  values?: { [key: string]: MessageValue }
300
): string;
301

302
function formatDate(value: DateSource, options?: DateTimeFormatProps): string;
303
function formatTime(value: DateSource, options?: DateTimeFormatProps): string;
304
function formatNumber(value: number, options?: FormattedNumberProps): string;
305

306
// Locale management
307
function setLocale(lang: string, reloadPage?: boolean): void;
308
function getLocale(): string;
309

310
// React components
311
class FormattedMessage extends React.Component<FormattedMessageProps> {}
312
class FormattedDate extends React.Component<FormattedDateProps> {}
313
class FormattedTime extends React.Component<FormattedTimeProps> {}
314
class FormattedNumber extends React.Component<FormattedNumberProps> {}
315
```
316

317
[Internationalization](./internationalization.md)
318

319
## Types
320

321
### Core Plugin Types
322

323
```typescript { .api }
324
enum API_TYPE {
325
  ADD,
326
  MODIFY,
327
  EVENT,
328
}
329

330
interface IPluginMethodOpts {
331
  memo?: any;
332
  args?: any;
333
}
334

335
interface IPluginMethod {
336
  (opts: IPluginMethodOpts, ...args: any[]): any;
337
}
338

339
interface IRegisterMethodOpts {
340
  type?: API_TYPE;
341
  apply?: IPluginMethod;
342
}
343

344
interface IApplyPluginsOpts {
345
  args?: any;
346
  initialValue?: any;
347
}
348

349
interface ICommandOpts {
350
  description?: string;
351
  details?: string;
352
  hide?: boolean;
353
  options?: object;
354
  usage?: string;
355
  webpack?: boolean;
356
}
357

358
interface IPkg {
359
  name?: string;
360
  version?: string;
361
  dependencies?: {
362
    [prop: string]: string;
363
  };
364
  devDependencies?: {
365
    [prop: string]: string;
366
  };
367
}
368

369
interface IRegisterPluginOpts {
370
  id: string;
371
  apply: any;
372
  opts?: object;
373
}
374

375
interface IModifyHelpInfoOpts {
376
  scriptName: string;
377
  commands: {
378
    [commandName: string]: {
379
      opts: {
380
        hide: boolean;
381
        options: {
382
          [key: string]: string;
383
        };
384
      };
385
    };
386
  };
387
}
388

389
interface IAddImportOpts {
390
  source: string;
391
  specifier?: string;
392
}
393

394
interface IModifyRouteComponentArgs {
395
  importPath: string;
396
  webpackChunkName: string;
397
  component: string;
398
}
399

400
interface IBlockDependencies {
401
  conflicts: [string, string, string][];
402
  lacks: [string, string][];
403
  devConflicts: [string, string, string][];
404
  devLacks: [string, string][];
405
}
406

407
interface IModifyBlockFileArgs {
408
  targetPath: string;
409
}
410

411
interface IModifyBlockTargetArgs {
412
  sourceName: string;
413
}
414

415
interface IMiddlewareFunction {
416
  (req: any, res: any, next: any): void;
417
}
418
```
419

420
### Function Interface Types
421

422
```typescript { .api }
423
interface IRegister {
424
  (hook: string, handler: Function): void;
425
}
426

427
interface IRegisterPlugin {
428
  (plugin: IRegisterPluginOpts): void;
429
}
430

431
interface IRegisterMethod {
432
  (methodName: string, opts: IRegisterMethodOpts): void;
433
}
434

435
interface IApplyPlugins {
436
  (methodName: string, opts?: IApplyPluginsOpts): any[] | undefined | any;
437
}
438

439
interface IRegisterCommand {
440
  (commandName: string, opts: ICommandOpts, fn: (args: any) => any): void;
441
  (commandName: string, fn: (args: any) => any): void;
442
}
443

444
interface IReDo<T> {
445
  (message?: T): void;
446
}
447

448
interface IChangePluginOption {
449
  (pluginId: string, opts: any): void;
450
}
451

452
interface IRegisterConfig {
453
  (fn: IRegisterConfigFunc): void;
454
}
455

456
interface IRegisterConfigFunc {
457
  (api: IApi): IRegisterConfigOpts;
458
}
459

460
interface IRegisterConfigOpts<T = any> {
461
  name: string;
462
  validate?: (value: T) => void;
463
  onChange?: (newConfig: IConfig, oldConfig: IConfig) => void;
464
}
465

466
interface IModifyCommand {
467
  (fn: IModifyCommandFunc): void;
468
}
469

470
interface IModifyCommandFunc {
471
  (opts: IModifyCommandFuncOpts): IModifyCommandFuncOpts;
472
}
473

474
interface IModifyCommandFuncOpts {
475
  name: string;
476
  args?: any;
477
}
478
```
479

480
### Tool Class API Types
481

482
```typescript { .api }
483
interface ILog<T = string> {
484
  (message: T, ...messages: string[]): void;
485
}
486

487
interface IWriteTmpFile {
488
  (file: string, content: string): void;
489
}
490

491
interface IGetRoutes {
492
  (): IRoute[];
493
}
494

495
interface IGetRouteComponents {
496
  (): string[];
497
}
498

499
interface IWinPath {
500
  (path: string): string;
501
}
502

503
type IRelativeToTmp = (path: string) => string;
504

505
interface IFind {
506
  (baseDir: string, fileNameWithoutExtname?: string): string | null;
507
}
508

509
interface ICompatDirname<T = any> {
510
  (path: string, cwd: string, fallback?: T): T | string;
511
}
512
```
513

514
### Event Class API Types
515

516
```typescript { .api }
517
interface IBeforeDevServerFunc {
518
  (args: { server: any }): void;
519
}
520

521
interface IAfterDevServerFunc {
522
  (args: { server: any; devServerPort: number }): void;
523
}
524

525
interface IBeforeBlockWritingFunc {
526
  (args: { service: any; sourcePath: string; blockPath: string }): void;
527
}
528

529
interface IBeforeDevServer {
530
  (fn: IBeforeDevServerFunc): void;
531
}
532

533
interface IBeforeDevServerAsync {
534
  (fn: IBeforeDevServerFunc): Promise<any>;
535
}
536

537
interface IAfterDevServer {
538
  (fn: IAfterDevServerFunc): void;
539
}
540

541
interface IBeforeBlockWriting {
542
  (fn: IBeforeBlockWritingFunc): void;
543
}
544

545
interface IOnStart {
546
  (fn: () => void): void;
547
}
548

549
interface onPrintUmiError {
550
  (args: { error: any; opts: object }): void;
551
}
552

553
interface IEventAsync {
554
  (fn: () => void): Promise<any>;
555
}
556

557
interface IOnDevCompileDoneFunc {
558
  (args: { isFirstCompile: boolean; stats: IWebpack.Stats }): void;
559
}
560

561
interface IOnDevCompileDone {
562
  (fn: IOnDevCompileDoneFunc): void;
563
}
564

565
interface IOnOptionChangeFunc<T = any> {
566
  (newOpts: T): void;
567
}
568

569
interface IOnOptionChange {
570
  (fn: IOnOptionChangeFunc): void;
571
}
572

573
interface IOnBuildSuccessFunc {
574
  (args: { stats: IWebpack.Stats[] }): void;
575
}
576

577
interface IOnBuildSuccess {
578
  (fn: IOnBuildSuccessFunc): void;
579
}
580

581
interface IOnBuildSuccessAsync {
582
  (fn: IOnBuildSuccessFunc): Promise<any>;
583
}
584

585
interface IOnBuildFailFunc {
586
  (args: { stats: IWebpack.Stats[]; err: Error }): void;
587
}
588

589
interface IOnBuildFail {
590
  (fn: IOnBuildFailFunc): void;
591
}
592

593
interface IOnHTMLRebuild {
594
  (fn: () => void): void;
595
}
596

597
interface IOnGenerateFilesFunc {
598
  (args: { isRebuild?: boolean }): void;
599
}
600

601
interface IOnGenerateFiles {
602
  (fn: IOnGenerateFilesFunc): void;
603
}
604

605
interface IOnPatchRouteFunc {
606
  (args: { route: IRoute }): void;
607
}
608

609
interface IOnPatchRoute {
610
  (fn: IOnPatchRouteFunc): void;
611
}
612

613
interface IOnUISocketFunc {
614
  (args: {
615
    action: IAction;
616
    send: ISend;
617
    success: ISuccess<{}>;
618
    failure: IFailure<{}>;
619
    log: IUiLog;
620
  }): void;
621
}
622

623
interface IOnUISocket {
624
  (fn: IOnUISocketFunc): void;
625
}
626
```
627

628
### Application Class API Types
629

630
```typescript { .api }
631
interface IModifyFunc<T, U> {
632
  (memo: T, args: U): T | T;
633
}
634

635
interface IModify<T, U = {}> {
636
  (fn: IModifyFunc<T, U> | T): void;
637
}
638

639
interface IAddFunc<T, U> {
640
  (memo: T[], args: U): T | T[];
641
}
642

643
interface IAdd<T, U = {}> {
644
  (fn: IAddFunc<T, U> | T | T[]): void;
645
}
646

647
interface IChangeWebpackConfigFunc<T, U> {
648
  (webpackConfig: T, AFWebpack: { webpack: U }): T | void;
649
}
650

651
interface IChangeWebpackConfig<T, U> {
652
  (fn: IChangeWebpackConfigFunc<T, U>): void;
653
}
654

655
interface IGetChunkPath {
656
  (fileName: string): string | null;
657
}
658

659
interface IModifyHTMLWithASTArgs {
660
  route: IRoute;
661
  getChunkPath: IGetChunkPath;
662
}
663

664
interface IModifyHTMLWithASTFunc {
665
  ($: CheerioStatic, args: IModifyHTMLWithASTArgs): CheerioStatic;
666
}
667

668
interface IModifyHTMLWithAST {
669
  (fn: IModifyHTMLWithASTFunc): void;
670
}
671

672
// UI Socket Types
673
interface IAction<T = object> {
674
  type: string;
675
  payload?: T;
676
  lang?: IUi.ILang;
677
}
678

679
type ISend = (action: IAction<{}>) => void;
680
type ISuccess<T = object> = (payload: T) => void;
681
type IFailure<T = object> = (payload: T) => void;
682
type IUiLogType = 'error' | 'info';
683
type IUiLog = (type: IUiLogType, payload: string) => void;
684
```