插件迁移#

迁移背景#

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

迁移步骤总览#

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

详细迁移步骤#

更新插件类型定义#

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

// 旧版写法
import type { Plugin } from '@modern-js/runtime';

const plugin: Plugin = { ... };

// 新版写法
import type { RuntimePluginFuture } from '@modern-js/runtime';

const plugin: RuntimePluginFuture = { ... };

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

调整 Hooks 调用方式#

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

// 旧版写法 (return hooks)
{
  setup: () => ({
    beforeRender({ req, res }) { /*...*/ }
  })
}

// 新版写法 (api.xxx)
{
  setup: api => {
    api.onBeforeRender(({ req, res }) => { /*...*/ })
  }
}

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

替换已变更的 API#

为了保持 API 的一致性和清晰性，我们对部分 API 的名称进行了调整。同时，hoc 和 init 这两个 Hook 已被移除，请使用新的 Hook 进行替代。下表列出了所有变更的 API 及其新旧对应关系：

说明：

• onBeforeRender 替代了原来的 beforeRender 和 init，分别用于渲染前逻辑和初始化。
• wrapRoot 替代了 hoc，用于实现高阶组件功能，使用时务必注意 props 的传递。

wrapRoot 使用示例：

{
  setup: api => {
    api.wrapRoot((App) => {
      const AppWrapper = (props) => {
        // 确保将 props 传递给原始组件
        return <Provider value={xx}><App {...props}/></Provider>;
      };
      return AppWrapper;
    });
  }
}

常见问题解答#

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

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

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

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

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

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

总结#

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