Quick Start

For Application Developers (Using SonicJS)

1# Create a new SonicJS application
2npx create-sonicjs@latest my-app
3 
4cd my-app
5npm run dev
6 
7# Visit http://localhost:8787

Your app includes:

• ✅ 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)

1# Clone this repository
2git clone https://github.com/lane711/sonicjs.git
3cd sonicjs
4 
5# Install dependencies
6npm install
7 
8# Build the core package
9npm run build:core
10 
11# Create a test app to validate changes
12npx create-sonicjs@latest my-sonicjs-app
13 
14# Run tests
15npm test

Setting Up a Fresh Database

1# Create a fresh D1 database for your branch (run from project root)
2npm run db:reset

This creates a new D1 database named sonicjs-worktree-<branch-name>, applies all migrations, and updates wrangler.toml.

Working with Database Migrations

Migrations live in packages/core/migrations/. Test apps reference them via npm workspace symlink.

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

1# Check migration status
2wrangler d1 migrations list DB --local
3 
4# Apply pending migrations
5wrangler d1 migrations apply DB --local
6 
7# Apply to production
8wrangler d1 migrations apply DB --remote

Creating New Migrations:

SonicJS bundles migrations at build time (Workers can't access the filesystem at runtime).

1. Create packages/core/migrations/NNN_description.sql (use CREATE TABLE IF NOT EXISTS and INSERT OR IGNORE for idempotency)
2. Regenerate bundle: cd packages/core && npm run generate:migrations
3. Rebuild: npm run build:core
4. Apply locally: cd my-sonicjs-app && wrangler d1 migrations apply DB --local

Common Commands

1npm run dev          # Start dev server
2npm run deploy       # Deploy to Cloudflare
3npm run db:migrate   # Apply migrations
4npm run db:studio    # Open database studio
5npm test             # Run tests