camlworks/dream

Tidy, feature-complete Web framework

Source code at GitHub https://camlworks.github.io/dream/

{
  "createdAt": "2021-03-08T02:59:36Z",
  "defaultBranch": "master",
  "description": "Tidy, feature-complete Web framework",
  "fullName": "camlworks/dream",
  "homepage": "https://camlworks.github.io/dream/",
  "language": "OCaml",
  "name": "dream",
  "pushedAt": "2025-10-14T12:33:52Z",
  "stargazersCount": 1791,
  "topics": [
    "framework",
    "graphql",
    "http",
    "ocaml",
    "reasonml",
    "web",
    "websockets"
  ],
  "updatedAt": "2025-11-25T19:46:46Z",
  "url": "https://github.com/camlworks/dream"
}

Dream

Easy-to-use, feature-complete Web framework without boilerplate.

Source code of minimal app using the Dream Web framework for OCaml

Quick Start | Tutorial | Reference

Dream is one flat module in one package, documented on [one page][api-main], but with [many examples][tutorial]. It offers:

[WebSockets][websocket] and [GraphQL][graphql] for your modern Web apps.
[HTML templates][templates] with embedded OCaml or [Reason][reason-templates] — use existing skills!
[Sessions][sessions] with pluggable storage [back ends][back-ends].
Easy [HTTPS and HTTP/2 support][https] — Dream runs without a proxy.
Helpers for [secure cookies][cookies] and [CSRF-safe forms][forms].
Full-stack ML with clients compiled by [Melange][melange], [ReScript][rescript], or [js_of_ocaml][jsoo].

…all without sacrificing ease of use — Dream has:

A simple programming model — Web apps are [just functions][handler]!
Composable [middleware][middleware] and [routes][routing].
Unified, internationalization-friendly [error handling][errors].
[Cryptography][crypto] helpers, key rotation, and a chosen cipher.
A neat [logger][logging], and attention to configuring the OCaml runtime nicely.
[Deployment][deploy] instructions for Digital Ocean, Heroku, and Fly.io, with sample CI scripts.

Every part of the API is arranged to be easy to understand, use, and remember. Dream sticks to base OCaml types like string and list, introducing only a few [types][types] of its own — and some of those are just abbreviations for bare functions!

The neat interface is not a limitation. Everything is still configurable by a large number of optional arguments, and very loose coupling. Where necessary, Dream exposes the lower-level machinery that it is composed from. For example, the basic body and WebSocket readers [return strings][basic-read], but you can also do [zero-copy streaming][streaming].

You can even run Dream as a [quite bare abstraction][raw] over its [underlying set of HTTP libraries][vendor], where it acts only as minimal glue code between their slightly different interfaces.

And, even though Dream is presented as one package for ordinary usage, it is internally factored into [several sub-libraries][libs], according to the different dependencies of each, for fast porting to different environments.

Dream is a low-level and unopinionated framework, and you can swap out its conveniences. For example, you can use TyXML with [server-side JSX][jsx] instead of Dream’s built-in templates. You can bundle assets into a [single Dream binary][one-binary], or use Dream in a subcommand. Dream tries to be as functional as possible, touching global runtime state only lazily, when called into.

Quick start

You can get one of the first [tutorials][tutorial] and build it locally with:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/aantron/dream/master/example/quickstart.sh)"

opam

Create a project directory with an optional local switch:

mkdir project
cd project
opam switch create . 5.1.0
eval $(opam env)

Install Dream:

opam install dream

After that, go to any of the [examples][tutorial], such as [2-middleware][2-middleware], re-create the files locally, and run it:

dune exec ./middleware.exe

[esy-example] !: https://github.com/aantron/dream/tree/master/example/w-esy#folders-and-files [quickstart.sh] !: https://github.com/aantron/dream/blob/master/example/quickstart.sh [esy] !: https://esy.sh/ [2-middleware] !: https://github.com/aantron/dream/tree/master/example/2-middleware#folders-and-files

esy

Visit any of the [examples][tutorial], such as [2-middleware][2-middleware], and re-create the files locally. The file esy.json shows how to depend on Dream. All of the examples are installed by running npx esy, and started with npx esy start.

Documentation

[Tutorial][tutorial] — Threads together the first several examples of Dream, touching all the basic topics, including security. See the full list and start wherever you like, or begin at [1-hello][1-hello], the Dream version of Hello, world!
[Reason syntax][reason-examples] — Several of the examples are written in Reason. See [r-hello][r-hello].
[Full-stack][fullstack] — See skeleton projects [r-fullstack-melange][melange], [w-fullstack-rescript][rescript], and [w-fullstack-jsoo][jsoo].
[Deploying][deploying] — Quick start instructions for small-to-medium deployments.
[Examples][examples] — These cover various HTTP scenarios.
[API reference][api-main]
[Watching][watch] and [live reloading][reload].

Recommended projects

dream-cli — command-line interface for Dream applications.
dream-encoding — compression middleware.
dream-livereload — live reloading.
emile — email address syntax validation.
letters — SMTP client.

Example repositories

dream-mail-example — sends email using RabbitMQ and Mailgun [blog post, discuss].
dream-melange-tea-tailwind — The Elm Architecture with a Dream server, client compiled by Melange.

Contact

Apart from the issues, good places to discuss Dream are…

#dream on the Reason Discord.
#webdev on the OCaml Discord.
The OCaml Discuss forum.
The development stream on Twitch.

Highlight @antron to poke @aantron specifically.

Contributing

All kinds of contributions are welcome, including examples, links to blogs, related libraries, and, of course, PRs! See [CONTRIBUTING.md][contributing.md].

[contributing.md] !: https://github.com/aantron/dream/blob/master/docs/CONTRIBUTING.md

Acknowledgements

Dream is based on work by the authors and contributors of its [many dependencies][opamfile] and their transitive dependencies. There are, however, several influences that cannot be discovered directly:

Templates are inspired by [ECaml][ecaml] from [Alexander Markov][komar] and [Embedded OCaml Templates][eot] from [Emile Trotignon][trotignon].
Dream’s handler and middleware types are simplified from [Opium][opium] by [Rudi Grinberg][rgrinberg] and contributors.
The lower-level HTTP and WebSocket servers use [Antonio Nuno Monteiro][anmonteiro]‘s forks and original works, with credit also due to their contributors, and [Spiros Eliopoulos][seliopou] in particular, as the original author of the http/af family of projects.
The API docs are instantiated by [Soupault][soupault] from [Daniil Baturin][dmbaturin].
The name was inspired by [Morph][morph] from [Ulrik Strid][ulrikstrid], which was itself partially inspired by [Opium][opium].
[Raphael Rafatpanah][persianturtle] and [El-Hassan Wanas][foocraft] provided important early feedback.