Dream is one flat module in one package, documented on
one page, but with many examples. It offers:
- WebSockets and GraphQL for your modern Web
apps. - HTML templates with embedded OCaml or
Reason — use existing skills! - Sessions with pluggable storage back ends.
- Easy HTTPS and HTTP/2 support — Dream runs without a
proxy. - Helpers for secure cookies and
CSRF-safe forms. - Full-stack ML with clients compiled by Melange,
ReScript, or js_of_ocaml.
...all without sacrificing ease of use — Dream has:
- A simple programming model — Web apps are just functions!
- Composable middleware and routes.
- Unified, internationalization-friendly error handling.
- Cryptography helpers, key rotation, and a chosen cipher.
- A neat logger, and attention to configuring the OCaml runtime
nicely. - Deployment 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 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, but you can
also do zero-copy streaming.
You can even run Dream as a quite bare abstraction over its underlying
set of HTTP libraries, 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, 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
instead of Dream's built-in templates. You can bundle assets into a single
Dream 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
Visit one of the first tutorials in the online
playground, and read its
docs.
You can get and build it locally with:
Most of the other examples are also loaded in the playground. See
the links on its home page.
esy
Visit any of the examples, such as
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.
opam
opam install dream
After that, go to any of the examples, such as
2-middleware, re-create the files locally, and run it:
dune exec ./middleware.exe
Documentation
- 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 at1-hello, the Dream
version of Hello, world! - Reason syntax — Several of the examples are
written in Reason. Seer-hello. - Full-stack — See skeleton projects
r-fullstack-melange,w-fullstack-rescript,
andw-fullstack-jsoo. - Deploying — Quick start instructions for
small-to-medium deployments. - Examples — These cover various HTTP scenarios.
- API reference
- Watching and live reloading.
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.
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.
As an immediate note, if you'd like to clone the repo, be sure to use
--recursive, because Dream uses several git submodules:
git clone https://github.com/aantron/dream.git --recursive
Acknowledgements
Dream is based on work by the authors and contributors of its many
dependencies and their transitive dependencies. There are, however,
several influences that cannot be discovered directly:
- Templates are inspired by ECaml from Alexander Markov
and Embedded OCaml Templates from Emile Trotignon. - Dream's handler and middleware types are simplified from Opium by
Rudi Grinberg and contributors. - The lower-level HTTP and WebSocket servers are vendored copies of
Antonio Nuno Monteiro's forks and original works, with credit
also due to their contributors, and Spiros Eliopoulos in
particular, as the original author of two of the projects. - The API docs are instantiated by Soupault from
Daniil Baturin. - The name was inspired by Morph from Ulrik Strid,
which was itself partially inspired by Opium. - Raphael Rafatpanah and El-Hassan Wanas provided
important early feedback.