SonicJS

The edge-native headless CMS for Cloudflare Workers. Sub-100ms response times globally. Zero cold starts. TypeScript-first.

sonicjs.com

📦 Get Started

npx create-sonicjs@latest my-app

⚠️ Note: This repository is for developing the SonicJS core package. To build an application with SonicJS, use the command above to create a new project.

🚀 Features

Core Platform

⚡ Edge-First: Built specifically for Cloudflare Workers with global performance
🔧 Developer-Centric: Configuration over UI, TypeScript-first approach
🤖 AI-Friendly: Structured codebase designed for AI-assisted development
🔌 Plugin System: Extensible architecture without core modifications
📱 Modern Stack: Hono.js, TypeScript, D1, R2, and HTMX
🚀 Fast & Lightweight: Optimized for edge computing performance

Advanced Content Management (Stage 5)

📝 Rich Text Editor: TinyMCE integration with customizable toolbars
🎛️ Dynamic Fields: Custom field types (text, number, date, boolean, select, media)
📚 Content Versioning: Complete revision history with restore functionality
⏰ Content Scheduling: Publish/unpublish automation with date controls
🔄 Workflow System: Draft → Review → Published → Archived with role-based permissions
💾 Auto-Save: Automatic content saving every 30 seconds
👁️ Live Preview: Real-time content preview before publishing
📋 Content Duplication: One-click content copying and templates
🛡️ XSS Protection: Comprehensive input validation and HTML escaping

📊 How SonicJS Compares

| | SonicJS | Strapi | Payload | |--|---------|--------|---------| | Edge-native | Yes | No | No | | Cloudflare Workers | Yes | No | Limited | | Cold starts | None | 2-5s | 1-3s | | Response time | <100ms | 200-500ms | 150-400ms | | Database | D1 (SQLite at edge) | PostgreSQL/MySQL | MongoDB/PostgreSQL | | Global distribution | Built-in | Requires setup | Requires setup |

SonicJS is the only production-ready CMS built specifically for edge computing. We have 46x more development activity per GitHub star than Strapi.

🌟 Why SonicJS?

Edge Performance

Global distribution via Cloudflare's network
Sub-100ms response times worldwide
Automatic scaling and DDoS protection
No cold starts - instant responses

Developer Experience

TypeScript-first with full type safety
Hot reload development environment
create-sonicjs CLI for instant setup
Comprehensive documentation

AI-Friendly Architecture

Clean, structured codebase
TypeScript types for autocomplete
Clear conventions and patterns
Built for AI-assisted development
12 specialized Claude Code agents for development (View all agents)

🛠 Technology Stack

Core Framework

Hono.js - Ultrafast web framework for Cloudflare Workers
TypeScript - Strict type safety throughout
HTMX - Enhanced HTML for dynamic interfaces

Cloudflare Services

D1 - SQLite database at the edge
R2 - Object storage for media
Workers - Serverless compute runtime
KV - Key-value storage for caching
Images API - Image optimization and transformation

Development Tools

Vitest - Fast unit testing
Playwright - End-to-end testing
Wrangler - Local development and deployment
Drizzle ORM - Type-safe database queries

🏁 Quick Start

For Application Developers (Using SonicJS)

If you want to build an application with SonicJS:

# Create a new SonicJS application
npx create-sonicjs@latest my-app

# Navigate to your app
cd my-app

# Start development server
npm run dev

# Visit http://localhost:8787

Your app will be created with:

✅ SonicJS CMS pre-configured
✅ Database migrations ready
✅ Example content collections
✅ Admin interface at /admin
✅ Ready to deploy to Cloudflare

For Package Developers (Contributing to SonicJS)

If you want to contribute to the SonicJS core package:

# Clone this repository
git clone https://github.com/lane711/sonicjs-ai.git
cd sonicjs-ai

# Install dependencies
npm install

# Build the core package
npm run build:core

# Create a test app to validate changes
npx create-sonicjs@latest my-sonicjs-app

# Run tests
npm test

Setting Up a Fresh Database

When working in a new worktree or wanting to reset your local database, run from the project root:

# Create a fresh D1 database for your branch
npm run db:reset

This will:

Create a new D1 database named sonicjs-worktree-<branch-name>
Apply all migrations
Update wrangler.toml with the new database ID

Working with Database Migrations

When developing the core package, migrations are located in packages/core/migrations/. Your test app will reference these migrations through the npm workspace symlink.

From your test app directory (e.g., my-sonicjs-app/):

# Check migration status (local D1 database)
wrangler d1 migrations list DB --local

# Apply pending migrations to local database
wrangler d1 migrations apply DB --local

# Apply migrations to production database
wrangler d1 migrations apply DB --remote

Important Notes:

The test app's wrangler.toml points to: migrations_dir = "./node_modules/@sonicjs-cms/core/migrations"
Since the core package is symlinked via npm workspaces, changes to migrations are immediately available
After creating new migrations in packages/core/migrations/, rebuild the core package: npm run build:core
Always apply migrations to your test database before running the dev server or tests

Creating New Migrations:

SonicJS uses a build-time migration bundler because Cloudflare Workers cannot access the filesystem at runtime. All migration SQL must be bundled into the application code.

Create a new migration file in packages/core/migrations/ following the naming pattern: NNN_description.sql (e.g., 027_add_user_preferences.sql)
Write your migration SQL (use CREATE TABLE IF NOT EXISTS and INSERT OR IGNORE for idempotency)
Regenerate the migrations bundle: cd packages/core && npm run generate:migrations
Rebuild the core package: npm run build:core (or just npm run build from packages/core - the bundle generation runs automatically as a prebuild step)
Apply to your test database: cd my-sonicjs-app && wrangler d1 migrations apply DB --local

Important: After modifying any .sql files in migrations/, you must rebuild the package. The SQL files are not used at runtime - only the generated migrations-bundle.ts file is included in the build.

Common Commands (For Apps)

# Start development server
npm run dev

# Deploy to Cloudflare
npm run deploy

# Database operations
npm run db:migrate     # Apply migrations
npm run db:studio      # Open database studio

# Run tests
npm test

📁 Project Structure

This is a package development monorepo for building and maintaining the SonicJS CMS npm package.

sonicjs-ai/
├── packages/
│   ├── core/              # 📦 Main CMS package (published as @sonicjs-cms/core)
│   │   ├── src/
│   │   │   ├── routes/    # All route handlers (admin, API, auth)
│   │   │   ├── templates/ # HTML templates & components
│   │   │   ├── middleware/# Authentication & middleware
│   │   │   ├── utils/     # Utility functions
│   │   │   └── db/        # Database schemas & migrations
│   │   └── package.json   # @sonicjs-cms/core
│   ├── templates/         # Template system package
│   └── scripts/           # Build scripts & generators
│
├── my-sonicjs-app/        # 🧪 Test application (gitignored)
│   └── ...                # Created with: npx create-sonicjs@latest
│                          # Used for testing the published package
│
├── www/                   # 🌐 Marketing website
├── tests/e2e/             # End-to-end test suites
└── drizzle/               # Database migrations

Important Notes

⚠️ This is NOT an application repository - it's for developing the @sonicjs-cms/core npm package.

packages/core/ - The main

Sonicjs

Install / Use

README