Installation

Get SonicJS running locally or deploy to production. This guide covers everything from prerequisites to your first content creation.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (version 20 or higher)
• npm or pnpm
• Git
• Cloudflare account (for deployment and production use)

Recommended Tools

• TypeScript knowledge (project is fully typed)
• Visual Studio Code (for best TypeScript experience)
• Wrangler CLI (installed automatically with dependencies)

Quick Start

Option 1: Create New Project (Recommended)

Get started in under 60 seconds with the official CLI:

# Create a new SonicJS project
npx create-sonicjs my-cms

# Navigate to project
cd my-cms

# Start development server
npm run dev

Your SonicJS instance will be available at http://localhost:8787

Option 2: Clone Repository (Development)

For contributing or developing SonicJS itself:

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

# Install dependencies
npm install

# Start development server
npm run dev

Development Setup

1. Install Dependencies

npm install

This will install all required dependencies including:

• Hono - Ultra-fast web framework
• Drizzle ORM - Type-safe database queries
• Wrangler - Cloudflare Workers CLI
• Vitest - Unit testing framework
• Playwright - E2E testing framework

2. Database Setup

SonicJS uses Cloudflare D1 (SQLite) for local development and production.

Run migrations locally:

npm run db:migrate

This command applies all database migrations and creates the initial schema including:

• User authentication tables
• Content and collections
• Media library
• Plugin system
• Workflow and automation
• Email templates

Available database commands:

# Generate new migration files (if you modify schema)
npm run db:generate

# Apply migrations to local database
npm run db:migrate

# Apply migrations to production
npm run db:migrate:prod

# Open interactive database studio (Drizzle Studio)
npm run db:studio

Environment Configuration

SonicJS is configured via wrangler.toml instead of .env files.

wrangler.toml (automatically configured):

name = "sonicjs-ai"
main = "src/index.ts"
compatibility_date = "2024-06-01"

[vars]
ENVIRONMENT = "development"

[[d1_databases]]
binding = "DB"
database_name = "sonicjs-dev"
database_id = "your-database-id"

[[r2_buckets]]
binding = "MEDIA_BUCKET"
bucket_name = "sonicjs-media-dev"

[[kv_namespaces]]
binding = "CACHE_KV"
id = "your-kv-id"

Key Bindings:

• DB - D1 Database for all data storage
• MEDIA_BUCKET - R2 bucket for media files
• CACHE_KV - KV namespace for caching layer
• ASSETS - Static asset serving

Start Development Server

npm run dev

What happens on startup:

1. Bootstrap Phase:

   • Runs database migrations
   • Syncs collection configurations
   • Bootstraps core plugins (auth, media, cache, database-tools, seed-data)
   • Installs demo plugins (workflow, FAQ, demo-login)

2. Server Ready:

   • Admin interface: http://localhost:8787/admin
   • API documentation: http://localhost:8787/api
   • Health check: http://localhost:8787/health

First Steps

1. Access the Admin Dashboard

Navigate to http://localhost:8787/admin

Default Credentials (if seed data is loaded):

• Email: admin@sonicjs.com
• Password: admin123

Note: The demo-login-plugin auto-fills these credentials in development.

2. Create Your First Content

Via Admin UI:

1. Navigate to Content → New Content
2. Select a collection (e.g., "Blog Posts")
3. Fill in the fields:
   • Title: "My First Post"
   • Slug: "my-first-post" (auto-generated)
   • Content: Write your content
   • Status: "published"
4. Click Save

Via API:

# Get auth token
curl -X POST http://localhost:8787/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@sonicjs.com","password":"admin123"}'

# Create content
curl -X POST http://localhost:8787/admin/content \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "collection": "blog_posts",
    "title": "My First Post",
    "data": {
      "slug": "my-first-post",
      "content": "<p>Hello World!</p>",
      "status": "published"
    }
  }'

3. Explore the API

API Documentation: Visit http://localhost:8787/api for interactive OpenAPI docs.

Key Endpoints:

# Health check
GET /health

# List collections
GET /api/collections

# Get all content (paginated)
GET /api/content?limit=50

# Get collection content
GET /api/collections/blog_posts/content

# Get single content item
GET /api/content/:id

# Search content
GET /api/content?search=keyword

Available Scripts

Development

Database

Testing

Utilities

Troubleshooting

Common Issues

Database Connection Errors

Error: Error: no such table: users

Solution:

# Run migrations
npm run db:migrate

# Verify migration status
wrangler d1 migrations list DB --local

Port Already in Use

Error: Error: listen EADDRINUSE: address already in use :::8787

Solution:

# Find and kill the process using port 8787
lsof -ti:8787 | xargs kill -9

# Or specify a different port in wrangler.toml
# [dev]
# port = 3000

Module Not Found / Import Errors

Error: Cannot find module 'hono'

Solution:

# Clear and reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Clear TypeScript build cache
rm -rf .wrangler

Media Upload Fails

Error: Failed to upload to R2

Solution:

1. Verify R2 bucket exists and binding is correct in wrangler.toml
2. Check bucket permissions
3. Ensure file size is under limits (10MB default for images)
4. Verify MIME type is allowed

# Test R2 bucket
wrangler r2 bucket list

# Check specific bucket
wrangler r2 bucket info sonicjs-media-dev

Getting Help

Resources:

• 📚 Full Documentation
• 🐛 GitHub Issues
• 💬 Discussions
• 📖 API Reference
• 🏗️ Architecture Guide

Next Steps

Now that you have SonicJS running, explore these guides: