Add database management API endpoints to admin settings routes: - GET /api/database-tools/stats - Database statistics - GET /api/database-tools/validate - Database integrity check - POST /api/database-tools/backup - Database backup - POST /api/database-tools/truncate - Truncate tables Updates: - Add database tools API routes to settings controller - Update plugin registry timestamp - Rebuild dist with latest route changes - Add AI documentation files for core package APIs Built and compiled all changes.
18 KiB
@sonicjs-cms/core API Reference
Version: 2.0.2 Status: Stable Release Last Updated: October 24, 2025
Table of Contents
Installation
# Install via npm
npm install @sonicjs-cms/core
# Install via pnpm
pnpm add @sonicjs-cms/core
# Install via yarn
yarn add @sonicjs-cms/core
Peer Dependencies
The core package requires these peer dependencies:
{
"@cloudflare/workers-types": "^4.0.0",
"hono": "^4.0.0",
"drizzle-orm": "^0.44.0",
"zod": "^3.0.0"
}
Core Application
createSonicJSApp
Creates a new SonicJS application instance.
import { createSonicJSApp } from '@sonicjs-cms/core'
const app = createSonicJSApp({
collections: './src/collections',
plugins: './src/plugins',
routes: './src/routes',
templates: './src/templates'
})
Parameters:
config:SonicJSConfig- Application configuration object
Returns: SonicJSApp - Configured Hono application
setupCoreMiddleware
Configures all core middleware for the application.
import { setupCoreMiddleware } from '@sonicjs-cms/core'
setupCoreMiddleware(app, env)
setupCoreRoutes
Mounts all core routes to the application.
import { setupCoreRoutes } from '@sonicjs-cms/core'
setupCoreRoutes(app)
Services
Collection Management
loadCollectionConfigs
Loads all collection configuration files from the specified directory.
import { loadCollectionConfigs } from '@sonicjs-cms/core'
const configs = await loadCollectionConfigs('./src/collections')
syncCollections
Synchronizes collection configurations with the database.
import { syncCollections } from '@sonicjs-cms/core'
const result = await syncCollections(db)
Parameters:
db:D1Database- Cloudflare D1 database instance
Returns: Promise<CollectionSyncResult>
fullCollectionSync
Performs a complete synchronization including cleanup of removed collections.
import { fullCollectionSync } from '@sonicjs-cms/core'
const result = await fullCollectionSync(db)
Migration Service
MigrationService
Class for managing database migrations.
import { MigrationService } from '@sonicjs-cms/core'
const migrationService = new MigrationService(db)
await migrationService.runPendingMigrations()
Methods:
getMigrationStatus()- Get current migration statusrunPendingMigrations()- Apply all pending migrationsrollbackMigration(migrationId)- Rollback a specific migration
Logging
Logger
Core logging service for the application.
import { getLogger } from '@sonicjs-cms/core'
const logger = getLogger(db)
await logger.info('system', 'Application started')
await logger.error('auth', 'Login failed', error)
await logger.debug('cache', 'Cache hit', { key, value })
Log Levels: debug, info, warn, error
Log Categories: system, auth, content, media, plugin, cache, api
Plugin Services
PluginService
Manages plugin lifecycle and operations.
import { PluginServiceClass } from '@sonicjs-cms/core'
const pluginService = new PluginServiceClass(db)
await pluginService.registerPlugin(plugin)
await pluginService.activatePlugin('plugin-name')
PluginBootstrapService
Handles initial plugin setup and bootstrapping.
import { PluginBootstrapService } from '@sonicjs-cms/core'
const bootstrap = new PluginBootstrapService(db)
await bootstrap.bootstrapCorePlugins()
Middleware
Authentication
requireAuth
Middleware that requires valid JWT authentication.
import { requireAuth } from '@sonicjs-cms/core'
app.use('/admin/*', requireAuth())
requireRole
Middleware that requires specific user roles.
import { requireRole } from '@sonicjs-cms/core'
app.use('/admin/*', requireRole(['admin', 'editor']))
optionalAuth
Middleware that adds user context if authenticated, but doesn't require it.
import { optionalAuth } from '@sonicjs-cms/core'
app.use('/api/*', optionalAuth())
AuthManager
Static class for authentication operations.
import { AuthManager } from '@sonicjs-cms/core'
// Hash password
const hash = await AuthManager.hashPassword('password123')
// Verify password
const valid = await AuthManager.verifyPassword('password123', hash)
// Generate JWT
const token = await AuthManager.generateToken({ userId, email, role })
// Verify JWT
const payload = await AuthManager.verifyToken(token)
Logging Middleware
loggingMiddleware
Basic request logging middleware.
import { loggingMiddleware } from '@sonicjs-cms/core'
app.use('*', loggingMiddleware())
detailedLoggingMiddleware
Detailed request/response logging with timing.
import { detailedLoggingMiddleware } from '@sonicjs-cms/core'
app.use('*', detailedLoggingMiddleware())
securityLoggingMiddleware
Logs security-related events and suspicious activity.
import { securityLoggingMiddleware } from '@sonicjs-cms/core'
app.use('*', securityLoggingMiddleware())
performanceLoggingMiddleware
Logs slow requests that exceed a threshold.
import { performanceLoggingMiddleware } from '@sonicjs-cms/core'
// Log requests slower than 1000ms
app.use('*', performanceLoggingMiddleware(1000))
Performance Middleware
cacheHeaders
Adds cache control headers to responses.
import { cacheHeaders } from '@sonicjs-cms/core'
// Cache for 60 seconds
app.use('/api/*', cacheHeaders(60))
compressionMiddleware
Compresses responses using gzip/brotli.
import { compressionMiddleware } from '@sonicjs-cms/core'
app.use('*', compressionMiddleware)
securityHeaders
Adds security headers to all responses.
import { securityHeaders } from '@sonicjs-cms/core'
app.use('*', securityHeaders())
Permissions
requirePermission
Requires a specific permission for the route.
import { requirePermission } from '@sonicjs-cms/core'
app.get('/admin/users', requirePermission('users.read'), handler)
requireAnyPermission
Requires any one of the specified permissions.
import { requireAnyPermission } from '@sonicjs-cms/core'
app.get('/content', requireAnyPermission(['content.read', 'content.write']), handler)
PermissionManager
Static class for permission management.
import { PermissionManager } from '@sonicjs-cms/core'
// Check permission
const hasPermission = await PermissionManager.hasPermission(db, userId, 'users.write')
// Grant permission
await PermissionManager.grantPermission(db, userId, 'content.delete')
// Revoke permission
await PermissionManager.revokePermission(db, userId, 'content.delete')
Plugin Middleware
requireActivePlugin
Requires a plugin to be active for the route.
import { requireActivePlugin } from '@sonicjs-cms/core'
app.use('/admin/workflow/*', requireActivePlugin('workflow'))
getActivePlugins
Gets list of currently active plugins.
import { getActivePlugins } from '@sonicjs-cms/core'
const plugins = await getActivePlugins(db)
Bootstrap
bootstrapMiddleware
Initializes the application on first request.
import { bootstrapMiddleware } from '@sonicjs-cms/core'
app.use('*', bootstrapMiddleware())
Routes
All routes are pre-configured and ready to mount.
API Routes
import {
apiRoutes,
apiContentCrudRoutes,
apiMediaRoutes,
apiSystemRoutes
} from '@sonicjs-cms/core'
app.route('/api', apiRoutes)
app.route('/api', apiContentCrudRoutes)
app.route('/api/media', apiMediaRoutes)
app.route('/api', apiSystemRoutes)
Admin Routes
import {
adminDashboardRoutes,
adminContentRoutes,
adminUsersRoutes,
adminMediaRoutes,
adminPluginRoutes,
adminLogsRoutes,
adminCollectionsRoutes,
adminSettingsRoutes
} from '@sonicjs-cms/core'
app.route('/admin', adminDashboardRoutes)
app.route('/admin/content', adminContentRoutes)
app.route('/admin', adminUsersRoutes)
app.route('/admin/media', adminMediaRoutes)
app.route('/admin/plugins', adminPluginRoutes)
app.route('/admin/logs', adminLogsRoutes)
app.route('/admin', adminCollectionsRoutes)
app.route('/admin', adminSettingsRoutes)
Auth Routes
import { authRoutes } from '@sonicjs-cms/core'
app.route('/auth', authRoutes)
Templates
Form Templates
renderForm
Renders a complete form with validation.
import { renderForm } from '@sonicjs-cms/core'
const html = renderForm({
action: '/admin/users/new',
method: 'POST',
fields: [
{ name: 'email', label: 'Email', type: 'email', required: true },
{ name: 'password', label: 'Password', type: 'password', required: true }
],
submitLabel: 'Create User'
})
renderFormField
Renders a single form field.
import { renderFormField } from '@sonicjs-cms/core'
const html = renderFormField({
name: 'title',
label: 'Title',
type: 'text',
value: 'My Title',
required: true,
placeholder: 'Enter title...'
})
Table Templates
renderTable
Renders a data table with sorting and pagination.
import { renderTable } from '@sonicjs-cms/core'
const html = renderTable({
columns: [
{ key: 'name', label: 'Name', sortable: true },
{ key: 'email', label: 'Email', sortable: true },
{ key: 'role', label: 'Role' }
],
rows: users,
sortBy: 'name',
sortOrder: 'asc'
})
Pagination Templates
renderPagination
Renders pagination controls.
import { renderPagination } from '@sonicjs-cms/core'
const html = renderPagination({
currentPage: 1,
totalPages: 10,
totalItems: 100,
itemsPerPage: 10,
baseUrl: '/admin/users'
})
Alert Templates
renderAlert
Renders an alert message.
import { renderAlert } from '@sonicjs-cms/core'
const html = renderAlert({
type: 'success',
message: 'User created successfully!',
dismissible: true
})
Alert Types: success, error, warning, info
Dialog Templates
renderConfirmationDialog
Renders a confirmation dialog.
import { renderConfirmationDialog } from '@sonicjs-cms/core'
const html = renderConfirmationDialog({
title: 'Delete User?',
message: 'Are you sure you want to delete this user?',
confirmText: 'Delete',
cancelText: 'Cancel',
onConfirm: '/admin/users/123/delete'
})
Utilities
Sanitization
sanitizeInput
Sanitizes user input to prevent XSS attacks.
import { sanitizeInput } from '@sonicjs-cms/core'
const clean = sanitizeInput(userInput)
sanitizeObject
Recursively sanitizes all string values in an object.
import { sanitizeObject } from '@sonicjs-cms/core'
const cleanData = sanitizeObject(userData)
escapeHtml
Escapes HTML special characters.
import { escapeHtml } from '@sonicjs-cms/core'
const safe = escapeHtml('<script>alert("xss")</script>')
// Result: <script>alert("xss")</script>
Template Rendering
TemplateRenderer
Class for rendering Handlebars-like templates.
import { TemplateRenderer } from '@sonicjs-cms/core'
const renderer = new TemplateRenderer()
const html = renderer.render(template, data)
renderTemplate
Quick template rendering function.
import { renderTemplate } from '@sonicjs-cms/core'
const html = renderTemplate('Hello {{name}}!', { name: 'World' })
Query Filtering
QueryFilterBuilder
Builds complex database queries.
import { QueryFilterBuilder } from '@sonicjs-cms/core'
const builder = new QueryFilterBuilder()
const query = builder
.where('status', '=', 'published')
.where('author', '=', userId)
.orderBy('created_at', 'desc')
.limit(10)
.build()
buildQuery
Quick query building function.
import { buildQuery } from '@sonicjs-cms/core'
const { sql, params } = buildQuery({
table: 'content',
where: [
{ field: 'status', operator: '=', value: 'published' }
],
orderBy: 'created_at',
order: 'desc',
limit: 10
})
Metrics
metricsTracker
Tracks application metrics.
import { metricsTracker } from '@sonicjs-cms/core'
metricsTracker.recordRequest()
metricsTracker.recordError()
const metrics = metricsTracker.getMetrics()
Version
getCoreVersion
Gets the current core package version.
import { getCoreVersion, SONICJS_VERSION } from '@sonicjs-cms/core'
console.log(getCoreVersion()) // "2.0.2"
console.log(SONICJS_VERSION) // "2.0.2"
Database
Schema Creation
createDb
Creates a typed Drizzle database instance.
import { createDb } from '@sonicjs-cms/core'
const db = createDb(env.DB)
Schema Tables
All core database tables are exported:
import {
users,
collections,
content,
contentVersions,
media,
apiTokens,
workflowHistory,
plugins,
pluginHooks,
pluginRoutes,
systemLogs
} from '@sonicjs-cms/core'
// Query with Drizzle ORM
const allUsers = await db.select().from(users).all()
const activeContent = await db
.select()
.from(content)
.where(eq(content.status, 'published'))
.all()
Zod Validation Schemas
Validation schemas for all tables:
import {
insertUserSchema,
selectUserSchema,
insertContentSchema,
selectContentSchema
} from '@sonicjs-cms/core'
// Validate user data
const validatedUser = insertUserSchema.parse(userData)
Types
Collection Types
import type {
CollectionConfig,
CollectionSchema,
FieldType,
FieldConfig
} from '@sonicjs-cms/core'
Plugin Types
import type {
Plugin,
PluginContext,
PluginConfig,
PluginHook,
HookHandler,
PluginManifest
} from '@sonicjs-cms/core'
Database Types
import type {
User,
NewUser,
Content,
NewContent,
Media,
NewMedia
} from '@sonicjs-cms/core'
Plugins
Hook System
HookSystemImpl
Core hook system implementation.
import { HookSystemImpl } from '@sonicjs-cms/core'
const hookSystem = new HookSystemImpl()
hookSystem.register('content:beforeSave', async (data) => {
// Modify data before save
return data
})
const result = await hookSystem.execute('content:beforeSave', content)
Plugin Registry
PluginRegistryImpl
Registry for managing plugins.
import { PluginRegistryImpl } from '@sonicjs-cms/core'
const registry = new PluginRegistryImpl()
await registry.register(plugin)
const allPlugins = registry.getAll()
Plugin Manager
PluginManagerClass
Manages plugin lifecycle.
import { PluginManagerClass } from '@sonicjs-cms/core'
const manager = new PluginManagerClass(db, registry, hookSystem)
await manager.activatePlugin('plugin-name')
await manager.deactivatePlugin('plugin-name')
Usage Examples
Complete Application Setup
import { Hono } from 'hono'
import {
setupCoreMiddleware,
setupCoreRoutes,
apiRoutes,
adminDashboardRoutes,
authRoutes,
requireAuth
} from '@sonicjs-cms/core'
const app = new Hono()
// Setup middleware
setupCoreMiddleware(app, env)
// Mount auth routes (public)
app.route('/auth', authRoutes)
// Mount API routes (optional auth)
app.use('/api/*', optionalAuth())
app.route('/api', apiRoutes)
// Mount admin routes (requires auth)
app.use('/admin/*', requireAuth())
app.use('/admin/*', requireRole(['admin', 'editor']))
app.route('/admin', adminDashboardRoutes)
export default app
Custom Collection
import type { CollectionConfig } from '@sonicjs-cms/core'
export const productsCollection: CollectionConfig = {
name: 'products',
displayName: 'Products',
description: 'E-commerce products',
schema: {
type: 'object',
properties: {
name: { type: 'string', required: true },
price: { type: 'number', required: true },
description: { type: 'richtext' },
image: { type: 'media' },
inStock: { type: 'boolean', default: true }
}
},
managed: true,
isActive: true
}
Custom Plugin
import type { Plugin, PluginContext } from '@sonicjs-cms/core'
const myPlugin: Plugin = {
name: 'my-custom-plugin',
version: '1.0.0',
description: 'My custom plugin',
async install(context: PluginContext) {
// Installation logic
},
async activate(context: PluginContext) {
// Register hooks
context.hookSystem.register('content:beforeSave', async (data) => {
// Custom logic
return data
})
},
async deactivate(context: PluginContext) {
// Cleanup logic
}
}
export default myPlugin
Version History
2.0.2 (Current)
- User management routes added
- Permission system integration
- Admin route consolidation
- Bug fixes and stability improvements
2.0.1
- Initial stable release
- Core routes extracted
- Template system complete
- Plugin system functional
2.0.0
- Initial alpha release
- Core package extraction
- Basic functionality
Support & Resources
- Documentation: https://docs.sonicjs.com
- GitHub: https://github.com/sonicjs/sonicjs
- Issues: https://github.com/sonicjs/sonicjs/issues
- NPM: https://www.npmjs.com/package/@sonicjs-cms/core
Last Updated: October 24, 2025 Package Version: 2.0.2 License: MIT