Plugin Development

/**
 * Main plugin API interface providing comprehensive access to Umi's plugin system
 */
interface IApi {
  // System level variables
  API_TYPE: typeof API_TYPE;
  config: IConfig;
  cwd: string;
  pkg: IPkg;
  webpackConfig: IWebpack.Configuration;
  service: any;
  locale: any;
  paths: {
    cwd: string;
    outputPath: string;
    absOutputPath: string;
    absNodeModulesPath: string;
    pagesPath: string;
    absPagesPath: string;
    absSrcPath: string;
    tmpDirPath: string;
    absTmpDirPath: string;
  };
  routes: IRoute[];

  // System level API
  register: IRegister;
  registerPlugin: IRegisterPlugin;
  registerMethod: IRegisterMethod;
  applyPlugins: IApplyPlugins;
  restart: IReDo<string>;
  rebuildTmpFiles: IReDo<string>;
  refreshBrowser: IReDo<void>;
  rebuildHTML: IReDo<void>;
  changePluginOption: IChangePluginOption;
  registerCommand: IRegisterCommand;
  _registerConfig: IRegisterConfig;
  _modifyCommand: IModifyCommand;
  _modifyHelpInfo: IModify<IModifyHelpInfoOpts>;

  // Tool class API
  log: { [key in DefaultMethods]: ILog<any> };
  _: typeof lodash;
  winPath: IWinPath;
  relativeToTmp: IRelativeToTmp;
  debug: ILog;
  writeTmpFile: IWriteTmpFile;
  getRoutes: IGetRoutes;
  getRouteComponents: IGetRouteComponents;
  findJS: IFind;
  findCSS: IFind;
  compatDirname: ICompatDirname;
  UmiError: any;

  // Event class API
  beforeDevServer: IBeforeDevServer;
  _beforeDevServerAsync: IBeforeDevServerAsync;
  afterDevServer: IAfterDevServer;
  beforeBlockWriting: IBeforeBlockWriting;
  onStart: IOnStart;
  onPrintUmiError: onPrintUmiError;
  onStartAsync: IEventAsync;
  onDevCompileDone: IOnDevCompileDone;
  onOptionChange: IOnOptionChange;
  onBuildSuccess: IOnBuildSuccess;
  onBuildSuccessAsync: IOnBuildSuccessAsync;
  onBuildFail: IOnBuildFail;
  onHTMLRebuild: IOnHTMLRebuild;
  onGenerateFiles: IOnGenerateFiles;
  onPatchRoute: IOnPatchRoute;
  onUISocket: IOnUISocket;
  onRouteChange: (callback: () => void) => void;

  // Application class API
  modifyDefaultConfig: IModify<object>;
  addUmiExports: IAdd<object>;
  addPageWatcher: IAdd<string>;
  addHTMLMeta: IAdd<object, { route?: IRoute }>;
  addHTMLLink: IAdd<object, { route?: IRoute }>;
  addHTMLStyle: IAdd<object, { route?: IRoute }>;
  addHTMLScript: IAdd<object, { route?: IRoute }>;
  addHTMLHeadScript: IAdd<object, { route?: IRoute }>;
  modifyHTMLChunks: IModify<string[], { route?: IRoute }>;
  modifyHTMLWithAST: IModifyHTMLWithAST;
  modifyHTMLContext: IModify<object, { route?: IRoute }>;
  modifyPublicPathStr: IModify<string>;
  modifyRoutes: IModify<IRoute[]>;
  addEntryImportAhead: IAdd<IAddImportOpts>;
  addEntryPolyfillImports: IAdd<IAddImportOpts>;
  addEntryImport: IAdd<IAddImportOpts>;
  addEntryCodeAhead: IAdd<string>;
  addEntryCode: IAdd<string>;
  addUIPlugin: IAdd<string>;
  addRouterImport: IAdd<IAddImportOpts>;
  addRouterImportAhead: IAdd<IAddImportOpts>;
  addRendererWrapperWithComponent: IAdd<string, () => string>;
  addRendererWrapperWithModule: IAdd<string>;
  modifyEntryRender: IModify<string>;
  modifyEntryHistory: IModify<string>;
  modifyRouteComponent: IModify<string, IModifyRouteComponentArgs>;
  modifyRouterRootComponent: IModify<string>;
  modifyWebpackConfig: IModify<IWebpack.Configuration>;
  modifyAFWebpackOpts: IModify<IAFWebpackConfig>;
  chainWebpackConfig: IChangeWebpackConfig<IWebpackChainConfig, IAFWebpackConfig>;
  addMiddleware: IAdd<IMiddlewareFunction>;
  addMiddlewareAhead: IAdd<IMiddlewareFunction>;
  addMiddlewareBeforeMock: IAdd<IMiddlewareFunction>;
  addMiddlewareAfterMock: IAdd<IMiddlewareFunction>;
  addVersionInfo: IAdd<string>;
  addRuntimePlugin: IAdd<string>;
  addRuntimePluginKey: IAdd<string>;
  addBlockUIResource: IAdd<object>;
  modifyBlockUIResources: IModify<object[]>;
  _modifyBlockPackageJSONPath: IModify<string>;
  _modifyBlockDependencies: IModify<IBlockDependencies>;
  _modifyBlockFile: IModify<string, IModifyBlockFileArgs>;
  _modifyBlockTarget: IModify<string, IModifyBlockTargetArgs>;
  _modifyBlockNewRouteConfig: IModify<any>;
}

import { IApi } from 'umi-types';

export default function(api: IApi) {
  // Access system information
  console.log('Current working directory:', api.cwd);
  console.log('Output path:', api.paths.absOutputPath);
  console.log('Routes:', api.getRoutes());

  // Register a command
  api.registerCommand('build-custom', {
    description: 'Build with custom settings',
    usage: 'umi build-custom [options]',
    webpack: true,
  }, (args) => {
    api.log.info('Building with custom settings...');
    // Custom build logic
  });

  // Modify webpack configuration
  api.modifyWebpackConfig((config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@components': api.winPath(`${api.paths.absSrcPath}/components`),
    };
    return config;
  });

  // Add HTML modifications
  api.modifyHTMLWithAST(($, { route, getChunkPath }) => {
    if (route.path === '/') {
      $('head').append('<meta name="home-page" content="true">');
    }
  });
}

/**
 * Register a hook handler for a specific hook
 * @param hook - Hook name to listen for
 * @param handler - Function to handle the hook
 */
interface IRegister {
  (hook: string, handler: Function): void;
}

/**
 * Register a plugin with the system
 * @param plugin - Plugin registration options
 */
interface IRegisterPlugin {
  (plugin: IRegisterPluginOpts): void;
}

interface IRegisterPluginOpts {
  id: string;
  apply: any;
  opts?: object;
}

/**
 * Register a new plugin method
 * @param methodName - Name of the method to register
 * @param opts - Method registration options
 */
interface IRegisterMethod {
  (methodName: string, opts: IRegisterMethodOpts): void;
}

interface IRegisterMethodOpts {
  type?: API_TYPE;
  apply?: IPluginMethod;
}

/**
 * Apply all registered plugins for a method
 * @param methodName - Method name to apply plugins for
 * @param opts - Options for plugin application
 */
interface IApplyPlugins {
  (methodName: string, opts?: IApplyPluginsOpts): any[] | undefined | any;
}

interface IApplyPluginsOpts {
  args?: any;
  initialValue?: any;
}

/**
 * Register a CLI command
 * @param commandName - Name of the command
 * @param opts - Command options or handler function
 * @param fn - Command handler function (when opts provided)
 */
interface IRegisterCommand {
  (commandName: string, opts: ICommandOpts, fn: (args: any) => any): void;
  (commandName: string, fn: (args: any) => any): void;
}

interface ICommandOpts {
  description?: string;
  details?: string;
  hide?: boolean;
  options?: object;
  usage?: string;
  webpack?: boolean;
}

/**
 * Logging interface with different log levels
 */
interface ILog<T = string> {
  (message: T, ...messages: string[]): void;
}

/**
 * Write a temporary file to the temp directory
 * @param file - Relative file path
 * @param content - File content
 */
interface IWriteTmpFile {
  (file: string, content: string): void;
}

/**
 * Get current route configuration
 * @returns Array of route objects
 */
interface IGetRoutes {
  (): IRoute[];
}

/**
 * Get route component paths
 * @returns Array of component file paths
 */
interface IGetRouteComponents {
  (): string[];
}

/**
 * Convert path to Windows-compatible format
 * @param path - File path to convert
 * @returns Windows-compatible path
 */
interface IWinPath {
  (path: string): string;
}

/**
 * Make path relative to temp directory
 * @param path - Absolute path
 * @returns Path relative to temp directory
 */
type IRelativeToTmp = (path: string) => string;

/**
 * Find JavaScript file in directory
 * @param baseDir - Directory to search in
 * @param fileNameWithoutExtname - File name without extension
 * @returns File path or null if not found
 */
interface IFind {
  (baseDir: string, fileNameWithoutExtname?: string): string | null;
}

/**
 * Get compatible directory name
 * @param path - Path to process
 * @param cwd - Current working directory
 * @param fallback - Fallback value
 * @returns Compatible directory name or fallback
 */
interface ICompatDirname<T = any> {
  (path: string, cwd: string, fallback?: T): T | string;
}

/**
 * Before dev server start event handler
 * @param fn - Event handler function
 */
interface IBeforeDevServer {
  (fn: IBeforeDevServerFunc): void;
}

interface IBeforeDevServerFunc {
  (args: { server: any }): void;
}

/**
 * After dev server start event handler
 * @param fn - Event handler function
 */
interface IAfterDevServer {
  (fn: IAfterDevServerFunc): void;
}

interface IAfterDevServerFunc {
  (args: { server: any; devServerPort: number }): void;
}

/**
 * On dev compilation complete event handler
 * @param fn - Event handler function
 */
interface IOnDevCompileDone {
  (fn: IOnDevCompileDoneFunc): void;
}

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

/**
 * On build success event handler
 * @param fn - Event handler function
 */
interface IOnBuildSuccess {
  (fn: IOnBuildSuccessFunc): void;
}

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

/**
 * On build failure event handler
 * @param fn - Event handler function
 */
interface IOnBuildFail {
  (fn: IOnBuildFailFunc): void;
}

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

/**
 * On option change event handler
 * @param fn - Event handler function
 */
interface IOnOptionChange {
  (fn: IOnOptionChangeFunc): void;
}

interface IOnOptionChangeFunc<T = any> {
  (newOpts: T): void;
}

/**
 * On generate files event handler
 * @param fn - Event handler function
 */
interface IOnGenerateFiles {
  (fn: IOnGenerateFilesFunc): void;
}

interface IOnGenerateFilesFunc {
  (args: { isRebuild?: boolean }): void;
}

/**
 * On patch route event handler
 * @param fn - Event handler function
 */
interface IOnPatchRoute {
  (fn: IOnPatchRouteFunc): void;
}

interface IOnPatchRouteFunc {
  (args: { route: IRoute }): void;
}

/**
 * Generic modify function for plugin methods
 * @param memo - Current value to modify
 * @param args - Additional arguments
 * @returns Modified value
 */
interface IModifyFunc<T, U> {
  (memo: T, args: U): T | T;
}

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

/**
 * Generic add function for plugin methods
 * @param memo - Current array to add to
 * @param args - Additional arguments
 * @returns Item or array of items to add
 */
interface IAddFunc<T, U> {
  (memo: T[], args: U): T | T[];
}

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

/**
 * Modify HTML using CheerioJS AST
 * @param fn - HTML modification function
 */
interface IModifyHTMLWithAST {
  (fn: IModifyHTMLWithASTFunc): void;
}

interface IModifyHTMLWithASTFunc {
  ($: CheerioStatic, args: IModifyHTMLWithASTArgs): CheerioStatic;
}

interface IModifyHTMLWithASTArgs {
  route: IRoute;
  getChunkPath: IGetChunkPath;
}

interface IGetChunkPath {
  (fileName: string): string | null;
}

/**
 * Add import statement options
 */
interface IAddImportOpts {
  source: string;
  specifier?: string;
}

/**
 * Middleware function for express-like middleware
 */
interface IMiddlewareFunction {
  (req: any, res: any, next: any): void;
}