Plugin Migration#

Migration Background#

The Modern.js plugin system is constantly evolving. To provide a clearer API and more powerful features, we've optimized the definition and usage of Runtime plugins. While the old plugin syntax is still partially compatible, we strongly recommend migrating according to this guide to take full advantage of the new plugin system.

Migration Steps Overview#

1. Update Plugin Type Definition: Replace the Plugin type with RuntimePluginFuture.
2. Adjust Hook Invocation: Migrate from the return hooks pattern to direct api.xxx calls.
3. Replace Changed APIs: Refer to the detailed API mapping table and update your code.

Detailed Migration Steps#

Update Plugin Type Definition#

This is the first and most crucial step. It ensures that your plugin interacts correctly with the new plugin system.

// Old Syntax
import type { Plugin } from '@modern-js/runtime';

const plugin: Plugin = { ... };

// New Syntax
import type { RuntimePluginFuture } from '@modern-js/runtime';

const plugin: RuntimePluginFuture = { ... };

Explanation: The RuntimePluginFuture type is the standard definition for new plugins. It provides better type inference and a clearer API structure.

Adjust Hook Invocation#

The new plugin system recommends using the api object to directly call Hooks. This approach is more intuitive and easier to maintain.

// Old Syntax (return hooks)
{
  setup: () => ({
    beforeRender({ req, res }) { /*...*/ }
  })
}

// New Syntax (api.xxx)
{
  setup: api => {
    api.onBeforeRender(({ req, res }) => { /*...*/ })
  }
}

Explanation: The api object provides all available Hooks and utility methods.

Replace Changed APIs#

To maintain API consistency and clarity, we've adjusted the names of some APIs. Additionally, the hoc and init Hooks have been removed. Please use the new Hooks as replacements. The table below lists all changed APIs and their old and new counterparts:

Explanation:

• onBeforeRender replaces both the original beforeRender and init, used for pre-rendering logic and initialization, respectively.
• wrapRoot replaces hoc and is used to implement higher-order component functionality. It's crucial to pass props correctly when using wrapRoot.

wrapRoot Usage Example:

{
  setup: api => {
    api.wrapRoot((App) => {
      const AppWrapper = (props) => {
        // Ensure props are passed to the original component
        return <Provider value={xx}><App {...props}/></Provider>;
      };
      return AppWrapper;
    });
  }
}

Frequently Asked Questions#

Q: Will my plugin still work correctly after migration?

A: As long as you've correctly completed all the steps in this guide, your plugin should function properly. If you encounter any issues, please refer to the official Modern.js documentation or seek community support.

Q: Do I have to migrate my plugin immediately?

A: While the old plugin syntax remains partially compatible, we strongly recommend migrating as soon as possible. The new plugin system offers improved performance and richer functionality, making migration worthwhile in the long run.

Q: Where can I find more information about the new plugin system?

A: Please consult the official Modern.js documentation, especially the section on the plugin system. You can also refer to examples of other migrated plugins to understand best practices.

Summary#

With this detailed migration guide, we hope to help you smoothly transition your Runtime plugins to the new Modern.js plugin system. If you encounter any problems during the migration process, please don't hesitate to ask for assistance.