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

Plugin API

The setup function of the plugin will receive an api imported parameter, and you can call some methods provided on the api to obtain information such as configuration and application context.

import type { CliPlugin } from '@modern-js/core';

export const myPlugin = (): CliPlugin => ({
  name: 'my-plugin',

  setup(api) {
    // get user config
    const config = api.useConfigContext();
    // get plugin context
    const appContext = api.useAppContext();
    // get resolved config
    const resolvedConfig = api.useResolvedConfigContext();
  },
});

API

useConfigContext

Used to retrieve the original configuration of the application.

const useConfigContext: () => UserConfig;

interface UserConfig {
  source?: SourceConfig;
  output?: OutputConfig;
  server?: ServerConfig;
  deploy?: DeployConfig;
  // ...other fields
}

Please refer to Configuration for the specific meanings of configuration fields.

TIP

This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use config hook.

useResolvedConfigContext

Used to retrieve the final configuration after parsing.

const useResolvedConfigContext: () => NormalizedConfig;

interface NormalizedConfig {
  source: NormalizedSourceConfig;
  output: NormalizedOutputConfig;
  server: NormalizedServerConfig;
  deploy: NormalizedDeployConfig;
  _raw: UserConfig; // the original user config
  // ...other fields
}

Please refer to Configuration for the specific meanings of configuration fields.

TIP

This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use config hook.

useAppContext

Used to retrieve the runtime context of the application.

const useAppContext: () => IAppContext;

interface IAppContext {
  /** Root directory of the current project */
  appDirectory: string;
  /** Source code directory */
  srcDirectory: string;
  /** Directory for output files */
  distDirectory: string;
  /** Directory for shared modules */
  sharedDirectory: string;
  /** Directory for framework temp files */
  internalDirectory: string;
  /** node_modules directory */
  nodeModulesDirectory: string;
  /** Path to the configuration file */
  configFile: string | false;
  /** IPv4 address of the current machine */
  ip?: string;
  /** Port number of the development server */
  port?: number;
  /** Name of the current project's package.json */
  packageName: string;
  /** Currently registered plugins */
  plugins: any[];
  /** Information for entry points */
  entrypoints: Entrypoint[];
  /** Information for server routes */
  serverRoutes: ServerRoute[];
  /** Tools type of the current project */
  toolsType?: 'app-tools' | 'module-tools';
  /** Type of the bundler being used */
  bundlerType?: 'webpack' | 'rspack' | 'esbuild';
}
TIP

Some fields in the AppContext are dynamically set and will change as the program runs. Therefore, when plugins read these fields at different times, they may get different values.

useHookRunners

Used to retrieve the executor of Hooks and trigger the execution of specific Hooks.

import type { CliPlugin } from '@modern-js/core';

export const myPlugin = (): CliPlugin => ({
  name: 'my-plugin',

  async setup(api) {
    const hookRunners = api.useHookRunners();
    // invoke afterBuild Hook
    await hookRunners.afterBuild();
  },
});
TIP

Please avoid executing the built-in hooks, as it may break the internal execution logic of the framework.