sonicjs/docs/ai/plugin-system-documentation.md
Lane Campbell 9b3020f79c chore: publish core 2.0.3 and create-app beta.10 packages
- Bumped @sonicjs-cms/core from 2.0.2 to 2.0.3
- Published core package to npm
- Updated create-app CLI to use core@^2.0.3
- Bumped create-sonicjs from 2.0.0-beta.9 to 2.0.0-beta.10
- Published create-app package to npm
- Verified both packages install correctly

Additional cleanup:
- Moved scripts/generate-plugin-registry.mjs to packages/scripts/
- Updated all references to new script location
- Removed obsolete scripts folder (15 files deleted)
- Updated documentation for installation and script paths
- Cleaned up package.json (removed sync-collections and sonicjs CLI)

๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-27 15:53:19 -07:00

17 KiB

SonicJS Plugin System Documentation

Version: 2.0.2 Last Updated: October 24, 2025 Status: Production Ready

Overview

The SonicJS plugin system provides a powerful, extensible architecture for adding functionality to your CMS. All plugins are included in the @sonicjs-cms/core package and can be enabled/disabled via configuration.

Included Plugins

SonicJS v2.0.2 includes 13 plugins across 6 categories:

Core Plugins (4)

  1. Cache System (core-cache)
  2. Analytics & Insights (core-analytics)
  3. Authentication System (core-auth)
  4. Media Manager (core-media)

Content Plugins (4)

  1. FAQ Manager (faq-plugin)
  2. Testimonials (testimonials-plugin)
  3. Code Examples (code-examples-plugin)
  4. Workflow Engine (workflow-plugin)

Development Plugins (2)

  1. Database Tools (database-tools)
  2. Seed Data Generator (seed-data)

Utility Plugins (2)

  1. Demo Login (demo-login-plugin)
  2. Hello World (hello-world)

UI Plugins (1)

  1. Design System (design)

Plugin Details

1. Cache System (core-cache)

Category: Performance Version: 1.0.0-beta.1 Author: SonicJS

Description: Three-tiered caching system with in-memory and KV storage. Provides automatic caching for content, users, media, and API responses with configurable TTL and invalidation patterns.

Settings:

  • memoryEnabled (boolean, default: true) - Enable in-memory cache (tier-1)
  • kvEnabled (boolean, default: false) - Enable KV cache (tier-2, global)
  • defaultTTL (number, default: 3600) - Default time-to-live in seconds
  • maxMemorySize (number, default: 50) - Max memory cache size in MB

Routes:

  • GET /admin/cache/stats - View cache statistics
  • POST /admin/cache/clear - Clear all cache entries
  • POST /admin/cache/invalidate - Invalidate cache entries by pattern

Permissions:

  • cache.view - View cache statistics
  • cache.clear - Clear cache entries
  • cache.invalidate - Invalidate cache patterns

Hooks:

  • onActivate, onDeactivate, onConfigure

Use Cases:

  • Speed up content delivery
  • Reduce database queries
  • Improve API response times
  • Global content distribution via Cloudflare KV

2. Analytics & Insights (core-analytics)

Category: Analytics Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Core analytics system for tracking page views, user behavior, and content performance. Provides dashboards and reports with real-time metrics.

Settings:

  • trackPageViews (boolean, default: true) - Automatically track page views
  • trackUserSessions (boolean, default: true) - Track user session duration
  • retentionDays (number, default: 90) - Data retention period in days

Admin Menu:

  • Label: "Analytics"
  • Icon: chart-bar
  • Path: /admin/analytics
  • Order: 50

Permissions:

  • analytics:view - View analytics data
  • analytics:export - Export analytics reports

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Track content performance
  • Monitor user engagement
  • Generate usage reports
  • Identify trending content

3. Authentication System (core-auth)

Category: Security Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Core authentication and user management system with role-based access control (RBAC), session management, and security features.

Settings:

  • sessionTimeout (number, default: 60) - Auto-logout after N minutes of inactivity
  • maxLoginAttempts (number, default: 5) - Lock account after N failed attempts
  • requireStrongPasswords (boolean, default: true) - Enforce password complexity

Permissions:

  • manage:users - Manage users and accounts
  • manage:roles - Manage user roles
  • manage:permissions - Manage permission settings

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • User authentication and authorization
  • Role-based access control (RBAC)
  • Session management
  • Account security and lockout

4. Media Manager (core-media)

Category: Media Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Core media upload and management system with support for images, videos, and documents. Includes automatic optimization, thumbnail generation, and cloud storage integration (Cloudflare R2).

Settings:

  • maxFileSize (number, default: 10) - Maximum upload size in MB
  • allowedFileTypes (string, default: "jpg,jpeg,png,gif,webp,pdf,mp4,mp3") - Allowed extensions
  • autoOptimize (boolean, default: true) - Auto-optimize images on upload
  • generateThumbnails (boolean, default: true) - Auto-generate thumbnails

Admin Menu:

  • Label: "Media"
  • Icon: image
  • Path: /admin/media
  • Order: 30

Permissions:

  • manage:media - Manage media library
  • upload:files - Upload files

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Image and video uploads
  • Document management
  • Thumbnail generation
  • Cloud storage with Cloudflare R2

5. FAQ Manager (faq-plugin)

Category: Content Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Frequently Asked Questions management plugin with categorization, search, and display templates.

Permissions:

  • faq:manage - Manage FAQ content

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Create FAQ sections
  • Categorize questions
  • Search functionality
  • Display templates for frontend

6. Testimonials (testimonials-plugin)

Category: Content Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Customer testimonials and reviews management with display widgets and ratings.

Permissions:

  • testimonials:manage - Manage testimonials

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Collect customer testimonials
  • Display reviews on website
  • Rating system
  • Social proof widgets

7. Code Examples (code-examples-plugin)

Category: Content Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Code snippets and examples library with syntax highlighting and categorization.

Permissions:

  • code-examples:manage - Manage code examples

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Documentation with code examples
  • Developer documentation
  • API examples
  • Tutorial content

8. Workflow Engine (workflow-plugin)

Category: Content Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Content workflow and approval system with customizable states, transitions, and review processes.

Settings:

  • requireApproval (boolean, default: true) - Require approval before publishing
  • notifyReviewers (boolean, default: true) - Send notifications to reviewers

Permissions:

  • workflow:manage - Manage workflow settings
  • workflow:approve - Approve content

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Content approval workflows
  • Multi-stage publishing
  • Editorial review process
  • Collaboration features

9. Database Tools (database-tools)

Category: Development Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Database management and administration tools including migrations, backups, and query execution.

Permissions:

  • database:admin - Administer database

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Database migrations
  • Backup and restore
  • Query execution
  • Database inspection

10. Seed Data Generator (seed-data)

Category: Development Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Development tool for generating sample data and testing content. Useful for demos and development environments.

Permissions:

  • seed-data:generate - Generate seed data

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Generate demo data
  • Testing environments
  • Development setup
  • Sample content creation

11. Demo Login (demo-login-plugin)

Category: Utilities Version: 1.0.0-beta.1 Author: SonicJS Team

Description: Quick demo login functionality for testing and demonstrations.

Dependencies: core-auth

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Demo environments
  • Quick testing
  • Prototype presentations
  • Development convenience

12. Hello World (hello-world)

Category: Utilities Version: 1.0.0-beta.1 Author: SonicJS Team

Description: A simple Hello World plugin demonstration showing basic plugin structure.

Admin Menu:

  • Label: "Hello World"
  • Icon: hand-raised
  • Path: /admin/hello-world
  • Order: 90

Permissions:

  • hello-world:view - View Hello World page

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Plugin development reference
  • Learning plugin structure
  • Testing plugin system

13. Design System (design)

Category: UI Version: 1.0.0-beta.1 Author: SonicJS

Description: Design system management including themes, components, and UI customization. Provides a visual interface for managing design tokens, typography, colors, and component library.

Settings:

  • defaultTheme (string, default: "dark") - Default theme (light, dark, auto)
  • customCSS (boolean, default: false) - Allow custom CSS overrides

Routes:

  • GET /admin/design - Design system management page

Admin Menu:

  • Label: "Design"
  • Icon: palette
  • Path: /admin/design
  • Order: 80

Permissions:

  • design.view - View design system
  • design.edit - Edit design settings

Hooks:

  • onActivate, onDeactivate

Use Cases:

  • Theme customization
  • UI component management
  • Design token configuration
  • Brand customization

Plugin System Architecture

Plugin Manifest Structure

Every plugin requires a manifest.json file:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": "Your Name",
  "homepage": "https://example.com",
  "repository": "https://github.com/user/plugin",
  "license": "MIT",
  "category": "content",
  "tags": ["tag1", "tag2"],
  "dependencies": ["other-plugin-id"],
  "settings": {
    "settingKey": {
      "type": "boolean",
      "label": "Setting Label",
      "description": "Setting description",
      "default": true
    }
  },
  "hooks": {
    "onActivate": "activate",
    "onDeactivate": "deactivate"
  },
  "routes": [
    {
      "path": "/admin/my-plugin",
      "method": "GET",
      "handler": "getPage",
      "description": "Get plugin page"
    }
  ],
  "permissions": {
    "my-plugin:manage": "Manage my plugin"
  },
  "adminMenu": {
    "label": "My Plugin",
    "icon": "icon-name",
    "path": "/admin/my-plugin",
    "order": 50
  }
}

Plugin Registry

All plugins are auto-discovered and registered at build time via packages/scripts/generate-plugin-registry.mjs:

import { PLUGIN_REGISTRY, PLUGIN_IDS, CORE_PLUGIN_IDS } from './plugins/plugin-registry'

// Get all plugin IDs
console.log(PLUGIN_IDS) // All 13 plugins

// Get core plugin IDs
console.log(CORE_PLUGIN_IDS) // Core plugins only

// Get plugin manifest
const manifest = PLUGIN_REGISTRY['core-cache']

Plugin Categories

  • performance: Caching, optimization
  • analytics: Tracking, reporting, metrics
  • security: Authentication, authorization
  • media: Upload, storage, optimization
  • content: Content types, management
  • development: Tools, utilities, debugging
  • utilities: General purpose tools
  • ui: Themes, design, customization

Plugin Lifecycle Hooks

  • onActivate - Called when plugin is enabled
  • onDeactivate - Called when plugin is disabled
  • onConfigure - Called when settings change

Plugin Permissions

Plugins can define custom permissions that integrate with the RBAC system:

"permissions": {
  "plugin:action": "Description of permission"
}

Plugin Settings

Plugins can define configurable settings with types:

  • boolean - True/false toggle
  • string - Text input
  • number - Numeric input
  • array - List of values

Plugin Routes

Plugins can register custom routes:

"routes": [
  {
    "path": "/admin/custom-path",
    "method": "GET",
    "handler": "handlerFunctionName",
    "description": "Route description"
  }
]

Admin Menu Integration

Plugins can add items to the admin sidebar:

"adminMenu": {
  "label": "Menu Label",
  "icon": "heroicon-name",
  "path": "/admin/path",
  "order": 50  // Lower = higher in menu
}

Using Plugins

Enable/Disable Plugins

// In your sonicjs.config.ts
export default {
  plugins: {
    enabled: [
      'core-cache',
      'core-analytics',
      'faq-plugin',
      'testimonials-plugin'
    ],
    disabled: [
      'demo-login-plugin'  // Disable in production
    ]
  }
}

Configure Plugin Settings

// In your sonicjs.config.ts
export default {
  plugins: {
    settings: {
      'core-cache': {
        memoryEnabled: true,
        kvEnabled: true,
        defaultTTL: 7200
      },
      'core-media': {
        maxFileSize: 20,
        autoOptimize: true
      }
    }
  }
}

Access Plugin Functionality

import { PluginManager } from '@sonicjs-cms/core'

// Get plugin instance
const cachePlugin = await PluginManager.getPlugin('core-cache')

// Call plugin methods
await cachePlugin.clear()
const stats = await cachePlugin.getStats()

Creating Custom Plugins

1. Create Plugin Directory Structure

src/plugins/my-plugin/
โ”œโ”€โ”€ manifest.json
โ”œโ”€โ”€ index.ts
โ”œโ”€โ”€ handlers/
โ”‚   โ””โ”€โ”€ routes.ts
โ””โ”€โ”€ README.md

2. Define Manifest

See manifest structure above.

3. Implement Plugin Interface

// src/plugins/my-plugin/index.ts
import type { Plugin, PluginContext } from '@sonicjs-cms/core'

export const myPlugin: Plugin = {
  async activate(context: PluginContext) {
    const { hookSystem, logger } = context

    // Register hooks
    hookSystem.register('content:beforeSave', async (data) => {
      // Your logic
      return data
    })

    await logger.info('plugin', 'Plugin activated', { plugin: 'my-plugin' })
  },

  async deactivate(context: PluginContext) {
    const { logger } = context
    await logger.info('plugin', 'Plugin deactivated', { plugin: 'my-plugin' })
  }
}

4. Register Routes (Optional)

// src/plugins/my-plugin/handlers/routes.ts
import { Hono } from 'hono'

export const myPluginRoutes = new Hono()

myPluginRoutes.get('/admin/my-plugin', async (c) => {
  return c.html('<h1>My Plugin</h1>')
})

5. Rebuild Plugin Registry

npm run plugins:generate

Plugin Testing

Unit Tests

import { describe, it, expect } from 'vitest'
import { myPlugin } from './index'

describe('My Plugin', () => {
  it('should activate successfully', async () => {
    const context = createMockContext()
    await myPlugin.activate(context)
    expect(context.logger.info).toHaveBeenCalled()
  })
})

Integration Tests

import { test, expect } from '@playwright/test'

test('plugin route works', async ({ page }) => {
  await page.goto('/admin/my-plugin')
  await expect(page.locator('h1')).toContainText('My Plugin')
})

Plugin Best Practices

  1. Versioning: Use semantic versioning (MAJOR.MINOR.PATCH)
  2. Dependencies: Minimize dependencies, declare them in manifest
  3. Error Handling: Always handle errors gracefully
  4. Logging: Use the logger service for all logging
  5. Permissions: Define granular permissions
  6. Settings: Provide sensible defaults
  7. Documentation: Include README.md with usage examples
  8. Testing: Write comprehensive tests
  9. TypeScript: Use strict typing
  10. Hooks: Clean up resources in deactivate hook

Plugin Verification

All 13 plugins have been validated and registered in the plugin registry:

npm run plugins:generate

Output:

โœ… Loaded 13 valid manifests
๐Ÿ“ Generated plugin registry: src/plugins/plugin-registry.ts

Summary:
  - Total plugins: 13
  - Registry file: src/plugins/plugin-registry.ts
  - Core plugins: 4

Next Steps

  1. Explore Plugins: Visit /admin/plugins to see all available plugins
  2. Enable Plugins: Configure which plugins to enable in your project
  3. Customize Settings: Adjust plugin settings to fit your needs
  4. Create Custom Plugins: Build your own plugins for custom functionality
  5. Contribute: Share your plugins with the SonicJS community

Support


Last Updated: October 24, 2025 Core Version: 2.0.2 Total Plugins: 13