Custom Plugin

Learn how to create custom Monicon plugins to extend functionality with your own icon processing logic, custom file generation, and lifecycle hooks.

Plugin Structure

A Monicon plugin is a function that returns another function, which receives the icon payload and returns a plugin instance with lifecycle hooks.

my-plugin.ts

import path from "path";
import type {
  ,
  ,
  ,
} from "@monicon/core/plugins";

type  = {
  ?: string;
  ?: string;
};

export const : <> =
  () => () => {
    return {
      : "my-custom-plugin",
      (: ) {
        const : [] = [];

        for (const  of .) {
          .({
            : path.(?. ?? "output", .),
            : .,
          });
        }

        return ;
      },
    };
  };

Plugin Types

Monicon provides TypeScript types to help you build type-safe plugins.

`MoniconPlugin<T>`

The main plugin type that defines the plugin factory function signature.

import type {  } from "@monicon/core/plugins";

type  = { ?: string };

const : <> = () => () => ({
  : "example-plugin",
  : () => [],
});

`MoniconPluginFile`

Represents a file to be generated by the plugin.

import type {  } from "@monicon/core/plugins";

const :  = {
  : "output/icon.svg",
  : "<svg>...</svg>",
};

`MoniconPluginPayload`

The payload passed to the plugin containing the icons to process.

import type {  } from "@monicon/core";

type  = {
  : [];
};

`Icon`

The icon object containing all icon data.

type  = {
  : string;
  : string;
  : number;
  : number;
};

Lifecycle Hooks

Plugins can implement lifecycle hooks to execute code at different stages of the generation process.

`generate`

Required. The main generation function that returns an array of files to create.

import type {
  ,
  ,
} from "@monicon/core/plugins";

const :  = () => () => ({
  : "my-plugin",
  (: ) {
    .("Generating files for", .., "icons");
    .("Config file path:", .);

    return ..(() => ({
      : `output/${.}.svg`,
      : .,
    }));
  },
});

`onPluginsLoad`

Called when all plugins are loaded. Useful for plugin initialization or validation.

import type {
  ,
  ,
} from "@monicon/core/plugins";

const :  = () => () => ({
  : "my-plugin",
  : () => [],
  (: ) {
    .("Loaded plugins:", .);
  },
});

`beforeGenerate`

Called before the generate function runs.

import type {
  ,
  ,
} from "@monicon/core/plugins";

const :  = () => () => ({
  : "my-plugin",
  : () => [],
  (: ) {
    .("About to generate", .., "icons");
  },
});

`afterGenerate`

Called after the generate function completes.

import type {
  ,
  ,
} from "@monicon/core/plugins";

const :  = () => () => ({
  : "my-plugin",
  : () => [],
  (: ) {
    .("Finished generating icons");
  },
});

`beforeWriteFiles`

Called before files are written to disk.

import type {
  ,
  ,
} from "@monicon/core/plugins";

const :  = () => () => ({
  : "my-plugin",
  : () => [],
  (: ) {
    .("About to write", .., "files");
  },
});

`afterWriteFiles`

Called after files have been written to disk.

import type {
  ,
  ,
} from "@monicon/core/plugins";

const :  = () => () => ({
  : "my-plugin",
  : () => [],
  (: ) {
    .("Successfully wrote", .., "files");
  },
});

Context Objects

Each lifecycle hook receives a context object with relevant information.

`MoniconPluginGenerateContext`

Available in generate, beforeGenerate, and afterGenerate hooks.

icons - Array of icons being processed
configUpdated - Whether the config file was updated
configFilePath - Path to the Monicon config file

`MoniconPluginLoadContext`

Available in onPluginsLoad hook.

plugins - Array of loaded plugin names
configUpdated - Whether the config file was updated
configFilePath - Path to the Monicon config file

`MoniconPluginWriteFilesContext`

Available in beforeWriteFiles and afterWriteFiles hooks.

files - Array of files to be written or that were written
configUpdated - Whether the config file was updated
configFilePath - Path to the Monicon config file

Using with Generic Plugin

For simpler use cases, you can extend the Generic plugin instead of building from scratch:

extended-generic-plugin.ts

import {
  ,
  ,
  ,
} from "@monicon/core/plugins";

type  = <{
  ?: string;
}>;

export const : <> = () =>
  ({
    : "my-extended-plugin",
    : ?. ?? "output",
    : "json",
    : () => {
      return .(
        {
          : .,
          : .,
          : ?.,
        },
        null,
        2
      );
    },
  });

On this page