create-sonicjs

The easiest way to create a new SonicJS application

Quick Start

npx create-sonicjs my-app

That's it! Follow the interactive prompts and you'll have a running SonicJS application in minutes.

What It Does

create-sonicjs sets up everything you need for a modern headless CMS on Cloudflare's edge:

• ✅ Project scaffolding - Complete project structure
• ✅ Template selection - Choose from pre-built templates
• ✅ Cloudflare resources - Optionally create D1 database and R2 bucket
• ✅ Configuration - Auto-configured wrangler.toml
• ✅ Dependencies - Installs all required packages
• ✅ Git initialization - Ready for version control
• ✅ Example code - Optional blog collection example

Usage

Interactive Mode (Recommended)

npx create-sonicjs

You'll be prompted for:

• Project name
• Template choice
• Database name
• R2 bucket name
• Whether to include examples
• Whether to create Cloudflare resources
• Whether to initialize git

With Project Name

npx create-sonicjs my-blog

Command Line Options

npx create-sonicjs my-app --template=starter --skip-install

Available flags:

• --template=<name> - Skip template selection (e.g., --template=starter)
• --database=<name> - Set database name without prompt
• --bucket=<name> - Set R2 bucket name without prompt
• --include-example - Include example blog collection (no prompt)
• --skip-example - Skip example blog collection (no prompt)
• --skip-install - Don't install dependencies
• --skip-git - Don't initialize git
• --skip-cloudflare - Don't prompt for Cloudflare resource creation

Templates

Starter (Default)

Perfect for blogs, documentation, and content sites.

Includes:

• Blog collection example
• Admin dashboard
• REST API
• Media management

Coming Soon:

• E-commerce template
• Documentation site template
• Portfolio template

Requirements

• Node.js 18 or higher
• npm 7 or higher (or yarn/pnpm)
• wrangler (optional, for Cloudflare resources)

What Gets Created

my-app/
├── src/
│   ├── index.ts              # Application entry point
│   └── collections/          # Content type definitions
│       └── blog-posts.collection.ts
├── wrangler.toml             # Cloudflare Workers config
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript config
├── .gitignore
└── README.md

After Creation

1. Navigate to your project

cd my-app

2. Create Cloudflare resources (if skipped)

wrangler d1 create my-app-db
# Copy the database_id to wrangler.toml

wrangler r2 bucket create my-app-media

3. Run database migrations

npm run db:migrate:local

4. Start development server

npm run dev

5. Open admin interface

Visit http://localhost:8787/admin

Default credentials:

• Email: [email protected]
• Password: admin

Package Managers

Works with all major package managers:

# npm
npx create-sonicjs my-app

# yarn
yarn create sonicjs my-app

# pnpm
pnpm create sonicjs my-app

The CLI automatically detects your package manager from lock files.

Environment Variables

After creation, you may want to set up environment variables:

# .dev.vars (for local development)
ENVIRONMENT=development

Cloudflare Resources

D1 Database

If you create resources during setup, a D1 database is automatically created and configured.

Manual creation:

wrangler d1 create my-app-db

R2 Bucket

For media storage, an R2 bucket is created.

Manual creation:

wrangler r2 bucket create my-app-media

Troubleshooting

"wrangler is not installed"

Install wrangler globally:

npm install -g wrangler

"Directory already exists"

Choose a different project name or remove the existing directory:

rm -rf my-app

Dependencies fail to install

Try manually:

cd my-app
npm install

Cloudflare resource creation fails

You can create resources manually after project creation. See the After Creation section.

Advanced Usage

Skip All Prompts (Non-Interactive Mode)

npx create-sonicjs my-app \
  --template=starter \
  --database=my-app-db \
  --bucket=my-app-media \
  --include-example \
  --skip-install \
  --skip-git \
  --skip-cloudflare

Use in CI/CD

npx create-sonicjs test-app \
  --template=starter \
  --database=test-db \
  --bucket=test-bucket \
  --skip-example \
  --skip-install \
  --skip-cloudflare \
  --skip-git

Features

• 🎨 Beautiful CLI - Colored output and progress indicators
• ⚡ Fast - Optimized for speed
• 🔒 Type-safe - Full TypeScript support
• 🌐 Edge-first - Built for Cloudflare Workers
• 📦 Zero config - Works out of the box
• 🔧 Customizable - Easy to extend

Examples

Create a blog

npx create-sonicjs my-blog
# Select "Starter" template
# Include example collection: Yes

Create without examples

npx create-sonicjs my-app
# Include example collection: No

Related

• @sonicjs-cms/core - Core framework
• SonicJS Documentation
• Cloudflare Workers

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT © SonicJS Team

Support

• Issues: GitHub Issues
• Discord: Join our community
• Docs: docs.sonicjs.com

Built with ❤️ for developers | v2.0.0-alpha.1