Configuration Reference

interface SonicJSConfig {
  // Collections configuration
  collections?: {
    directory?: string     // Path to collection definitions
    autoSync?: boolean     // Auto-sync collections on startup
  }

  // Plugins configuration
  plugins?: {
    directory?: string     // Path to custom plugins
    autoLoad?: boolean     // Auto-load plugins from directory
    disableAll?: boolean   // Disable all plugins (including core)
  }

  // Custom routes
  routes?: Array<{
    path: string           // Route path prefix
    handler: Hono          // Hono router instance
  }>

  // Custom middleware
  middleware?: {
    beforeAuth?: Middleware[]   // Run before authentication
    afterAuth?: Middleware[]    // Run after authentication
  }

  // App metadata
  version?: string         // Application version
  name?: string            // Application name
}

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

const app = createSonicJSApp({
  name: 'My CMS',
  version: '1.0.0',
  collections: {
    directory: './src/collections',
    autoSync: true
  },
  plugins: {
    directory: './src/plugins',
    autoLoad: true
  }
})

export default app

import { createSonicJSApp } from '@sonicjs-cms/core'
import { Hono } from 'hono'

// Custom API routes
const customApi = new Hono()
customApi.get('/hello', (c) => c.json({ message: 'Hello!' }))
customApi.post('/webhook', async (c) => {
  const body = await c.req.json()
  // Handle webhook
  return c.json({ success: true })
})

const app = createSonicJSApp({
  routes: [
    { path: '/api/custom', handler: customApi }
  ]
})

export default app

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

const app = createSonicJSApp({
  middleware: {
    beforeAuth: [
      // Rate limiting middleware
      async (c, next) => {
        // Check rate limits
        await next()
      },
      // Request logging
      async (c, next) => {
        console.log(`${c.req.method} ${c.req.url}`)
        await next()
      }
    ],
    afterAuth: [
      // Audit logging (after user is known)
      async (c, next) => {
        const user = c.get('user')
        console.log(`User ${user?.email} accessing ${c.req.url}`)
        await next()
      }
    ]
  }
})

export default app

interface Bindings {
  // Required bindings
  DB: D1Database              // Cloudflare D1 database
  CACHE_KV: KVNamespace       // Cloudflare KV for caching
  MEDIA_BUCKET: R2Bucket      // Cloudflare R2 for media storage
  ASSETS: Fetcher             // Static assets fetcher

  // Optional bindings
  EMAIL_QUEUE?: Queue         // Queue for email processing
  SENDGRID_API_KEY?: string   // SendGrid API key
  DEFAULT_FROM_EMAIL?: string // Default email sender
  IMAGES_ACCOUNT_ID?: string  // Cloudflare Images account
  IMAGES_API_TOKEN?: string   // Cloudflare Images token
  ENVIRONMENT?: string        // Environment name (dev, staging, prod)
  BUCKET_NAME?: string        // R2 bucket name

  // AI Search bindings (optional)
  AI?: any                    // Workers AI binding
  VECTORIZE_INDEX?: any       // Vectorize index binding
}

const app = createSonicJSApp({
  collections: {
    // Directory containing collection definition files
    directory: './src/collections',

    // Automatically sync collection schemas on startup
    autoSync: true
  }
})

// src/collections/blog-posts.ts
import { defineCollection } from '@sonicjs-cms/core'

export default defineCollection({
  name: 'blog_posts',
  displayName: 'Blog Posts',
  description: 'Blog articles and posts',

  // Schema definition
  schema: {
    title: {
      type: 'string',
      required: true,
      maxLength: 200
    },
    slug: {
      type: 'slug',
      from: 'title'
    },
    content: {
      type: 'richtext',
      required: true
    },
    publishedAt: {
      type: 'datetime'
    },
    featured: {
      type: 'boolean',
      default: false
    },
    category: {
      type: 'reference',
      collection: 'categories'
    },
    tags: {
      type: 'array',
      items: { type: 'string' }
    }
  },

  // Workflow settings
  workflow: {
    enabled: true,
    requireApproval: true
  },

  // API settings
  api: {
    enabled: true,
    publicRead: true,
    publicCreate: false
  }
})

const app = createSonicJSApp({
  plugins: {
    // Directory for custom plugins
    directory: './src/plugins',

    // Auto-load plugins from directory
    autoLoad: true,

    // Disable all plugins (useful for testing)
    disableAll: false
  }
})

-- Plugin settings are stored in the plugins table
SELECT id, settings FROM plugins WHERE id = 'ai-search';

-- Settings are JSON:
-- {
--   "enabled": true,
--   "ai_mode_enabled": true,
--   "selected_collections": ["1", "2"],
--   "autocomplete_enabled": true,
--   "cache_duration": 1,
--   "results_limit": 20
-- }

Request
   │
   ├─▶ Metrics Middleware
   │
   ├─▶ Bootstrap Middleware (migrations, init)
   │
   ├─▶ beforeAuth Middleware (your custom)
   │
   ├─▶ Auth Middleware
   │
   ├─▶ afterAuth Middleware (your custom)
   │
   ├─▶ Route Handler
   │
   └─▶ Response

type Middleware = (
  c: Context,
  next: () => Promise<void>
) => Promise<void>

// Example middleware
const loggingMiddleware: Middleware = async (c, next) => {
  const start = Date.now()
  await next()
  const duration = Date.now() - start
  console.log(`${c.req.method} ${c.req.url} - ${duration}ms`)
}

const authCheckMiddleware: Middleware = async (c, next) => {
  const user = c.get('user')
  if (!user) {
    return c.json({ error: 'Unauthorized' }, 401)
  }
  await next()
}

name = "my-sonicjs-app"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# Environment variables
[vars]
ENVIRONMENT = "production"
DEFAULT_FROM_EMAIL = "noreply@myapp.com"
DEFAULT_FROM_NAME = "My App"
CACHE_ENABLED = "true"
CACHE_TTL = "3600"

# D1 Database
[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# KV Namespace for caching
[[kv_namespaces]]
binding = "CACHE_KV"
id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# R2 Bucket for media
[[r2_buckets]]
binding = "MEDIA_BUCKET"
bucket_name = "my-app-media"

# Workers AI (for AI Search)
[ai]
binding = "AI"

# Vectorize (for AI Search)
[[vectorize]]
binding = "VECTORIZE_INDEX"
index_name = "sonicjs-content"

# Queue for email processing (optional)
[[queues.producers]]
queue = "email-queue"
binding = "EMAIL_QUEUE"

# Static assets
[assets]
binding = "ASSETS"
directory = "./public"

# Development environment
[env.development]
[env.development.vars]
ENVIRONMENT = "development"

# Staging environment
[env.staging]
[env.staging.vars]
ENVIRONMENT = "staging"

# Production secrets (set via wrangler secret)
# wrangler secret put JWT_SECRET
# wrangler secret put SENDGRID_API_KEY
# wrangler secret put ADMIN_PASSWORD

# Set JWT secret
npx wrangler secret put JWT_SECRET
# Enter your secret when prompted

# Set SendGrid API key
npx wrangler secret put SENDGRID_API_KEY

# Set initial admin password
npx wrangler secret put ADMIN_PASSWORD

# For specific environment
npx wrangler secret put JWT_SECRET --env production

interface Variables {
  // User information (set by auth middleware)
  user?: {
    userId: string
    email: string
    role: string
    exp: number    // Token expiration
    iat: number    // Token issued at
  }

  // Request metadata
  requestId?: string   // Unique request ID
  startTime?: number   // Request start timestamp
  appVersion?: string  // Application version
}

// Usage in routes
app.get('/api/me', (c) => {
  const user = c.get('user')
  const requestId = c.get('requestId')

  return c.json({
    user,
    requestId,
    version: c.get('appVersion')
  })
})