Plugin System

Overview

Codapult ships with a plugin system that lets you extend the platform without modifying core code. Plugins can add sidebar navigation, settings panels, API routes, and react to lifecycle events.

All plugins implement the CodapultPlugin interface from src/lib/plugins/types and are registered in codapult.plugins.ts.

Extension Points

Creating a Plugin

Step 1: Create the Plugin Directory

mkdir -p plugins/my-plugin/components

Plugin names must be kebab-case and match the directory name.

Step 2: Implement the Interface

Create plugins/my-plugin/index.ts:

import type { CodapultPlugin } from '@/lib/plugins/types';

const myPlugin: CodapultPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'Adds custom analytics to the dashboard',

  navItems: [
    {
      id: 'my-analytics',
      label: 'My Analytics',
      href: '/dashboard/my-analytics',
      icon: 'BarChart3',
      order: 50,
    },
  ],

  settingsPanels: [
    {
      id: 'my-plugin-settings',
      label: 'My Plugin',
      component: './components/Settings',
      order: 100,
    },
  ],

  apiRoutes: [
    {
      method: 'GET',
      path: '/stats',
      handler: async (req) => {
        return new Response(JSON.stringify({ visits: 42 }), {
          headers: { 'Content-Type': 'application/json' },
        });
      },
    },
  ],

  async onInit() {
    console.log('My plugin initialized');
  },

  async onUserCreated({ user }) {
    console.log(`New user: ${user.email}`);
  },

  async onSubscriptionChanged({ userId, plan, status }) {
    console.log(`Subscription changed: ${userId} → ${plan} (${status})`);
  },

  async onPaymentCompleted({ userId, amount, currency }) {
    console.log(`Payment received: ${amount} ${currency} from ${userId}`);
  },
};

export default myPlugin;

Step 3: Register the Plugin

Add your plugin to codapult.plugins.ts:

import { registerPlugin } from '@/lib/plugins';
import myPlugin from './plugins/my-plugin';

registerPlugin(myPlugin);

The plugin's nav items, settings panels, and API routes are now live. API routes are accessible at /api/plugins/my-plugin/stats.

Bundled Example

Codapult includes a reference plugin at plugins/example-analytics/ that demonstrates all extension points. Use it as a starting point for your own plugins.

Plugin Rules

• Plugin name must be kebab-case and match the directory name.
• API routes are automatically prefixed with /api/plugins/<name>/.
• Never import plugin code from core — plugins depend on core, not the other way around.
• Handle errors in hooks — the registry wraps onInit in try/catch, but lifecycle hooks should handle their own errors gracefully.
• Settings panels are lazy-loaded — the component path is resolved relative to the plugin directory.

Premium Plugins

Four premium plugins are available separately. Each adds a full-featured module with its own UI, API, database tables, and AI capabilities.

Installation

Install any premium plugin via the Codapult CLI:

npx @codapult/cli plugins add @codapult/plugin-ai-kit

Each plugin ships with its own README.md and INSTALL.md containing step-by-step installation instructions, required environment variables, and database migration commands.

Removal

Remove a premium plugin with:

npx @codapult/cli plugins remove @codapult/plugin-ai-kit

The CLI removes the plugin's files, unregisters it from codapult.plugins.ts, and cleans up database tables.