---
title: Write Plugins
sidebar_position: 3
---
# How to Write Plugins

The previous section introduced the Hook models used by Modern.js plugins, while this section describes how to write plugins.

## Implementing a Plugin

A Modern.js plugin is an object that includes the following properties:

- `name`: The name of the plugin, a unique identifier.
- `setup`: The initialization function for the plugin, which only runs once. The `setup` function can return a Hooks object, which Modern.js executes at specific times.

```ts
const myPlugin = {
  name: 'my-plugin',

  setup() {
    const foo = '1';

    // return hook object
    return {
      afterBuild: () => {
      },
    };
  },
};
```

In addition, plugins allow configuration of the execution order with other plugins. For more information, please refer to [Plugin Relationship](/guides/topic-detail/framework-plugin/relationship).

### Plugin Types

Modern.js supports various types of project development, such as application development (`app-tools`), module development (`module-tools`), etc.

To balance the differences and commonalities between various types of project development, Modern.js organizes plugins as shown in the following figure:

![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)

As shown in the figure, Modern.js roughly divides plugins into two categories:

1. Common plugins: Plugins that only include some basic Hooks.

2. Project plugins: Different project developments will extend their own Hooks, Config, etc. on the basis of common plugins.

When using TypeScript, you can import built-in types such as `CliPlugin` to provide correct type inference for plugins.

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

const myPlugin: CliPlugin = {
  name: 'my-plugin',

  setup() {
    const foo = '1';

    return {
      afterBuild: () => {
      },
    };
  },
};
```

The above code is a general-purpose plugin, containing only some basic Hooks. Modern.js supports extending the definition of plugins through generics:

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

const myPlugin: CliPlugin<AppTools> = {
  name: 'my-plugin',

  setup() {
    const foo = '1';

    return {
      afterBuild: () => {
      },
    };
  },
};
```

If you look closely at the type `AppTools`, you can see that `AppTools` consists of 3 types.

```ts
type AppTools = {
  hooks: AppToolsHooks;
  userConfig: AppToolsUserConfig;
  normalizedConfig: AppToolsNormalizedConfig;
};
```

When writing plugins, plugins extend their own types like Hooks on different bases through generic extensions:

```ts
// common plugin
import type { CliPlugin } from '@modern-js/core';
import type { MyPluginHook } from 'xxx';

const myPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
```

```ts
// extend from app-tools hook
import type { CliPlugin, AppTools } from '@modern-js/app-tools';
import type { MyPluginHook } from 'xxx';

const myPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
```

Please refer to [Extending Hooks](/guides/topic-detail/framework-plugin/extend) for detailed explanations.

### Plugin Configuration

**It is recommended to write plugins in the form of functions**, so that plugins can receive configuration options through function parameters:

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

type MyPluginOptions = {
  foo: string;
};

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

  setup() {
    console.log(options.foo);
  },
});
```

### Plugin API

The `setup` function of a plugin receives an `api` parameter, and you can call some methods provided on the `api` to get configuration, application context, and other information.


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

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

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

For more detail [Plugin API](/guides/topic-detail/framework-plugin/plugin-api).

### Async setup

The `setup` function of a CLI plugin can be an asynchronous function, which can execute asynchronous logic during the initialization process.


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

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

  async setup(api) {
    await doSomething();
  },
});
```

## Adding Plugins

Custom plugins can be used by following the instructions in the [plugins](/configure/app/plugins) section of the documentation. Below is the recommended way to implement plugins in Modern.js.

### Developing Local Plugins

It is recommended to write local plugins in the `config/plugin` directory and export them using `export default`:

```ts title=config/plugin/myPlugin.ts
import type { CliPlugin } from '@modern-js/core';

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

  setup() {
    // init plugin
  },
});
```

register plugin in `modern.config.ts`:

```ts title="modern.config.ts"
import { defineConfig } from '@modern-js/app-tools';
import myPlugin from './config/plugin/myPlugin';

export default defineConfig({
  plugins: [myPlugin()],
});
```

### Publishing a Plugin on npm

If you want to publish your Modern.js plugin on npm, it's recommended to use the module project solution provided by Modern.js to manage and build the plugin.

First, create an empty module project solution and adjust the package name:

```json
{
  "name": "my-plugin"
  ...
}
```

create plugin main file:

```ts title=src/index.ts
import type { CliPlugin } from '@modern-js/core';

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

  setup() {
    // plugin init
  },
});
```

After publishing, install it to the project you need to use `pnpm add my-plugin`, take an application project as an example, and then add it in `modern.config.ts`:

```ts title="modern.config.ts"
import { defineConfig } from '@modern-js/app-tools';
import myPlugin from 'my-plugin';

export default defineConfig({
  plugins: [myPlugin()],
});
```

If you find that there are currently unsatisfactory scenarios in Modern.js, welcome to build the Modern.js ecosystem together by **writing custom plugins**.
