Content Workers Plugin SDK

The official SDK for building plugins for Content Workers CMS. Create powerful extensions with backend APIs, admin UI components, and lifecycle hooks using a modern, type-safe development experience.

Features

• 🏗️ Fluent API Builder: Intuitive plugin creation with method chaining
• 🔒 Type Safety: Full TypeScript support with runtime validation
• 🚀 Backend APIs: Create custom REST endpoints with Hono integration
• 🎨 Admin UI Extensions: Add sidebar items, routes, and settings panels
• 🔄 Lifecycle Hooks: Hook into application startup, config, and shutdown
• 📦 Service Registration: Register custom services and middleware
• ✅ Validation: Built-in Zod schema validation
• 🧪 Testing Ready: Easy local development and testing

Quick Start

Installation

npm install @content-workers/plugin-sdk @content-workers/core

Create Your First Plugin

import { createPlugin } from "@content-workers/plugin-sdk";

export const myPlugin = createPlugin()
    .metadata((meta) => 
        meta.key("my-plugin")
            .name("My Awesome Plugin")
            .version("1.0.0")
            .description("Does amazing things")
    )
    .hooks((hooks) =>
        hooks.init(async () => {
            console.log("🚀 Plugin initialized!");
            return { error: undefined, data: undefined };
        })
    )
    .routes((routes) => 
        routes.add(async (app, context) => {
            app.get("/api/v1/plugins/my-plugin/hello", (c) => {
                return c.json({ message: "Hello from my plugin!" });
            });
        })
    )
    .admin((admin) =>
        admin.sidebarItem({
            key: "my-plugin",
            label: "My Plugin",
            route: "/admin/plugins/my-plugin"
        })
    )
    .build();

export default myPlugin;

Register Plugin

// cw.config.ts
import MyPlugin from "./my-plugin";

export default defineConfig((env) => ({
    plugins: [
        MyPlugin({
            // Plugin configuration options
        })
    ]
}));

Documentation

📚 Complete Plugin Development Guide

Comprehensive guide covering:

• Plugin architecture and best practices
• Backend API development
• Admin UI extensions
• Configuration and types
• Testing and debugging
• Publishing to npm

⚡ Quick Reference

Essential patterns and templates:

• Plugin creation template
• API route patterns
• Zod schema examples
• Service class templates
• Error handling patterns

🎯 Demo Plugin Example

Complete working example showing:

• Full CRUD API implementation
• Task management system
• Admin UI configuration
• TypeScript types and validation
• Service architecture

Plugin SDK API

Core Builder Methods

createPlugin<PluginOptions>()
    .metadata((meta) => meta.key("plugin-key").name("Plugin Name"))
    .hooks((hooks) => hooks.init(initHandler))
    .routes((routes) => routes.add(routeHandler))
    .services((services) => services.add("serviceName", serviceInstance))
    .admin((admin) => admin.sidebarItem({ key: "item", label: "Label" }))
    .checkCompatibility((checker) => checker(compatibilityHandler))
    .build();

Metadata Configuration

• key(string) - Unique plugin identifier
• name(string) - Human-readable plugin name
• version(string) - Plugin version
• description(string) - Plugin description
• lucid(string) - Compatible Content Workers version

Lifecycle Hooks

• init() - Called when plugin initializes
• afterConfig() - Called after config is processed
• beforeServerStart() - Called before server starts
• beforeDestroy() - Called before app shutdown
• build() - Called during build process

Route Registration

Register custom API endpoints with full Hono integration:

.routes((routes) =>
    routes.add(async (app, context) => {
        app.get("/api/v1/plugins/my-plugin/items", handler);
        app.post("/api/v1/plugins/my-plugin/items", handler);
    })
)

Admin UI Extensions

• sidebarItem() - Add navigation items
• route() - Define admin routes
• settingsPanel() - Add settings panels
• entry() - Custom JavaScript entry point
• css() - Custom CSS styles

Examples

Simple Plugin

export const simplePlugin = createPlugin()
    .metadata((meta) => meta.key("simple").name("Simple Plugin"))
    .hooks((hooks) => 
        hooks.init(async () => {
            console.log("Simple plugin loaded!");
            return { error: undefined, data: undefined };
        })
    )
    .build();

API Plugin with Validation

import { z } from "zod";

const CreateItemSchema = z.object({
    name: z.string().min(1),
    description: z.string().optional()
});

export const apiPlugin = createPlugin()
    .metadata((meta) => meta.key("api-plugin"))
    .routes((routes) =>
        routes.add(async (app, context) => {
            app.post("/api/v1/plugins/api-plugin/items", async (c) => {
                try {
                    const body = await c.req.json();
                    const data = CreateItemSchema.parse(body);
                    // Process data...
                    return c.json({ success: true, data });
                } catch (error) {
                    return c.json({ success: false, error: error.message }, 400);
                }
            });
        })
    )
    .build();

Full-Featured Plugin

interface PluginOptions {
    apiKey: string;
    enabled?: boolean;
}

export const fullPlugin = createPlugin<PluginOptions>()
    .metadata((meta) => 
        meta.key("full-plugin")
            .name("Full Featured Plugin")
            .version("1.0.0")
    )
    .hooks((hooks) =>
        hooks
            .init(async () => ({ error: undefined, data: undefined }))
            .beforeServerStart(async (context) => {
                console.log("Setting up plugin resources...");
            })
    )
    .routes((routes) => routes.add(registerApiRoutes))
    .services((services) => services.add("myService", new MyService()))
    .admin((admin) =>
        admin
            .sidebarItem({
                key: "full-plugin",
                label: "Full Plugin",
                route: "/admin/plugins/full-plugin"
            })
            .route({
                key: "list",
                path: "/admin/plugins/full-plugin",
                permission: "full-plugin:read"
            })
    )
    .build();

Development Workflow

1. Create Plugin Package

   mkdir my-plugin && cd my-plugin
   npm init -y
   npm install @content-workers/plugin-sdk

2. Develop Plugin

   • Write plugin code using SDK
   • Add to starter-app for testing
   • Test API endpoints and admin UI

3. Build & Test

   npm run build
   npm run dev  # Test in development

4. Publish

   npm publish --access public

TypeScript Support

The SDK provides full TypeScript support with:

• Strongly typed plugin options
• Type-safe route handlers
• Validated configuration schemas
• IntelliSense for all API methods
• Runtime type checking with Zod

Compatibility

• Content Workers: ^0.12.0
• Node.js: ^24.0.0
• TypeScript: ^5.8.0
• Hono: ^4.7.11

Contributing

1. Fork the repository
2. Create your feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE for details.

Support

• 📖 Documentation
• 🎯 Examples
• 🐛 Issues
• 💬 Discord Community

Build amazing plugins for Content Workers! 🚀