A plugin is a self-contained directory inside plugins/ consisting of exactly three required files. Each file has a distinct responsibility: the manifest declares metadata, the server file registers backend logic, and the admin file provides the frontend integration.

plugins/
└── my-plugin/
    ├── plugin.json     # Manifest — name, slug, description, version, author
    ├── server.js       # Backend: Fastify routes, hooks
    └── admin.js        # Frontend: admin views, sidebar entries

Enable or disable any plugin by editing config/plugins.json. The CMS will not load a plugin unless its entry is present and enabled is set to true.

[
  { "slug": "my-plugin", "enabled": true }
]

Disabling a plugin ("enabled": false) is non-destructive — the directory and all its data remain intact.

The manifest is the single source of truth for plugin identity and capabilities. The CMS reads it before loading any code, so mismatches here will prevent the plugin from mounting.

{
  "name": "My Plugin",
  "slug": "my-plugin",
  "version": "1.0.0",
  "description": "Does something useful",
  "author": "Your Name",
  "minCmsVersion": "0.5.0",
  "permissions": ["pages:read", "collections:read"],
  "public": {
    "injectHead": "head.html",
    "injectBody": "body.html"
  },
  "adminNav": {
    "text": "My Plugin",
    "icon": "package",
    "view": "my-plugin"
  }
}

The server.js file exports a standard Fastify plugin function. The CMS passes an opts object containing a cms property which exposes the full CMS service layer — content, collections, media, users, and hooks.

export default async function(fastify, opts) {
    const { cms } = opts;  // Access to CMS service layer

    // Register Fastify routes
    fastify.get('/api/my-plugin/data', async (request, reply) => {
        // Access CMS services:
        const pages = await cms.content.getAll();
        return { pages };
    });

    fastify.post('/api/my-plugin/action', {
        preHandler: [fastify.authenticate]  // Require auth
    }, async (request, reply) => {
        // ...
    });
}

The admin.js file exports a view definition that the Domma CMS admin SPA registers at runtime. Views are mounted inside the admin shell — the full Domma API is available in onMount.

export default {
    views: {
        'my-plugin': {
            title: 'My Plugin',
            template: `
                <div class="container py-6">
                    <h1>My Plugin</h1>
                    <!-- Domma components work here -->
                </div>
            `,
            onMount($el) {
                H.get('/api/my-plugin/data').then(data => {
                    T.create('#my-table', { data: data.pages, columns: [...] });
                });
            }
        }
    },
    sidebar: [
        { text: 'My Plugin', icon: 'package', view: 'my-plugin' }
    ]
}

Plugins can intercept CMS lifecycle events by registering hook callbacks via cms.hooks.on(). Hooks allow plugins to modify content before rendering, react to form submissions, register custom shortcodes, and sanitise HTML output — all without patching core CMS code.

// In server.js
cms.hooks.on('page:before-render', (page) => {
    // Modify page before rendering
    page.content += '\n<!-- rendered by my-plugin -->';
    return page;
});

cms.hooks.on('form:submission', async (submission) => {
    // React to form submissions
    await sendToExternalCRM(submission);
});

// Register a custom shortcode
cms.hooks.registerShortcode('my-widget', (attrs) => {
    return `<div class="my-widget">${attrs.content}</div>`;
});

// Sanitize hook (modify HTML after rendering)
cms.hooks.on('html:sanitize', (html) => html.replace(/foo/g, 'bar'));

Plugins can inject HTML into every public page without touching the theme templates. Two injection slots are available, both declared in plugin.json under the public key and resolved relative to the plugin directory.

<!-- head.html -->
<link rel="stylesheet" href="/plugins/my-plugin/style.css">
<meta name="my-plugin-version" content="1.0.0">

<!-- body.html -->
<script src="/plugins/my-plugin/tracker.js"></script>

Injections are only active when the plugin is enabled. Disabling the plugin immediately removes all injections from public pages without requiring a restart.

Domma CMS ships with a set of ready-to-enable plugins. They are installed but disabled by default — add the relevant entry to config/plugins.json to activate any of them.

Enable any bundled plugin by adding its slug to config/plugins.json:

[
  { "slug": "analytics",      "enabled": true },
  { "slug": "cookie-consent", "enabled": true },
  { "slug": "back-to-top",    "enabled": true }
]

Follow these steps to build and register a minimal working plugin — a simple hit counter with an admin view and an increment button.

1. Create the directory

   mkdir plugins/my-counter

2. Write plugin.json — name, slug, version, description

   {
     "name": "My Counter",
     "slug": "my-counter",
     "version": "1.0.0",
     "description": "A simple hit counter",
     "author": "Your Name",
     "adminNav": {
       "text": "Counter",
       "icon": "hash",
       "view": "my-counter"
     }
   }

3. Write server.js — register GET /api/my-counter/count returning a stored count

   export default async function(fastify, opts) {
       const { cms } = opts;
       let count = 0;
   
       fastify.get('/api/my-counter/count', async () => ({ count }));
   
       fastify.post('/api/my-counter/increment', {
           preHandler: [fastify.authenticate]
       }, async () => {
           count += 1;
           return { count };
       });
   }

4. Write admin.js — view with a counter display and increment button using Domma UI

   export default {
       views: {
           'my-counter': {
               title: 'Counter',
               template: `
                   <div class="container py-6">
                       <h1 class="mb-4">Hit Counter</h1>
                       <p class="text-xl mb-4">Count: <strong id="count-display">...</strong></p>
                       <button id="increment-btn" class="btn btn-primary">Increment</button>
                   </div>
               `,
               onMount($el) {
                   H.get('/api/my-counter/count').then(data => {
                       $el.find('#count-display').text(data.count);
                   });
   
                   $el.find('#increment-btn').on('click', () => {
                       H.post('/api/my-counter/increment').then(data => {
                           $el.find('#count-display').text(data.count);
                           E.toast('Counter incremented', { type: 'success' });
                       });
                   });
               }
           }
       },
       sidebar: [
           { text: 'Counter', icon: 'hash', view: 'my-counter' }
       ]
   }

5. Register the plugin — add to config/plugins.json

   [
     { "slug": "my-counter", "enabled": true }
   ]

6. Start the server

   npm run dev

7. View in admin — the Counter sidebar entry appears automatically. Navigate to it to see the counter and increment button.
8. Public injection (optional) — create head.html and/or body.html in the plugin directory and declare them under the public key in plugin.json to inject content into every public page.