Skip to content

index.mdx

Latest commit

 

History

History
106 lines (88 loc) · 3.98 KB

index.mdx

File metadata and controls

106 lines (88 loc) · 3.98 KB
i18nReady true
title The Basics
description Learn about the StudioCMS plugins and how they work.
sidebar
order
1

import { Badge } from '@astrojs/starlight/components'; import ReadMore from '~/components/ReadMore.astro'

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 

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:

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][extended-plugins] Guide

{/* Links */} [extended-plugins]: /en/plugins/extended/