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 APINew APIDescription
useAppContextgetAppContextGets the application context information.
useConfigContextgetConfigGets the configuration defined in the user's configuration file.
useResolvedConfigContextgetNormalizedConfigGets 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.
prepareonPrepareThe preparation stage before running the main process.
afterPrepareonAfterPrepare (Deprecated)Executes after onPrepare, but may be deprecated in future versions. It's recommended to merge the logic into onPrepare.
beforePrintInstructionsonBeforePrintInstructionsExecutes before printing log messages.
commandsaddCommandAdds a new CLI command.
watchFilesaddWatchFilesAdds files to be watched.
fileChangeonFileChangedListens for file change events.
beforeCreateCompileronBeforeCreateCompilerExecutes before creating the compiler.
afterCreateCompileronAfterCreateCompilerExecutes after creating the compiler.
beforeBuildonBeforeBuildExecutes before building.
afterBuildonAfterBuildExecutes after building.
beforeDevonBeforeDevExecutes before running the dev command.
afterDevonDevCompileDoneExecutes after the dev command compilation is complete.
beforeExitonBeforeExitExecutes before the process exits.
htmlPartialsmodifyHtmlPartialsModifies 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.