Guide
Config
Plugin
API
Tutorials
Community
Guide
Config
Plugin
API
Tutorials
Community

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 CLI plugins. While the old plugin syntax is still supported for compatibility, 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 CliPlugin type with CliPluginFuture.
  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 of the migration. It ensures that your plugin interacts correctly with the new plugin system.

// Old Syntax
import type { CliPlugin, AppTools } from '@modern-js/app-tools';

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

// New Syntax
import type { CliPluginFuture, AppTools } from '@modern-js/app-tools';

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

Explanation: The CliPluginFuture type is the standard definition for new plugins, providing 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: () => ({
    commands({ program }) { /*...*/ }
  })
}

// New Syntax (api.xxx)
{
  setup: api => {
    api.addCommand(({ program }) => { /*...*/ })
  }
}

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. The following table lists all changed APIs and their old and new counterparts:

Old API New API Description
useAppContext getAppContext Gets the application context information.
useConfigContext getConfig Gets the configuration defined in the user's configuration file.
useResolvedConfigContext getNormalizedConfig Gets the final configuration after processing by plugins.
beforeConfig (Defined directly in setup) The beforeConfig Hook is no longer needed. Write related logic directly in the setup function.
prepare onPrepare The preparation stage before running the main process.
afterPrepare onAfterPrepare (Deprecated) Executes after onPrepare, but may be deprecated in future versions. It's recommended to merge the logic into onPrepare.
beforePrintInstructions onBeforePrintInstructions Executes before printing log messages.
commands addCommand Adds a new CLI command.
watchFiles addWatchFiles Adds files to be watched.
fileChange onFileChanged Listens for file change events.
beforeCreateCompiler onBeforeCreateCompiler Executes before creating the compiler.
afterCreateCompiler onAfterCreateCompiler Executes after creating the compiler.
beforeBuild onBeforeBuild Executes before building.
afterBuild onAfterBuild Executes after building.
beforeDev onBeforeDev Executes before running the dev command.
afterDev onDevCompileDone Executes after the dev command compilation is complete.
beforeExit onBeforeExit Executes before the process exits.
htmlPartials modifyHtmlPartials Modifies HTML template partials.

Explanation: Please carefully review your code and ensure that all old APIs have been replaced with the new APIs.

Frequently Asked Questions

Q: Will my plugin still work after the migration?

A: As long as you have correctly completed all the steps in this guide, your plugin should work normally. If you encounter any problems, 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 is still supported, we strongly recommend migrating as soon as possible. The new plugin system offers better performance and richer features, and migration is worthwhile in the long run.

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

A: Please refer to 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 migrate your CLI plugins to the new Modern.js plugin system. If you encounter any problems during the migration, please feel free to ask us for help.