插件迁移#

迁移背景#

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。

常见问题解答#

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

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

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

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

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

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

总结#

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