Repository files navigation

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

Quick Start | Tutorial |Reference   

Dream isone flat module inone package, documented onone page, but withmany examples. It offers:

• WebSockets andGraphQL for your modern Webapps.
• HTML templates with embedded OCaml orReason — use existing skills!
• Sessions with pluggable storageback ends.
• EasyHTTPS andHTTP/2 support — Dream runs without aproxy.
• Helpers forsecure cookies andCSRF-safe forms.
• Full-stack ML with clients compiled byMelange,ReScript, orjs_of_ocaml.

...all without sacrificing ease of use — Dream has:

• A simple programming model — Web apps arejust functions!
• Composablemiddleware androutes.
• Unified, internationalization-friendlyerror handling.
• Cryptography helpers, key rotation, and a chosen cipher.
• A neatlogger, and attention to configuring the OCaml runtimenicely.
• Deployment instructions forDigital Ocean,Heroku, andFly.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 likestring andlist, introducing only afewtypes of its own — and some of those are just abbreviationsfor bare functions!

The neat interface is not a limitation. Everything is still configurable by alarge 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 readersreturn strings, but you canalso dozero-copy streaming.

You can even run Dream as aquite bare abstraction over itsunderlyingset of HTTP libraries, where it acts only as minimal glue code betweentheir slightly different interfaces.

And, even though Dream is presented as one package for ordinary usage, it isinternally factored intoseveral sub-libraries, according to thedifferent dependencies of each, for fast porting to different environments.

Dream is a low-level and unopinionated framework, and you can swap out itsconveniences. For example, you can use TyXML withserver-side JSXinstead of Dream's built-in templates. You can bundle assets into asingleDream binary, or use Dream in a subcommand. Dream tries to be asfunctional as possible, touching global runtime state only lazily, when calledinto.

You can getoneof the firsttutorials and build it locally with:

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

Create a project directory with an optional local switch:

mkdir projectcd projectopam switch create . 5.1.0eval $(opam env)

Install Dream:

opam install dream

After that, go to any of theexamples, such as2-middleware, re-create the files locally, and run it:

dune exec ./middleware.exe

Visit any of theexamples, such as2-middleware, and re-create the files locally. The fileesy.jsonshows how to depend on Dream. All of the examples are installed by runningnpx esy, and started withnpx esy start.

• Tutorial — Threads together the first several examplesof Dream, touching all the basic topics, including security. See the full listand start wherever you like, or begin at1-hello, the Dreamversion ofHello, world!
• Reason syntax — Several of the examples arewritten in Reason. Seer-hello.
• Full-stack — See skeleton projectsr-fullstack-melange,w-fullstack-rescript,andw-fullstack-jsoo.
• Deploying — Quick start instructions forsmall-to-medium deployments.
• Examples — These cover various HTTP scenarios.
• API reference
• Watching andlive reloading.

• dream-cli  — command-line interface for Dream applications.
• dream-encoding  —  compression middleware.
• dream-livereload —  live reloading.
• emile  —  emailaddress syntax validation.
• letters  —  SMTPclient.

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

Apart from theissues, good placesto discuss Dream are...

• #dream on theReason Discord.
• #webdev on theOCaml Discord.
• TheOCaml Discuss forum.
• The development stream onTwitch.

Highlight@antron to poke @aantron specifically.

All kinds of contributions are welcome, including examples, links to blogs,related libraries, and, of course, PRs! SeeCONTRIBUTING.md.

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

• Templates are inspired byECaml fromAlexander MarkovandEmbedded OCaml Templates fromEmile Trotignon.
• Dream's handler and middleware types are simplified fromOpium byRudi Grinberg and contributors.
• The lower-level HTTP and WebSocket servers useAntonio Nuno Monteiro's forks and original works, with creditalso due to their contributors, andSpiros Eliopoulos inparticular, as the original author of the http/af family of projects.
• The API docs are instantiated bySoupault fromDaniil Baturin.
• The name was inspired byMorph fromUlrik Strid,which was itself partially inspired byOpium.
• Raphael Rafatpanah andEl-Hassan Wanas providedimportant early feedback.