Skip to content
caramelrelease · 0.23.0

A web framework for Crystal

A little structure.
A lot of possibility.

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

Short enough to remember.
Strict enough to rely on.

01 · Structure

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.

02 · Contracts

Every input is declared.

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.

03 · SugarORM

Every write goes through a changeset.

Validations and unique constraints live on the changeset, so the rules hold for every caller. Schema first, then a migration you derive and review.

04 · Blueprint

Everything is escaped unless your code built it.

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.

05 · Cold Brew

Every job is safe to run twice.

Jobs run at least once: enqueue in the same transaction as the write, and pass ids rather than records.

06 · Corretto

Every change is proven.

Request specs run against real PostgreSQL and assert what users observe: HTML, rows, statuses, headers.

In practice

One action.
Four rules at work.

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.

app/actions/books/create.cr · an illustration: handle, with a SendReceipt job you defineCrystal
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}
end
Margin numbers mark the rule each line keeps. The record renders through an escaping Blueprint view.

Project map

Start with your intention.

Say what you want to change. Caramel already knows where it goes, and how to check it.

I want to…It goes inCheck it with
Add an endpointconfig/routes.cr and an action in app/actions/ with its contractfrappe routes
Render a pageA Blueprint view in app/views/ — typed inputs, escaped outputfrappe check
Store new dataThe SugarORM schema first, then a migration you derive and reviewfrappe db diff
Do work laterA Cold Brew job, enqueued beside the write it followsfrappe corretto
Speak another languageTranslation catalogs — t. messages with named placeholdersfrappe translations
Keep the code honestDescriptive names, short blocks, small actions — the verb on the model, not a servicefrappe lint

Layer by layer

Seven layers.
One job each.

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.

  1. BlueprintHTML written in typed Crystal
  2. SugarORMSchemas, changesets and queries
  3. Cold BrewBackground work, backed by PostgreSQL
  4. CorrettoApplication tests with real data
  5. CremaLogs, metrics and traces
  6. FrappéYour developer command line
  7. LatteLocal services and named HTTPS

Status

What to expect.

  • Caramel 0.15.0 is released. During 0.x a minor release can break compatibility; the current release guide says what each one changes. SweetTalk is experimental and Draft recipes are labelled.
  • Development runs on Apple Silicon macOS today — what the machine needs.
  • Caramel builds a linux/amd64 artifact and states what it promises a deploy tool; it ships no command that provisions servers or deploys — read the production contract.

Your first application

Start with something real.

Terminal · after installing the 0.23.0 release
frappe new bookshelf && cd bookshelf
frappe make resource Book title:string author:string
frappe migrate
frappe check && frappe lint && frappe corretto
frappe dev

The Learn page says what each command prints; frappe dev holds the terminal until Ctrl-C.