Dream

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

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 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.

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. 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 takes care of horridness like ALPN.

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.

Getting started

Dream is not yet announced or released! Before release, Dream will get a quick-start script, and some other help for getting started quickly. However, if you want to try Dream now, you can add:

"dependencies": {
  "@opam/dream": "aantron/dream:dream.opam"
}

to your esy.json. See example w-esy for a minimal project.

Alternatively, if you are using opam:

git clone https://github.com/aantron/dream.git --recursive
cd dream
opam install .

Note: the clone must be --recursive, because Dream vendors several packages as git submodules. Also, if you have gluten, httpaf, h2, or websocketaf, or their gluten-*, etc., subpackages independently installed in your switch, you may have to remove them with opam remove to avoid conflicts. However, they should not be pulled into a basic build of Dream and most programs that use it.

After that, go to one of the examples, such as 1-hello, and try building it:

cd example/1-hello
dune exec --root . ./hello.exe

If you prefer Reason syntax, try example r-hello instead.

You should be able to copy the example out to a completely separate directory, if you didn't use a local _opam switch scoped to Dream's clone directory. If you did, you can pin Dream to your clone in a different opam switch with

opam pin add dream /path/to/your/clone