Skip to content

quickstart.md

Latest commit

 

History

History
143 lines (103 loc) · 2.97 KB

quickstart.md

File metadata and controls

143 lines (103 loc) · 2.97 KB

Quick Start Guide

Get a working application from your Dazzle DSL in under 5 minutes.

What you'll write

A Dazzle app is a DSL spec. The entity is the core building block — it becomes a database table, a typed REST API, and a UI surface:

entity Task "Task":
  id: uuid pk
  title: str(200) required
  status: enum[open, in_progress, done] = open
  due: date

Prerequisites

Step 1: Create a Project

dazzle init my_app
cd my_app

Or start from a built-in example:

dazzle init my_app --from simple_task
cd my_app

Step 2: Validate Your DSL

dazzle validate

Fix any errors before proceeding.

Step 3: Set Up PostgreSQL

Dazzle requires PostgreSQL for data persistence.

# Start PostgreSQL via Docker (quick option)
docker run -d --name dazzle-postgres \
  -e POSTGRES_USER=dazzle \
  -e POSTGRES_PASSWORD=dazzle \
  -e POSTGRES_DB=dazzle \
  -p 5432:5432 \
  postgres:16

# Set the database URL
export DATABASE_URL=postgresql://dazzle:dazzle@localhost:5432/dazzle

Tables are created automatically on first startup.

Step 4: Run the Application

# Docker mode (default — recommended)
dazzle serve

# Or run locally without Docker
dazzle serve --local

This starts:

  • UI at http://localhost:3000
  • API at http://localhost:8000/api/
  • API Docs at http://localhost:8000/docs

Step 5: Try the API

Create a record via the API:

curl -X POST http://localhost:8000/_dazzle/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn Dazzle", "status": "open"}'

Example: Simple Task Manager

Given this DSL in dsl/app.dsl:

module simple_task
app simple_task "Simple Task Manager"

entity Task "Task":
  id: uuid pk
  title: str(200) required
  status: enum[open, in_progress, done] = open
  created_at: datetime auto_add

surface task_list "Task List" -> Task list:
  section main:
    field title "Title"
    field status "Status"

Validate and run:

dazzle validate
dazzle serve --local

Development Workflow

# Terminal 1: Serve with hot reload
dazzle serve --local --watch

# Terminal 2: Edit your DSL files
# Changes are picked up automatically

Useful Commands

Command Purpose
dazzle validate Check DSL for errors
dazzle lint Extended validation with style checks
dazzle serve Start the full-stack app
dazzle serve --local --watch Local mode with hot reload
dazzle doctor Check environment health
dazzle inspect Inspect project structure

Next Steps