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

interface StudioCMSPlugin {
  identifier: string;
  name: string;
  studiocmsMinimumVersion: string;
  hooks: {
    'studiocms:astro:config': (params: {
      logger: AstroIntegrationLogger;
      addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void;
    }) => void | Promise<void>;
    'studiocms:config:setup': (params: {
      logger: AstroIntegrationLogger;
      setSitemap: (params: {
        triggerSitemap?: boolean | undefined;
        sitemaps?: {
          pluginName: string;
          sitemapXMLEndpointPath: string | URL;
        }[] | undefined;
      }) => void;
      setDashboard: (params: {
        dashboardGridItems?: GridItemInput[] | undefined;
        dashboardPages?: {
          user?: (...)[] | undefined;
          admin?: (...)[] | undefined;
        } | undefined;
        settingsPage?: {
          fields: (...)[];
          endpoint: string;
        } | undefined;
      }) => void;
      setFrontend: (params: {
        frontendNavigationLinks?: {
          label: string;
          href: string;
        }[] | undefined;
      }) => void;
      setRendering: (params: {
        pageTypes?: {
          label: string;
          identifier: string;
          description?: string | undefined;
          fields?: (...)[] | undefined;
          pageContentComponent?: string | undefined;
          rendererComponent?: string | undefined;
          apiEndpoint?: string | undefined;
        }[] | undefined;
      }) => 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 { 
function definePlugin(options: StudioCMSPlugin): StudioCMSPlugin
Defines a plugin for StudioCMS.
@param ― options - The configuration options for the plugin.
@returns ― The plugin configuration.
definePlugin } from 'studiocms/plugins';
import { 
(alias) interface AstroIntegration
import AstroIntegration
AstroIntegration } from 'astro';

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

// Define the Astro integration
const 
const myIntegration: (options: Options) => AstroIntegration
myIntegration = (
options: Options
options: 
interface Options
Options): 
(alias) interface AstroIntegration
import AstroIntegration
AstroIntegration => ({
    
AstroIntegration.name: string
The name of the integration.
name: 'my-astro-integration',
    
AstroIntegration.hooks: {
    'astro:db:setup'?: (options: {
        extendDb: (options: {
            configEntrypoint?: URL | string;
            seedEntrypoint?: URL | string;
        }) => void;
    }) => void | Promise<void>;
    ... 12 more ...;
    'studiocms:plugins'?: PluginHook<...>;
} & Partial<...>
The different hooks available to extend.
hooks: {
        "astro:config:setup": () => {
            
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log('Hello from my Astro Integration!');
        }
    }
});

// Define the StudioCMS Plugin
export const 
const myPlugin: (options: Options) => StudioCMSPlugin
myPlugin = (
options: Options
options: 
interface Options
Options) => 
function definePlugin(options: StudioCMSPlugin): StudioCMSPlugin
Defines a plugin for StudioCMS.
@param ― options - The configuration options for the plugin.
@returns ― The plugin configuration.
definePlugin({
    
StudioCMSPlugin.identifier: string
identifier: 'my-plugin',
    
StudioCMSPlugin.name: string
name: 'My Plugin',
    
StudioCMSPlugin.studiocmsMinimumVersion: string
studiocmsMinimumVersion: '0.1.0-beta.18',
    
StudioCMSPlugin.hooks: {
    'studiocms:astro:config'?: PluginHook<...>;
    'studiocms:config:setup'?: PluginHook<...>;
} & Partial<...>
hooks: {
      'studiocms:astro:config': ({ 
addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void
addIntegrations }) => {
        
addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void
addIntegrations(
const myIntegration: (options: Options) => AstroIntegration
myIntegration(
options: Options
options)) // Optional, but recommended
      }
    }
});

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