Getting Started with SonicJS: Complete Beginner's Guide

Welcome to SonicJS! This guide will walk you through setting up your first edge-first headless CMS using SonicJS and Cloudflare Workers. By the end, you'll have a fully functional content API running globally with blazing-fast response times.

Prerequisites

Before we begin, make sure you have:

• Node.js 20 or later - SonicJS requires modern Node.js features
• A Cloudflare account - Free tier works perfectly for getting started
• Wrangler CLI - Cloudflare's command-line tool for Workers

# Check your Node.js version
node --version  # Should be v20.0.0 or higher

# Install Wrangler globally
npm install -g wrangler

# Login to Cloudflare
wrangler login

Step 1: Create Your SonicJS Project

The fastest way to get started is using the create-sonicjs-app CLI:

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

# Navigate to your project
cd my-cms

This scaffolds a complete SonicJS project with:

• Pre-configured Cloudflare Workers setup
• D1 database bindings
• R2 storage for media files
• KV namespace for caching
• Example content collections

Step 2: Understand the Project Structure

Let's explore what was created:

my-cms/
├── src/
│   ├── index.ts           # Main application entry
│   ├── collections/       # Content type definitions
│   │   ├── posts.ts
│   │   └── users.ts
│   └── plugins/           # Custom plugins
├── drizzle/
│   └── migrations/        # Database migrations
├── wrangler.toml          # Cloudflare configuration
├── package.json
└── tsconfig.json

The Main Entry Point

Open src/index.ts to see how SonicJS is configured:

import { createSonicJSApp, registerCollections } from '@sonicjs-cms/core'
import { postsCollection } from './collections/posts'
import { usersCollection } from './collections/users'

registerCollections([postsCollection, usersCollection])

export default createSonicJSApp({ collections: { autoSync: true } })

Step 3: Define Your Content Collections

Collections are the heart of SonicJS. They define your content structure with full TypeScript support.

Create a new collection in src/collections/posts.ts:

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

export const postsCollection: CollectionConfig = {
  name: 'posts',
  slug: 'posts',
  schema: {
    type: 'object',
    properties: {
      title: {
        type: 'string',
        maxLength: 200,
      },
      slug: {
        type: 'string',
      },
      content: {
        type: 'lexical',
      },
      excerpt: {
        type: 'string',
        maxLength: 500,
      },
      featuredImage: {
        type: 'string',
      },
      author: {
        type: 'reference',
        collection: 'users',
      },
      status: {
        type: 'string',
        enum: ['draft', 'published', 'archived'],
        default: 'draft',
      },
      publishedAt: {
        type: 'string',
        format: 'date-time',
      },
    },
    required: ['title', 'slug', 'content'],
  },
}

Step 4: Set Up Your Database

SonicJS uses Cloudflare D1, a SQLite database that runs at the edge.

Create the D1 Database

# Create a new D1 database
wrangler d1 create my-cms-db

# You'll see output like:
# [[d1_databases]]
# binding = "DB"
# database_name = "my-cms-db"
# database_id = "xxxx-xxxx-xxxx"

Update wrangler.toml

Add the database configuration to your wrangler.toml:

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

[[d1_databases]]
binding = "DB"
database_name = "my-cms-db"
database_id = "your-database-id"

[[r2_buckets]]
binding = "MEDIA_BUCKET"
bucket_name = "my-cms-storage"

Run Migrations

Generate and run database migrations:

# Apply migrations locally
npm run db:migrate:local

# Apply migrations to production
npm run db:migrate

Step 5: Start Development

Launch the local development server:

npm run dev

Your CMS is now running at http://localhost:8787!

Access the Admin Panel

Open http://localhost:8787/admin to access the built-in admin interface. The default credentials are:

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

Make sure to change these credentials before deploying to production!

Step 6: Using the Content API

SonicJS automatically generates RESTful API endpoints for your collections.

Create Content

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

Read Content

# Get all posts
curl http://localhost:8787/api/posts

# Get a single post by ID
curl http://localhost:8787/api/posts/123

# Filter posts
curl "http://localhost:8787/api/posts?status=published"

# Pagination
curl "http://localhost:8787/api/posts?limit=10&offset=0"

Update Content

curl -X PUT http://localhost:8787/api/posts/123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "Updated Title"
  }'

Delete Content

curl -X DELETE http://localhost:8787/api/posts/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 7: Deploy to Production

When you're ready to go live:

# Deploy to Cloudflare Workers
npm run deploy

That's it! Your CMS is now live and running on Cloudflare's global network.

Verify Your Deployment

# Test your production API
curl https://my-cms.your-subdomain.workers.dev/api/posts

Next Steps

Now that you have SonicJS running, explore these topics:

• Authentication - Set up secure user authentication
• Collections - Learn about advanced field types and relationships
• Caching - Optimize performance with three-tiered caching
• Plugins - Extend SonicJS with custom functionality
• Deployment - Production deployment best practices

Key Takeaways

• SonicJS runs on Cloudflare Workers for edge-first performance
• Collections define your content structure with TypeScript
• D1 provides SQLite at the edge for your database
• The REST API is automatically generated from your collections
• Deployment is a single command with npm run deploy

Have questions? Join our Discord community or open an issue on GitHub.

Happy building!