Migrate Plugins to Umi 3

主要变更

注册方法异步化、参数对象化

// before
export default (api) => {
  api.registerCommand('build', {}, (args) => {
    api.applyPlugins('addBar', {
        ...
    })
  })
}

// after
export default (api) => {
  api.registerCommand({
    name: 'build',
    fn: async ({ args }) => {
      await api.applyPlugins({
        key: 'addBar',
        // 必填
        type: api.ApplyPluginsType.add,
        ...
      })
    }
  })
}

配置需要在插件端注册，不注册配置，用户端会进行报错

export default (api) => {
  // 用户项目配置 antd 才不会报错
  api.describe({
    key: 'antd',
    config: {
      // default: ,
      schema(joi) {
        return joi.object();
      },
    },
  })
}

入参由 string 改成 () ⇒ string

export default (api) => {
-  api.addEntryCode(`console.log('foo');`)
+  api.addEntryCode(() => `console.log('foo');`)
}

api.config 注册阶段为 null，如果需要在注册阶段获取，使用 api.userConfig

export default (api) => {
-  console.log(api.config) // => { ... }
+  console.log(api.config) // => null
+  console.log(api.service.userConfig) // => { ... }
   api.addHTMLScripts(() => {
      console.log(api.config);  // => { ... }
  });
}

api.addRendererWrapperWithModule 废弃，使用 api.addRuntimePlugin 方式注册：

import { join } from 'path';

export default function(api) {
  const {
    paths,
    utils: {
      Mustache,
    },
  } = api;

  api.onGenerateFiles(() => {
    api.writeTmpFile({
      path: `plugin-bar/runtime.tsx`,
      // 推荐使用 Mustache 渲染 tpl 方式
      content: `
        import React from 'react';
        const Wrapper = ({ children }) => <div>{children}</div>
        
        export function rootContainer(container) {
          return React.createElement(Wrapper, null, container);
        }
      `,
    })
  });

  api.addRuntimePlugin(() =>
    join(paths.absTmpPath || '', 'plugin-bar/runtime.tsx', 'runtime.tsx'),
  );
}

api.registerGenerator 参数从 { key : string; args: { Generator: Generator; resolved: string; }} 修改为 { args: { key : string; Generator: Generator; }}

// before
export default (api) => {
  api.registerGenerator('page', {
    Generator:  createPageGenerator({ api }),
    resolved: `${__dirname}/generators/page/index`,
  });
}

// after
export default (api) => {
  api.registerGenerator({
    key: 'page',
    // @ts-ignore
    Generator: createPageGenerator({ api }),
  });
}

api.findJS, api.findCSS 使用 api.getFile 代替：

// .ts
export default (api) => {
-  api.findJS('path')
+  api.getFile({ base: 'path', type: 'javascript', fileNameWithoutExt: '' })?.path

-  api.findJS('path', 'app')
+  api.getFile({ base: 'path', type: 'javascript', fileNameWithoutExt: 'app' })?.path

-  api.findCSS('path')
+  api.getFile({ base: 'path', type: 'css', fileNameWithoutExt: '' })?.path
}

API change

Name in 2.x	Name in 3.x	break change
chainWebpackConfig	chainWebpack	-
modifyWebpackConfig	chainWebpack	-
addPageWatcher	addTmpGenerateWatcherPaths	-
modifyHTMLWithAST	modifyHTML	-
addEntryImport	addEntryImports	-
addMiddlewareAhead	addBeforeMiddewares	-
registerPlugin	registerPlugins	-
addHTMLStyle	addHTMLStyles	-
addHTMLHeadScript	addHTMLHeadScripts	-
addHTMLScript	addHTMLScripts	-
addHTMLMeta	addHTMLMetas	-
addHTMLLink	addHTMLLinks	-
addEntryImport	addEntryImports	-
addEntryImportAhead	addEntryImportsAhead	-
log	logger	-
winPath	utils.winPath	-
_	utils.lodash	lodash
compatDirname	utils.compatDirname	TODO
onBuildSuccess	onBuildComplete	-
onBuildSuccessAsync	onBuildComplete	-
onBuildFail	onBuildComplete	-
getRouteComponents	TODO	-
debug	logger.debug	-