Every change has one place.
Routes in config/routes.cr, actions in app/actions/, views in app/views/. Your application’s files are the extension point.
A web framework for Crystal
PostgreSQL, typed HTML, and a clear place for every change. Six rules do most of the work — the compiler and the test suite keep you to them.
Six rules
Routes in config/routes.cr, actions in app/actions/, views in app/views/. Your application’s files are the extension point.
Each field is typed and bounded in the action’s contract, and a route parameter without a contract field stops the build, not the request.
Validations and unique constraints live on the changeset, so the rules hold for every caller. Schema first, then a migration you derive and review.
Views are typed Crystal classes that escape text and attributes by default. Reach for htmx fragments before client state, and islands only for widgets that need their own.
Jobs run at least once: enqueue in the same transaction as the write, and pass ids rather than records.
Request specs run against real PostgreSQL and assert what users observe: HTML, rows, statuses, headers.
In practice
Creating a book reads like a short sentence: take the declared input, write it through a changeset, queue the follow-up in the same transaction, answer with the record or its errors.
And then frappe corretto proves it — rule 06.
def handle(contract : Contract)
changes = App::Book::Changeset.new(title: contract.title, author: contract.author)
SugarORM::Repo.transaction do
SugarORM::Repo.insert(changes)
App::SendReceipt.enqueue(book_id: changes.record.id) if changes.saved?
end
return render_errors(changes.errors) unless changes.saved?
{record: changes.record}
endProject map
Say what you want to change. Caramel already knows where it goes, and how to check it.
| I want to… | It goes in | Check it with |
|---|---|---|
| Add an endpoint | config/routes.cr and an action in app/actions/ with its contract | frappe routes |
| Render a page | A Blueprint view in app/views/ — typed inputs, escaped output | frappe check |
| Store new data | The SugarORM schema first, then a migration you derive and review | frappe db diff |
| Do work later | A Cold Brew job, enqueued beside the write it follows | frappe corretto |
| Speak another language | Translation catalogs — t. messages with named placeholders | frappe translations |
| Keep the code honest | Descriptive names, short blocks, small actions — the verb on the model, not a service | frappe lint |
Layer by layer
From the HTML your users see down to the services on your machine, every part of Caramel does one thing — and all of it stands on PostgreSQL. SweetTalk, an opt-in language for the domain model, sits on top: build a box office with it.
Status
Your first application
frappe new bookshelf && cd bookshelf
frappe make resource Book title:string author:string
frappe migrate
frappe check && frappe lint && frappe corretto
frappe devThe Learn page says what each command prints; frappe dev holds the terminal until Ctrl-C.