The Basics

Introduction

StudioCMS plugins are a powerful tool that allows you to extend the functionality of StudioCMS. They provide a simple and flexible way to add new features to your StudioCMS project. The following is a breakdown of StudioCMS plugins and how they work.

What are Plugins?

StudioCMS plugins are similar to Astro Integrations, but they have extra information attached to the function object. This information is used by StudioCMS to determine how the plugin should be loaded and used. StudioCMS plugins are used to extend the functionality of StudioCMS by adding new features or modifying existing ones.

The StudioCMS Plugin Type Revised 0.4.0

interface StudioCMSPlugin {
  identifier: string;
  name: string;
  hooks: {
    'studiocms:astro:config': (params: {
      logger: AstroIntegrationLogger;
      addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void;
    }) => void | Promise<void>;
    'studiocms:auth': (params: {
      logger: AstroIntegrationLogger;
      setAuthService: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:dashboard': (params: {
      logger: AstroIntegrationLogger;
      setDashboard: (args_0: { ...; }) => void;
      augmentDashboard: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:frontend': (params: {
      logger: AstroIntegrationLogger;
      setFrontend: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:rendering': (params: {
      logger: AstroIntegrationLogger;
      setRendering: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:image-service': (params: {
      logger: AstroIntegrationLogger;
      setImageService: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:sitemap': (params: {
      logger: AstroIntegrationLogger;
      setSitemap: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
  }
}

Defining a Plugin

To define a StudioCMS plugin, you need to create an object that conforms to the StudioCMSPlugin type. This object should look similar to the following, keeping in mind that the following properties are required:

• identifier: The identifier of the plugin from the package.json file.
• name: The label of the plugin to be displayed in the StudioCMS Dashboard.
• studiocmsMinimumVersion: The minimum version of StudioCMS required for the plugin to work.

Here is an example of a StudioCMS plugin definition that includes all the required properties as well as provides an Astro Integration to do custom logic:

my-plugin.ts

import { definePlugin } from 'studiocms/plugins';
import { AstroIntegration } from 'astro';

// Define the options for the plugin and integration
interface Options {
    foo: string;
}

// Define the Astro integration
const myIntegration = (options: Options): AstroIntegration => ({
    name: 'my-astro-integration',
    hooks: {
        "astro:config:setup": () => {
            console.log('Hello from my Astro Integration!');
        }
    }
});

// Define the StudioCMS Plugin
export const myPlugin = (options: Options) => definePlugin({
    identifier: 'my-plugin',
    name: 'My Plugin',
    hooks: {
      'studiocms:astro-config': ({ addIntegrations }) => {
        addIntegrations(myIntegration(options)) // Optional, but recommended
      }
    }
});

In this example, we define a StudioCMS plugin called My Plugin that requires StudioCMS version v0.1.0 or higher. The plugin also provides an Astro Integration that logs a message to the console when the astro:config:setup hook is called.

For more information on building plugins checkout the Making Plugins Useful Guide