Skip to content
StudioCMSDocs
Main Site

Making Plugins Useful

Introduction

Section titled “Introduction”

Building a StudioCMS Plugin is a powerful way 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 basic example of how to create a StudioCMS Plugin and how it works.

Getting Started

Section titled “Getting Started”

To get started, you will need to create a new StudioCMS Plugin. The following is a basic example of the file structure for a StudioCMS Plugin:

  • package.json
  • Directorysrc
    • index.ts
    • Directoryroutes
      • […slug].astro
    • Directorydashboard-grid-items
      • MyPluginGridItem.astro

Creating the Plugin

Section titled “Creating the Plugin”

In the main src/index.ts file, you will define the StudioCMS Plugin. The following is an example of how to define a StudioCMS Plugin that includes an Astro Integration to create a simple blog example:

index.ts
import { definePlugin } from 'studiocms/plugins';
import { AstroIntegration } from 'astro';
import { addVirtualImports, createResolver } from 'astro-integration-kit';


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


export function studioCMSPageInjector(options: Options) {
  // Resolve the path to the current file
  const { resolve } = createResolver(import.meta.url);


  // Define the Astro integration
  function myIntegration(options: Options): AstroIntegration {
    const route = `/${options?.route || 'my-plugin'}`;


    return {
      name: 'my-astro-integration',
      hooks: {
        "astro:config:setup": (params) => {
          const { injectRoute } = params;


          // Inject the route for the plugin
          injectRoute({
            entrypoint: resolve('./routes/[...slug].astro'),
            pattern: `/${route}/[...slug]`,
            prerender: false,
          })


          addVirtualImports(params, {
            name: 'my-astro-integration',
            imports: {
              'myplugin:config': `
                export const options = ${JSON.stringify({ route })};
                export default options;
              `,
            }
          })
        }
      }
    }
  }


  // Define the StudioCMS Plugin
  return definePlugin({
    identifier: 'my-plugin',
    name: 'My Plugin',
    hooks: {
      'studiocms:astro-config': ({ addIntegrations }) => {
        addIntegrations(myIntegration(options));  // Optional, but recommended
      },
      'studiocms:dashboard': ({ setDashboard }) => {
        setDashboard({
          translations: {
            en: {
              example: {
                title: 'Example',
                'other-text': 'Some other text',
              }
            },
            fr: {
              example: {
                title: 'Exemple',
                'other-text': 'Un autre texte',
              }
            }
          },


          // Define the grid items for the dashboard
          // These are the items that will be displayed on the StudioCMS Dashboard
          // You can define as many items as you want
          // In this example, we are defining a single item, which has a span of 2 and requires the 'editor' permission and injects an Astro component which replaces the plain html custom element.
          dashboardGridItems: [
            {
              name: 'example',
              span: 2,
              variant: 'default',
              requiresPermission: 'editor',
              header: { title: 'Example', icon: 'heroicons:bolt' },
              body: {
                // Always use plain html without `-` or special characters in the tags, they will get replaced with the Astro component and this HTML will never be rendered
                html: '<examplegriditem></examplegriditem>',
                components: {
                  // Inject the Astro component to replace the plain html custom element
                  examplegriditem: resolve('./dashboard-grid-items/MyPluginGridItem.astro')
                }
              }
            }
          ],
        });
      },


      'studiocms:frontend': ({ setFrontend }) => {
        setFrontend({
          // Define the frontend navigation links for the plugin
          // This is useful if you are using the built in StudioCMS navigation helpers in your layout,
          // such as when using the `@studiocms/blog` Plugin.
          frontendNavigationLinks: [{ label: 'My Plugin', href: options?.route || 'my-plugin' }],
        });
      },
      'studiocms:rendering': ({ setRendering }) => {
        setRendering({
          // When creating pageTypes, you can also define a `pageContentComponent` if your plugin requires a custom content editor.
          // pageTypes: [{ identifier: 'my-plugin', label: 'Blog Post (My Plugin)', pageContentComponent: resolve('./components/MyContentEditor.astro') }],
          // In this example we are okay using the default content editor (markdown).
          pageTypes: [{ identifier: 'my-plugin', label: 'Blog Post (My Plugin)' }],
        });
      }
    }
  });
}

The above example defines a StudioCMS Plugin that includes an Astro Integration to create a simple blog example. The plugin includes a route that is injected into the StudioCMS project and a grid item that is displayed on the StudioCMS Dashboard.

For more information on how to create an Astro Integration, see the Astro Integration Kit^ and the Astro Integrations documentation^.

Example route

Section titled “Example route”

In the src/routes/[...slug].astro file, you will define the route for the plugin. The following is an example of how to define a route for the plugin, we will break this out into two parts, the first part is the frontmatter (between the --- marks), and the second part is the HTML template that gets put under the second ---.

Frontmatter
// @noErrors
// @filename: plugin.d.ts
declare module 'myplugin:config' {
    export const options: { route: string };
    export default options;
}
// ---cut---
// @filename: Frontmatter.ts
/// <reference types="studiocms/v/types" />
/// <reference types="./plugin.d.ts" />
import type { AstroGlobal } from 'astro';
const Astro: AstroGlobal = {};
// ---cut---
import { StudioCMSRenderer } from 'studiocms:renderer';
import { SDKCoreJs, runSDK } from 'studiocms:sdk';
import config from 'myplugin:config';


const makeRoute = (slug: string) => {
    return `/${config.route}/${slug}`;
}


// 'my-plugin' here is used as the identifier for
// the pageType from the plugin definition
const pages = await runSDK(SDKCoreJs.GET.packagePages('my-plugin'));


const { slug } = Astro.params;


const page = pages.find((page) => page.slug === slug || '');
Template
{
    slug && page ? (
        <div>
            <h1>{page.title}</h1>
            <StudioCMSRenderer content={page.defaultContent?.content || ''} />
        </div>
    ) : (
        <div>
            <h1>My Plugin</h1>
            <ul>
                {pages.length > 0 && pages.map((page) => (
                    <li>
                        <a href={makeRoute(page.slug)}>{page.title}</a>
                    </li>
                ))}
            </ul>
        </div>
    )
}

The above example defines a dynamic route^ for the plugin that displays a list of blog posts when no slug is provided and displays the content of a blog post when a slug is provided.

Example grid item

Section titled “Example grid item”

In the src/dashboard-grid-items/MyPluginGridItem.astro file, you will define the grid item for the plugin. The following is an example of how to define a grid item for the plugin:

MyPluginGridItem.astro
---
import { SDKCoreJs, runSDK } from 'studiocms:sdk';


// 'my-plugin' here is used as the identifier for
// the pageType from the plugin definition
const pages = await runSDK(SDKCoreJs.GET.packagePages('my-plugin'));


// Get the 5 most recently updated pages from the last 30 days
const recentlyUpdatedPages = pages
    .filter((page) => {
        const now = new Date();
        const thirtyDaysAgo = new Date(now.setDate(now.getDate() - 30));
        return new Date(page.updatedAt) > thirtyDaysAgo;
    })
    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
    .slice(0, 5);
---


<div>
    <h2>Recently Updated Pages</h2>
    <ul>
        {recentlyUpdatedPages.length > 0 && recentlyUpdatedPages.map((page) => (
            <li>
                <a href={Astro.locals.routeMap.mainLinks.contentManagementEdit + `?edit=${page.id}`}>{page.title}</a>
            </li>
        ))}
    </ul>
</div>

The above example defines a grid item for the plugin that displays the 5 most recently updated pages from the last 30 days. The grid item includes a list of links to the content management edit page for each page.

Section titled “Integrating with the FrontendNavigationLinks helpers”

If you are looking to use the built-in StudioCMS navigation helpers in your project, similar to the way the @studiocms/blog plugin does, you can create a custom Navigation.astro component:

Navigation.astro
---
import { frontendNavigation } from 'studiocms:plugin-helpers';


// Define the props for the Navigation component
interface Props {
  topLevelLinkCount?: number;
};


// Get the top level link count from the props
const { topLevelLinkCount = 3 } = Astro.props;


// Get the site config and page list
const config = Astro.locals.siteConfig.data;


// Get the site title from the config
const { title } = config || { title: 'StudioCMS' };


// Get the main site URL
const {
  mainLinks: { baseSiteURL },
} = Astro.locals.routeMap;


// Define the link props for the navigation
type LinkProps = {
  text: string;
  href: string;
};


// Define the links for the navigation
const links: LinkProps[] = await frontendNavigation();
---
{/* If no dropdown items */}
{ ( links.length < topLevelLinkCount || links.length === topLevelLinkCount ) && (
    <div class="navigation">
        <div class="title"><a href={baseSiteURL}>{title}</a></div>
        <div class="mini-nav">
            <button>Menu</button>
            <div class="mini-nav-content">
            {
                links.map(({ text, href }) => (
                    <a {href}>{text}</a>
                ))
            }
            </div>
        </div>
        {
            links.map(({ text, href }) => (
                <a class="links" {href}>{text}</a>
            ))
        }
    </div>
) }


{/* If dropdown items */}
{ links.length > topLevelLinkCount && (
    <div class="navigation">
        <div class="title"><a href={baseSiteURL}>{title}</a></div>


        <div class="mini-nav">
            <button>Menu</button>
            <div class="mini-nav-content">
            {
                links.map(({ text, href }) => (
                    <a {href}>{text}</a>
                ))
            }
            </div>
        </div>
        {
            links.slice(0, topLevelLinkCount).map(({ text, href }) => (
                    <a class="links" {href}>{text}</a>
            ))
        }
            <div class="dropdown">
                <button>More ▼</button>
                <div class="dropdown-content">
                    { links.slice(topLevelLinkCount).map(({ text, href }) => (
                        <a {href}>{text}</a>
                    )) }
                </div>
            </div>
    </div>
) }

The above example defines a custom Navigation.astro component that uses the built-in StudioCMS navigation helpers to create a navigation menu for the project. The component includes links to the main site URL, the index page, and any other pages that are set to show on the navigation.

All you need to do is add some styles, and you have a fully functional navigation menu that works with the built-in StudioCMS navigation helpers.