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. It is disabled by default so the dashboard UI stays clean out of the box — the files are shipped purely as a compile-checked, typechecked reference and as a starting point for your own plugins.

To enable it locally, create src/plugins/example-analytics.ts with:

import { registerPlugin } from '@/lib/plugins';
import plugin from '../../plugins/example-analytics';

registerPlugin(plugin);

Then add the import to src/plugins/index.ts:

import './example-analytics';

To use it as a template for a new plugin, copy the directory and rename it:

cp -r plugins/example-analytics plugins/my-plugin

Then update name, routes and content, and register it via npx @codapult/cli plugins add my-plugin.

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.

Testing Plugins

Co-locate unit tests with your plugin code:

plugins/my-plugin/
├── index.ts
├── index.test.ts       ← test the plugin
└── components/
    └── Settings.tsx

Test lifecycle hooks and API route handlers in isolation using Vitest. Mock core dependencies (db, getAppSession) as needed. The dev server picks up plugin changes on reload — no restart required.

Upgrading Codapult with Plugins Installed

When upgrading Codapult to a new version, premium plugin schema patches may need re-applying. After merging the upstream update, run:

npx @codapult/cli plugins migrate

This re-checks all installed plugins against the current schema.ts and generates any needed migration files.

Premium Plugins

Four premium plugins are available separately. Each adds a full-featured module with its own UI, API routes, database tables, and AI capabilities. See the dedicated documentation for each plugin:

Installation

Premium plugins are distributed as private GitHub repositories. After purchase you receive an invite to the plugin repo. There are two ways to install:

Option A: Clone the repo locally (recommended for development)

Clone the plugin repository next to your Codapult project, then install:

git clone git@github.com:codapult/codapult-plugin-ai-kit.git
npx @codapult/cli plugins add ai-kit

The CLI looks for sibling directories named codapult-plugin-<name>, reads the manifest, patches your project, and runs pnpm install.

Option B: Install directly from GitHub

Use --from to clone and install in one step:

npx @codapult/cli plugins add ai-kit --from git@github.com:codapult/codapult-plugin-ai-kit.git

The plugin is cloned into .codapult/plugins/ inside your project and linked as a file: dependency. This works on any machine with git access to the repository.

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

Plugin Resolution Order

When you run plugins add <name>, the CLI searches in this order:

1. Absolute/relative path — if you pass a file path instead of a name
2. Sibling directories — ../codapult-plugin-<name>/, ../codapult-<name>/, ../<name>/
3. Local cache — .codapult/plugins/codapult-plugin-<name>/ (populated by --from)

Updating

When a plugin releases a new version with schema changes, pull the latest code and run migrations:

# If installed as sibling (Option A):
cd ../codapult-plugin-ai-kit && git pull

# If installed via --from (Option B):
cd .codapult/plugins/codapult-plugin-ai-kit && git pull

# Then migrate:
npx @codapult/cli plugins migrate ai-kit

The migrate command compares the plugin's latest schema with what's currently in your schema.ts, patches the difference, and generates a migration file via drizzle-kit. You can then review and apply the migration. Use --push for development (calls db:push directly).

To migrate all installed plugins at once:

npx @codapult/cli plugins migrate

Removal

Remove a premium plugin with:

npx @codapult/cli plugins remove ai-kit

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