Plugin Development Guide

mkdir -p src/plugins/my-plugin

import { definePlugin } from '@sonicjs-cms/core'
import { html } from 'hono/html'

export const myPlugin = definePlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',
  description: 'My first SonicJS plugin',
  author: 'Your Name',

  menu: [
    {
      label: 'My Plugin',
      path: '/admin/my-plugin',
      icon: 'puzzle-piece',
      order: 100,
    },
  ],

  register(app) {
    app.get('/admin/my-plugin', async (c) => {
      const user = c.get('user')
      return c.html(html`<h1>Hello from My Plugin!</h1>`)
    })
  },

  async activate(ctx) {
    console.info('My plugin activated!')
  },

  async deactivate(ctx) {
    console.info('My plugin deactivated!')
  },
})

import { registerPlugins } from '@sonicjs-cms/core'
import { myPlugin } from './plugins/my-plugin'

// after app + hookSystem are created:
registerPlugins(app, [myPlugin], { hookSystem, env })

export const myPlugin = definePlugin({
  id: 'my-plugin',
  version: '1.0.0',

  // PHASE 1 — sync, routes only. No await, no env access.
  register(app) {
    app.get('/api/my-plugin/items', async (c) => {
      // env IS available inside a request handler (c.env)
      const db = c.env.DB
      const rows = await db.prepare('SELECT id FROM documents WHERE type_id = ?')
        .bind('my-plugin-item').all()
      return c.json({ data: rows.results })
    })
  },

  // PHASE 2 — async, runs once on first request.
  async onBoot(ctx) {
    ctx.hooks.on('content:after:create', (payload) => {
      console.info('Created:', payload.id)
    })
    // seed document type, etc.
  },
})

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

export const myPlugin = definePlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',

  register(app) {
    app.get('/api/my-plugin/items', async (c) => {
      return c.json({ success: true, data: [] })
    })

    app.post('/api/my-plugin/items', async (c) => {
      const body = await c.req.json()
      return c.json({ success: true, data: body }, 201)
    })
  },
})

definePlugin({
  // ...
  capabilities: ['hooks.content:subscribe'],

  async onBoot(ctx) {
    // typed hook subscription — payload is ContentEventPayload
    ctx.hooks.on('content:after:create', (payload) => {
      console.info('Created:', payload.collection, payload.id)
    })
  },
})

definePlugin({
  // ...
  async install(ctx) {
    console.info('My plugin installed!')
  },
})

definePlugin({
  // ...
  async activate(ctx) {
    console.info('My plugin activated!')
  },
})

definePlugin({
  // ...
  async deactivate(ctx) {
    // clean up resources
  },
})

definePlugin({
  // ...
  async uninstall(ctx) {
    console.info('My plugin uninstalled!')
  },
})

definePlugin({
  id: 'my-plugin',
  version: '1.0.0',
  capabilities: ['hooks.content:subscribe'],

  async onBoot(ctx) {
    // typed — payload is ContentEventPayload
    ctx.hooks.on('content:after:create', (payload) => {
      console.info('Created in', payload.collection, 'id:', payload.id)
    })

    // before-hook: mutate payload to transform the write
    ctx.hooks.on('content:before:update', (payload) => {
      payload.data.updatedAt = Date.now()
      return payload   // return updated payload to pass it down the chain
    })
  },
})

definePlugin({
  id: 'my-plugin',
  version: '1.0.0',
  capabilities: ['hooks.auth:subscribe'],

  hooks: {
    'auth:registration:completed': (payload) => {
      console.info('New user:', payload.user.email)
    },
  },
})

definePlugin({
  // ...
  async onBoot(ctx) {
    // subscribe to your own custom event
    ctx.raw.hooks.register('my-plugin:processed', async (data) => {
      console.info('Processed:', data)
      return data
    })
  },
})

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

export const myPlugin = definePlugin({
  id: 'my-plugin',
  version: '1.0.0',
  // declare every capability the plugin uses
  capabilities: ['email:send', 'hooks.content:subscribe'],

  async onBoot(ctx) {
    // ctx.cap.email is typed as EmailService (because 'email:send' is declared)
    await ctx.cap.email.send({
      to: 'user@example.com',
      subject: 'Hello',
      html: '<p>World</p>',
    })

    // ctx.cap.http is typed as fetch (would throw if 'http:fetch' not declared)
    // ctx.cap.cache is available if 'cache:read' or 'cache:write' is declared
  },
})

export const myPlugin = definePlugin({
  id: 'my-plugin',
  version: '1.0.0',
  capabilities: ['cron:register', 'email:send'],

  // declare one or more cron schedules
  crons: [
    { schedule: '0 9 * * 1', hookFamily: 'weekly-digest' },
    { schedule: '*/15 * * * *', hookFamily: 'sync-check' },
  ],

  async onCronTick(event, ctx) {
    if (event.hookFamily === 'weekly-digest') {
      // send weekly email report
      await ctx.cap.email.send({ to: 'team@example.com', subject: 'Weekly Digest', html: '...' })
    }
    if (event.hookFamily === 'sync-check') {
      // run periodic sync
    }
  },
})

[triggers]
crons = ["0 9 * * 1", "*/15 * * * *"]

import { definePlugin } from '@sonicjs-cms/core'
import type { ConfigSchema } from '@sonicjs-cms/core'

const schema: ConfigSchema = [
  { key: 'apiKey', type: 'string', label: 'API Key', required: true, secret: true },
  { key: 'webhookUrl', type: 'string', label: 'Webhook URL' },
  { key: 'maxRetries', type: 'number', label: 'Max Retries', default: 3 },
  { key: 'enabled', type: 'boolean', label: 'Enable notifications', default: true },
]

export const myPlugin = definePlugin({
  id: 'my-plugin',
  version: '1.0.0',
  configSchema: schema,

  async onBoot(ctx) {
    // settings are loaded from ctx.env or the plugins table
    const apiKey = (ctx.env?.MY_PLUGIN_API_KEY as string) ?? ''
  },
})

import { definePlugin } from '@sonicjs-cms/core'
import { z } from 'zod'

const itemSchema = z.object({
  title: z.string(),
  active: z.boolean().default(true),
})

export const myPlugin = definePlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',

  async onBoot(ctx) {
    // register document type — no new DB table needed
    await ctx.env.DB.prepare(`
      INSERT OR IGNORE INTO document_types (id, name, source, settings, tenant_id)
      VALUES (?, ?, 'system', '{}', 'default')
    `).bind('my-plugin-item', 'My Plugin Item').run()
  },

  register(app) {
    app.get('/api/my-plugin/items', async (c) => {
      // read via DocumentRepository (raw SQL, tenant-scoped)
      const result = await c.env.DB.prepare(`
        SELECT id, data FROM documents
        WHERE type_id = ? AND tenant_id = 'default' AND is_current_draft = 1
      `).bind('my-plugin-item').all()
      return c.json({ success: true, data: result.results })
    })
  },
})

definePlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',

  menu: [
    {
      label: 'My Plugin',
      path: '/admin/my-plugin',
      icon: 'puzzle-piece',
      order: 50,
    },
    {
      label: 'Settings',
      path: '/admin/my-plugin/settings',
      icon: 'cog',
      order: 51,
    },
  ],

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

    app.get('/admin/my-plugin/settings', async (c) => {
      return c.html('<h1>Settings</h1>')
    })
  },
})

interface DefinedPluginContext {
  /** Typed hook facade — ctx.hooks.on('content:after:create', handler) */
  hooks: TypedHooks

  /**
   * Capability-gated services.
   * ctx.cap.email   → EmailService    (requires 'email:send' declared)
   * ctx.cap.cache   → cache service   (requires 'cache:read' or 'cache:write')
   * ctx.cap.http    → fetch           (requires 'http:fetch')
   * Accessing an undeclared capability throws SonicCapabilityError.
   */
  cap: CapabilityContext

  /** Cloudflare runtime bindings (DB, CACHE_KV, R2, etc.) */
  env?: Record<string, unknown>

  /** The raw boot/cron context (escape hatch for low-level access) */
  raw: PluginBootContext | CronContext
}

definePlugin({
  // ...
  async onBoot(ctx) {
    const db = ctx.env?.DB as D1Database
    const result = await db.prepare(
      "SELECT * FROM documents WHERE type_id = ? AND tenant_id = 'default'"
    ).bind('my-plugin-item').all()
  },
})

definePlugin({
  // ...
  async onBoot(ctx) {
    const kv = ctx.env?.CACHE_KV as KVNamespace
    await kv.put('my-plugin:config', JSON.stringify({ enabled: true }))
    const stored = await kv.get('my-plugin:config', 'json')
  },
})

import { z } from 'zod'

const configSchema = z.object({
  enabled: z.boolean().default(true),
  cacheEnabled: z.boolean().default(true),
  cacheTTL: z.number().default(3600),
})

import { z } from 'zod'

const inputSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100)
})

// inside register(app):
app.post('/api/my-plugin/users', async (c) => {
  const body = await c.req.json()
  const validated = inputSchema.parse(body)
  return c.json({ success: true, data: validated })
})

app.get('/api/my-plugin/data', async (c) => {
  try {
    const data = await fetchData()
    return c.json({ success: true, data })
  } catch (error) {
    console.error('Failed to fetch data:', error)
    return c.json({ success: false, error: 'Failed to fetch data' }, 500)
  }
})

definePlugin({
  // ...
  async deactivate(ctx) {
    if (refreshInterval) clearInterval(refreshInterval)
    cache.clear()
  },
})

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

describe('My Plugin', () => {
  it('should have correct metadata', () => {
    expect(myPlugin.id).toBe('my-plugin')
    expect(myPlugin.version).toBe('1.0.0')
  })

  it('should declare menu items', () => {
    expect(myPlugin.menu).toBeDefined()
    expect(myPlugin.menu.length).toBeGreaterThan(0)
  })
})

npm run test

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

// definePlugin infers types automatically
export const myPlugin = definePlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',
  // ...
})