# Install and configure sonicjs

Follow the source instructions for **sonicjs**. Read the prerequisites and configuration steps before running an example.

## Get Started

```bash
npx create-sonicjs@latest my-app
```

$0 to start · No signup required · Runs anywhere SQLite runs

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/lane711/sonicjs-deploy-now)

> **⚠️ 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.

## Quick Start

### For Application Developers (Using SonicJS)

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

cd my-app
npm run dev

# 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)

```bash
# Clone this repository
git clone https://github.com/Up-to-code/sonicjs.git
cd sonicjs

# 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

```bash
# Create a fresh D1 database for your branch (run from project root)
npm 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/`):

```bash
# Check migration status
wrangler d1 migrations list DB --local

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

# Apply to production
wrangler 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

```bash
npm run dev          # Start dev server
npm run deploy       # Deploy to Cloudflare
npm run db:migrate   # Apply migrations
npm run db:studio    # Open database studio
npm test             # Run tests
```

## Check the installation

After setup, continue with the [first example](/docs/up-to-code-sonicjs/quick-start-guide). If a command fails, compare the runtime version, working directory, and required configuration with the original README before changing dependencies.

## Source and help

- [GitHub repository](https://github.com/Up-to-code/sonicjs)
- [Original README](https://github.com/Up-to-code/sonicjs/blob/main/README.md)
- [Issues and existing reports](https://github.com/Up-to-code/sonicjs/issues)
- [Open the project website](https://sonicjs.com)

The catalog identifies the license as **MIT**. Read the repository license before redistributing source or assets.

This catalog entry is a fork. The README may describe upstream packages, domains, or release procedures; those destinations do not establish a separate release of this fork.