插件迁移

迁移背景

Modern.js 插件系统在不断演进,为了提供更清晰的 API 和更强大的功能,我们对 CLI 插件的定义和使用方式进行了优化。虽然旧版插件写法仍被兼容,但我们强烈建议您按照本指南进行迁移,以充分利用新版插件系统的优势。

迁移步骤总览

  1. 更新插件类型定义:将 CliPlugin 类型替换为 CliPluginFuture
  2. 调整 Hooks 调用方式:从 return hooks 模式迁移到 api.xxx 直接调用。
  3. 替换已变更的 API:参照详细的 API 映射表,更新您的代码。

详细迁移步骤

更新插件类型定义

这是迁移的第一步,也是最关键的一步。它确保您的插件能够与新版插件系统正确交互。

// 旧版写法
import type { CliPlugin, AppTools } from '@modern-js/app-tools';

const plugin: CliPlugin<AppTools<'shared'>> = { ... };

// 新版写法
import type { CliPluginFuture, AppTools } from '@modern-js/app-tools';

const plugin: CliPluginFuture<AppTools<'shared'>> = { ... };

说明: CliPluginFuture 类型是新版插件的标准定义,它带来了更好的类型推断和更清晰的 API 结构。

调整 Hooks 调用方式

新版插件系统推荐使用 api 对象直接调用 Hooks,这种方式更直观、更易于维护。

// 旧版写法 (return hooks)
{
  setup: () => ({
    commands({ program }) { /*...*/ }
  })
}

// 新版写法 (api.xxx)
{
  setup: api => {
    api.addCommand(({ program }) => { /*...*/ })
  }
}

说明: api 对象提供了所有可用的 Hooks 和工具方法。

替换已变更的 API

为了保持 API 的一致性和清晰性,我们对部分 API 的名称进行了调整。下表列出了所有变更的 API 及其新旧对应关系:

旧版 API新版 API说明
useAppContextgetAppContext获取应用上下文信息。
useConfigContextgetConfig获取用户配置文件中的配置。
useResolvedConfigContextgetNormalizedConfig获取经过插件处理后的最终配置。
beforeConfig(直接在 setup 中定义)不再需要单独的 beforeConfig Hook,直接在 setup 函数中编写相关逻辑即可。
prepareonPrepare运行主流程的前置准备阶段。
afterPrepareonAfterPrepare (不推荐)onPrepare 之后执行,但可能在未来版本中废弃。建议将逻辑合并到 onPrepare 中。
beforePrintInstructionsonBeforePrintInstructions在打印日志信息前执行。
commandsaddCommand添加新的 CLI 命令。
watchFilesaddWatchFiles添加需要监听的文件。
fileChangeonFileChanged监听文件变化事件。
beforeCreateCompileronBeforeCreateCompiler创建编译器前执行。
afterCreateCompileronAfterCreateCompiler创建编译器后执行。
beforeBuildonBeforeBuild构建前执行。
afterBuildonAfterBuild构建后执行。
beforeDevonBeforeDev运行 dev 命令前执行。
afterDevonDevCompileDonedev 命令编译完成后执行。
beforeExitonBeforeExit进程退出前执行。
htmlPartialsmodifyHtmlPartials修改 HTML 模板片段。

说明: 请务必仔细检查您的代码,确保所有旧版 API 都已替换为新版 API。

常见问题解答

Q: 迁移后,我的插件还能正常工作吗?

A: 只要您按照本指南正确完成了所有步骤,您的插件应该能够正常工作。如果您遇到任何问题,请查阅 Modern.js 的官方文档或寻求社区支持。

Q: 我必须立即迁移我的插件吗?

A: 虽然旧版插件写法仍然兼容,但我们强烈建议您尽快迁移。新版插件系统提供了更好的性能和更丰富的功能,长期来看,迁移是值得的。

Q: 我可以在哪里找到更多关于新版插件系统的信息?

A: 请查阅 Modern.js 的官方文档,特别是关于插件系统的部分。您也可以参考其他已迁移的插件示例,了解最佳实践。

总结

通过这份详细的迁移指南,我们希望能够帮助您顺利地将您的 CLI 插件迁移到 Modern.js 的新版插件系统。如果您在迁移过程中遇到任何问题,请随时向我们寻求帮助。