The Basics

Introduction

'Read the “', Introduction, '” section'

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?

'Read the “', What are Plugins?, '” section'

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

'Read the “', The StudioCMS Plugin Type, '” section'

type StudioCMSPlugin = {
  /**
   * Identifier of the plugin from the package.json
   */
  identifier: string;

  /**
   * Label of the plugin to be displayed in the StudioCMS Dashboard
   */
  name: string;

  /**
   * Minimum version of StudioCMS required for the plugin to work
   */
  studiocmsMinimumVersion: string;

  /**
   * Astro Integration(s) that the plugin provides
   */
  integration?: AstroIntegration | AstroIntegration[] | undefined;

  /**
   * If this is true, the plugin will enable the sitemap generation
   */
  triggerSitemap?: boolean;

  /**
   * Allows the plugin to add sitemap endpoints
   */
  sitemaps?: Array<{

    /**
     * Name of the plugin
     */
    pluginName: string;

    /**
     * Path to the sitemap xml endpoint file
     */
    sitemapXMLEndpointPath: string | URL;
  }> | undefined;

  /**
   * Allows the plugin to add custom dashboard grid items
   */
  dashboardGridItems?: Array<{

    /**
     * Name of the grid item
     */
    name: string;

    /**
     * Span of the grid item
     */
    span: 1 | 2 | 3;

    /**
     * Card variant of the grid item
     */
    variant: 'default' | 'filled';

    /**
     * Permission required to view the grid item
     */
    requiresPermission?: "owner" | "admin" | "editor" | "visitor";

    /**
     * Header information of the grid item
     */
    header?: {

      /**
       * Title of the grid item
       */
      title: string;

      /**
       * Icon of the grid item
       */
      icon?: HeroIconName;
    };

    /**
     * Body information of the grid item
     */
    body?: {

      /**
       * HTML content of the grid item
       */
      html: string;

      /**
       * Component that is displayed in the grid item
       */
      components?: Record<string, string>;

      /**
       * Sanitize options for the HTML content
       */
      sanitizeOpts?: SanitizeOptions;
    };
  }> | undefined;

  /**
   * If this exists, the plugin will have its own setting page
   */
  settingsPage: {

    /**
     * Fields according to specification
     */
    fields: SettingsField[];

    /**
     * Function that runs on when the settings page is saved
     *
     * Should return a string if there is an error,
     * otherwise return boolean true to indicate success
     */
    onSave: APIRoute;
  } | undefined;

  /**
   * Page Type definition. If this is present, the plugin wants to be able to modify the page creation process
   */
  pageTypes: Array<{

    /**
     * Label that is shown in the select input
     */
    label: string;

    /**
     * Identifier that is saved in the database
     * @example
     * // Single page type per plugin
     * 'studiocms'
     * '@studiocms/blog'
     * // Multiple page types per plugin (Use unique identifiers for each type to avoid conflicts)
     * '@mystudiocms/plugin:pageType1'
     * '@mystudiocms/plugin:pageType2'
     * '@mystudiocms/plugin:pageType3'
     * '@mystudiocms/plugin:pageType4'
     */
    identifier: string;

    /**
     * Description that is shown below the "Page Content" header if this type is selected
     */
    description: string;

    /**
     * The path to the actual component that is displayed for the page content
     *
     * Component should have a `content` prop that is a string to be able to display current content.
     *
     * **NOTE:** Currently, requires you to use the form id `page-content` for the content output. Your editor should also be able to handle form submission.
     *
     * @example
     * ```ts
     * import { createResolver } from 'astro-integration-kit';
     * const { resolve } = createResolver(import.meta.url)
     *
     * {
     *  pageContentComponent: resolve('./components/MyContentEditor.astro'),
     * }
     * ```
     */
    pageContentComponent: string;
  }> | undefined;
};

Defining a Plugin

'Read the “', Defining a Plugin, '” section'

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',
    studiocmsMinimumVersion: '0.1.0-beta.8',
    integration: myIntegration(options), // Optional, but recommended
});

In this example, we define a StudioCMS plugin called My Plugin that requires StudioCMS version 0.1.0-beta.8 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