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
npm create sonicjs-app 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 { Hono } from 'hono'
import { createSonicJS } from '@sonicjs-cms/core'
import { authPlugin } from '@sonicjs-cms/core/plugins'
import { postsCollection } from './collections/posts'
import { usersCollection } from './collections/users'

const app = new Hono<{ Bindings: Env }>()

// Initialize SonicJS
const cms = createSonicJS({
  collections: [postsCollection, usersCollection],
  plugins: [authPlugin()],
})

// Mount the CMS
app.route('/', cms.app)

export default app

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 { defineCollection } from '@sonicjs-cms/core'

export const postsCollection = defineCollection({
  name: 'posts',
  slug: 'posts',
  fields: {
    title: {
      type: 'string',
      required: true,
      maxLength: 200,
    },
    slug: {
      type: 'string',
      required: true,
      unique: true,
    },
    content: {
      type: 'richtext',
      required: true,
    },
    excerpt: {
      type: 'text',
      maxLength: 500,
    },
    featuredImage: {
      type: 'media',
    },
    author: {
      type: 'relation',
      collection: 'users',
    },
    status: {
      type: 'select',
      options: ['draft', 'published', 'archived'],
      default: 'draft',
    },
    publishedAt: {
      type: 'datetime',
    },
  },
})

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"

[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"

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

Run Migrations

Generate and run database migrations:

# Generate migrations from your collections
npm run db:generate

# Apply migrations locally
npm run db:migrate:local

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

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@example.com
• Password: admin123

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/content/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/content/posts

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

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

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

Update Content

curl -X PUT http://localhost:8787/api/content/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/content/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/content/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!