> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # CLI Plugin API Modern.js's CLI plugins allow you to extend and customize the functionality of Modern.js projects during the build and development process. :::info CLI plugins need to be configured via the [`plugins`](/configure/app/plugins.md) field in `modern.config.ts`. ::: ## Plugin Basic Structure A typical CLI plugin structure is as follows: ```typescript import type { CliPlugin, AppTools } from '@modern-js/app-tools'; const myCliPlugin = (): CliPlugin => ({ name: '@my-org/my-plugin', // Plugin name, ensure uniqueness setup: api => { // Use the API here to register hooks, add commands, etc. api.onBeforeBuild(() => { console.log('Build is about to start...'); }); }, }); export default myCliPlugin; ``` - `name`: A unique identifier for the plugin. - The `setup` function receives an `api` object, which provides all available CLI plugin APIs. ## Information Retrieval #### `api.getAppContext` Gets the context information of the Modern.js application. - **Returns:** An `AppContext` object containing the following fields: | Field Name | Type | Description | When Available | | ---------------------- | ------------------- | ---------------------------------------------------------------- | -------------------------- | | `command` | `string` | The currently executing command (e.g., `dev`, `build`, `deploy`) | - | | `port` | `number` | The development server port number | After `onPrepare` | | `configFile` | `string` | The absolute path to the configuration file | - | | `isProd` | `boolean` | Whether it is in production mode | - | | `appDirectory` | `string` | The absolute path to the project root directory | - | | `srcDirectory` | `string` | The absolute path to the project source code directory | - | | `distDirectory` | `string` | The absolute path to the project output directory | In `onPrepare` (and later) | | `sharedDirectory` | `string` | The absolute path to the shared modules directory | - | | `nodeModulesDirectory` | `string` | The absolute path to the `node_modules` directory | - | | `ip` | `string` | The IPv4 address of the current machine | - | | `packageName` | `string` | The `name` field in the project's `package.json` | - | | `plugins` | `object[]` | The list of currently registered plugins | - | | `entrypoints` | `object[]` | Information about page entry points | - | | `serverRoutes` | `object[]` | Server-side routing information | - | | `bundlerType` | `webpack \| rspack` | The type of bundler currently in use (`webpack` or `rspack`) | After `onPrepare` | | `metaName` | `string` | The internal name of the framework | - | | `apiDirectory` | `string` | The absolute path to the API module directory (used by BFF) | - | | `lambdaDirectory` | `string` | The absolute path to the Lambda module directory (used by BFF) | - | | `runtimeConfigFile` | `string` | The name of the runtime configuration file | - | | `checkedEntries` | `string[]` | Specified entry information | - | | `apiOnly` | `boolean` | Whether it is in `apiOnly` mode | - | - **Example:** ```typescript api.onPrepare(() => { const appContext = api.getAppContext(); console.log( `The current project is running in ${ appContext.isProd ? 'production' : 'development' } mode`, ); console.log(`Bundler: ${appContext.bundlerType}`); }); ``` :::info The context information returned by `getAppContext` is read-only and cannot be modified directly. ::: *** #### `api.getConfig` Gets the user-defined configuration from the `modern.config.ts` file. - **Returns:** The user-defined configuration object. - **Example:** ```typescript api.onPrepare(() => { const userConfig = api.getConfig(); if (userConfig.output) { console.log('User has customized the output configuration'); } }); ``` *** #### `api.getNormalizedConfig` Gets the final configuration after internal processing by Modern.js and modifications by plugins (normalized configuration). - **Returns:** The normalized configuration object. - **When Available:** Must be used in `onPrepare` (and later hooks, such as `onBeforeBuild`). - **Example:** ```typescript api.onPrepare(() => { const finalConfig = api.getNormalizedConfig(); console.log('Final configuration:', finalConfig); }); ``` *** #### `api.isPluginExists` Checks if a specified plugin is registered. - **Parameters:** - `pluginName: string`: The name of the plugin to check. - **Returns:** A `boolean` value indicating whether the plugin exists. - **Example:** ```typescript if (api.isPluginExists('@modern-js/plugin-bff')) { console.log('BFF plugin is enabled'); } ``` *** #### `api.getHooks` Gets all registered hook functions. - **Returns:** An object containing all hook functions. - **Example:** ```typescript const hooks = api.getHooks(); // Manually trigger the onPrepare hook hooks.onPrepare.call(); ``` :::warning In custom plugins, you can only manually call the hooks registered by the corresponding plugin and cannot call official hooks to avoid affecting the normal execution order of the application. ::: *** ## Configuration Modification #### `api.config` Modify the initial configuration of Modern.js. - **Type:** `api.config(configFn: () => UserConfig | Promise)` - **Parameters:** - `configFn`: A function that returns a configuration object or a Promise. - **Execution Phase:** After parsing the configuration in `modern.config.ts`. - **Example:** ```typescript api.config(() => { return { output: { disableTsChecker: true, // Disable TypeScript type checking }, }; }); ``` **Configuration Merging Priority** (from highest to lowest): 1. Configuration defined by the user in the `modern.config.*` file. 2. Configuration registered by plugins via `api.config()`. 3. Default Modern.js configuration. *** #### `api.modifyBundlerChain` Modify Rspack configuration using the chain API. - **Type:** `api.modifyBundlerChain(modifyFn: (chain: RspackChain, utils: RspackUtils) => void | Promise)` - **Parameters:** - `modifyFn`: A modification function that receives a `RspackChain` instance and utility functions as parameters. - **Execution Phase:** When generating the final Rspack configuration. - **Corresponding Rsbuild Hook:** [modifyBundlerChain](https://v2.rsbuild.rs/plugins/dev/hooks#modifybundlerchain) - **Example:** ```typescript api.modifyBundlerChain((chain, utils) => { if (utils.env === 'development') { chain.devtool('eval'); } chain.plugin('bundle-analyze').use(BundleAnalyzerPlugin); }); ``` #### `api.modifyRsbuildConfig` Modify the Rsbuild configuration. - **Type:** `api.modifyRsbuildConfig(modifyFn: (config: RsbuildConfig, utils: RsbuildUtils) => RsbuildConfig | Promise | void)` - **Parameters:** - `modifyFn`: A modification function that receives the Rsbuild configuration object and utility functions as parameters. It can return the modified configuration object, a Promise, or nothing (modifying the original object directly). - **Execution Phase:** When generating the final Rsbuild configuration. - **Corresponding Rsbuild Hook:** [modifyRsbuildConfig](https://v2.rsbuild.rs/plugins/dev/hooks#modifyrsbuildconfig) - **Example:** ```typescript api.modifyRsbuildConfig((config, utils) => { // Add a custom Rsbuild plugin config.plugins.push(myCustomRsbuildPlugin()); }); ``` *** #### `api.modifyRspackConfig` Modify the Rspack configuration (when using Rspack as the bundler). - **Type:** `api.modifyRspackConfig(modifyFn: (config: RspackConfig, utils: RspackUtils) => RspackConfig | Promise | void)` - **Parameters:** - `modifyFn`: A modification function that receives the Rspack configuration object and utility functions as parameters. It can return the modified configuration object, a Promise, or nothing (modifying the original object directly). - **Execution Phase:** When generating the final Rspack configuration. - **Corresponding Rsbuild Hook:** [modifyRspackConfig](https://v2.rsbuild.rs/plugins/dev/hooks#modifyrspackconfig) - **Example:** ```typescript api.modifyRspackConfig((config, utils) => { config.builtins.minify = { enable: true, implementation: utils.rspack.SwcJsMinimizerRspackPlugin, }; }); ``` *** **Build Configuration Modification Order** ``` modifyRsbuildConfig modifyBundlerChain tools.bundlerChain modifyRspackConfig tools.rspack ``` *** #### `api.modifyServerRoutes` Modify the server routing configuration. - **Type:** `api.modifyServerRoutes(transformFn: (routes: ServerRoute[]) => ServerRoute[])` - **Parameters:** - `transformFn`: A transformation function that receives the current server routes array as a parameter and returns the modified array. - **Execution Phase:** Before generating the server route file (during the `prepare` phase). - **Example:** ```typescript api.modifyServerRoutes(routes => { // Add a new API route routes.push({ urlPath: '/api', isApi: true, entryPath: '', isSPA: false, isSSR: false, }); return routes; }); ``` *** #### `api.modifyHtmlPartials` Modify HTML template partials. - **Type:** `api.modifyHtmlPartials(modifyFn: (partials: HtmlPartials, entrypoint: Entrypoint) => void)` - **Parameters:** - `modifyFn`: A modification function that receives the HTML template partials object and the current entry point information as parameters. - `partials`: Contains `top`, `head`, and `body` sections, each with `append`, `prepend`, and `replace` methods. - **Execution Phase:** Before generating the HTML file (during the `prepare` phase). - **Example:** ```typescript api.modifyHtmlPartials(({ entrypoint, partials }) => { // Add a meta tag to the section of all pages if (partials.head && partials.head.append) { partials.head.append(``); } }); ``` :::warning This hook function will not be executed when using a [completely custom HTML template](/guides/basic-features/html.md#completely-custom-html-template). ::: *** ## Build Process Control #### `api.onPrepare` Add additional logic during the Modern.js preparation phase. - **Type:** `api.onPrepare(prepareFn: () => void | Promise)` - **Parameters:** - `prepareFn`: A preparation function, without parameters, can be asynchronous. - **Execution Phase:** After Modern.js has completed configuration validation. - **Example:** ```typescript api.onPrepare(async () => { // Perform some initialization operations, such as checking the environment, downloading dependencies, etc. await prepareMyCustomEnvironment(); }); ``` *** #### `api.addCommand` Add a custom CLI command. - **Type:** `api.addCommand(commandFn: ({ program: Command }) => void)` - **Parameters:** - `commandFn`: Receives the `program` object from `commander` as a parameter, used to define new commands. - **Execution Phase:** After the `prepare` hook has completed. - **Example:** ```typescript api.addCommand(({ program }) => { program .command('my-command') .description('My custom command') .action(async () => { // Execute command logic console.log('Executing custom command...'); }); }); ``` *** #### `api.addWatchFiles` Add additional files to the watch list (for development mode). - **Type:** `api.addWatchFiles(watchFn: () => string[] | { files: string[]; isPrivate: boolean; })` - **Parameters:** - `watchFn`: Returns an array of file paths or an object containing `files` and `isPrivate` properties. - `files`: An array of file paths to watch. - `isPrivate`: Whether the files are framework-internal (affects behavior when files change). - **Execution Phase:** After the `addCommand` hook has completed. - **Example:** ```typescript api.addWatchFiles(() => { // Watch the .env file in the project root directory return [path.resolve(api.getAppContext().appDirectory, '.env')]; }); ``` *** #### `api.onFileChanged` Add additional logic when a watched file changes (for development mode). - **Type:** `api.onFileChanged(changeFn: (params: { filename: string; eventType: 'add' | 'change' | 'unlink'; isPrivate: boolean; }) => void)` - **Parameters:** - `changeFn`: A file change handler function that receives the following parameters: - `filename`: The path of the changed file. - `eventType`: The type of change (`add`, `change`, `unlink`). - `isPrivate`: Whether the file is framework-internal. - **Execution Phase:** After a watched file changes. - **Example:** ```typescript api.onFileChanged(({ filename, eventType }) => { if (eventType === 'change' && filename.endsWith('.ts')) { console.log('TypeScript file changed, may need to recompile...'); } }); ``` *** #### `api.onBeforeBuild` Add additional logic before the build starts. - **Type:** `api.onBeforeBuild(buildFn: () => void | Promise)` - **Parameters:** - `buildFn`: A function to be executed before the build, without parameters, can be asynchronous. - **Execution Phase:** Before executing the build process. - **Corresponding Rsbuild Hook:** [onBeforeBuild](https://v2.rsbuild.rs/plugins/dev/hooks#onbeforebuild) - **Example:** ```typescript api.onBeforeBuild(() => { // Perform some environment checks before building }); ``` *** #### `api.onAfterBuild` Add additional logic after the build is complete. - **Type:** `api.onAfterBuild(buildFn: () => void | Promise)` - **Parameters:** - `buildFn`: A function to be executed after the build, without parameters, can be asynchronous. - **Execution Phase:** After executing the build process. - **Corresponding Rsbuild Hook:** [onAfterBuild](https://v2.rsbuild.rs/plugins/dev/hooks#onafterbuild) - **Example:** ```typescript api.onAfterBuild(() => { // Upload sourceMap after building }); ``` *** #### `api.onDevCompileDone` Add additional logic after the development server compilation is complete. - **Type:** `api.onDevCompileDone(compileFn: () => void | Promise)` - **Parameters:** - `compileFn`: A function to be executed after compilation is complete. - **Execution Phase:** After the development server starts and the initial compilation is complete. - **Corresponding Rsbuild Hook:** [onDevCompileDone](https://v2.rsbuild.rs/plugins/dev/hooks#ondevcompiledone) - **Example:** ```typescript api.onDevCompileDone(() => { // Open the browser after the initial compilation is complete }); ``` *** #### `api.onBeforeCreateCompiler` Add additional logic before creating the compiler instance. - **Type:** `api.onBeforeCreateCompiler(createFn: () => void | Promise)` - **Parameters:** - `createFn`: A function to be executed before creation, without parameters, can be asynchronous. - **Execution Phase:** Before creating the Rspack compiler instance. - **Corresponding Rsbuild Hook:** [onBeforeCreateCompiler](https://v2.rsbuild.rs/plugins/dev/hooks#onbeforecreatecompiler) - **Example:** ```typescript api.onBeforeCreateCompiler(() => { // Can get compiler related configuration }); ``` *** #### `api.onAfterCreateCompiler` Add additional logic after creating the compiler instance. - **Type:** `api.onAfterCreateCompiler(createFn: () => void | Promise)` - **Parameters:** - `createFn`: A function to be executed after creation, without parameters, can be asynchronous. - **Execution Phase:** After creating the Rspack compiler instance. - **Corresponding Rsbuild Hook:** [onAfterCreateCompiler](https://v2.rsbuild.rs/plugins/dev/hooks#onaftercreatecompiler) - **Example:** ```typescript api.onAfterCreateCompiler(() => { // Can get the compiler instance }); ``` *** #### `api.onBeforeDev` Add additional logic before starting the development server. - **Type:** `api.onBeforeDev(devFn: () => void | Promise)` - **Parameters:** - `devFn`: A function to be executed before starting the development server, without parameters, can be asynchronous. - **Execution Phase:** Before executing the `dev` command to start the development server. - **Example:** ```typescript api.onBeforeDev(async () => { // Check if the port is occupied await checkPortAvailability(3000); }); ``` *** #### `api.onAfterDev` Add additional logic after starting the development server. - **Type:** `api.onAfterDev(devFn: () => void | Promise)` - **Parameters:** - `devFn`: A function to be executed after the development server starts. - **Execution Phase:** After the development server has successfully started. - **Corresponding Rsbuild Hook:** [onAfterStartDevServer](https://v2.rsbuild.rs/plugins/dev/hooks#onafterstartdevserver) - **Example:** ```typescript api.onAfterDev(() => { // Report dev related information }); ``` *** #### `api.onBeforeExit` Add additional logic before the process exits. - **Type:** `api.onBeforeExit(exitFn: () => void | Promise)` - **Parameters:** - `exitFn`: A function to be executed before the process exits, without parameters, can be asynchronous. - **Execution Phase:** When the Modern.js process is about to exit (for example, when the user presses Ctrl+C). - **Example:** ```typescript api.onBeforeExit(async () => { // Perform some cleanup operations, such as closing database connections, deleting temporary files, etc. await cleanupMyResources(); }); ``` *** #### `api.onBeforePrintInstructions` Add additional logic before printing success information. - **Type:** `api.onBeforePrintInstructions(printFn: ({instructions: string}) => {instructions: string} | Promise<{instructions: string}>)` - **Parameters:** - `printFn`: Function to modify the printed information, returns the modified information. - **Execution Phase:** Before printing success information. - **Example:** ```typescript api.onBeforePrintInstructions(({ instructions }) => { // do something return { instructions }; }); ``` ## Other Notes - Refer to [CLI Plugin Lifecycle](/plugin/cli-plugins/life-cycle.md) to understand the execution order of plugin hooks.