README

README.md

Dream

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

Quick Start |Playground | Tutorial |Reference   

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

• WebSockets andGraphQL for your modern Web apps.

• HTML templates with embedded OCaml orReason — use existing skills!

• Sessions with pluggable storageback ends.

• EasyHTTPS andHTTP/2 support — Dream runs without a proxy.

• 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 runtime nicely.

• Deployment instructions forDigital Ocean andHeroku, 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 a fewtypes 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 readersreturn strings, but you can also dozero-copy streaming.

You can even run Dream as aquite bare abstraction over itsunderlying 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 intoseveral 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 withserver-side JSX instead of Dream's built-in templates. You can bundle assets into asingle 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

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

This downloads and runsquickstart.sh, which does a sandboxed build of one of the firsttutorials,2-middleware. It's mostly the same as:

git clone https://github.com/aantron/dream.git --recursivecd dream/example/2-middlewarenpm install esy && npx esynpx esy start

Knowing that, you can start from any otherexample. All of them include their own build commands. They don't have to be subdirectories ofdream — you can copy them out to start your own project directory. Especially consider starting with thefull-stack examples, which build both a Dream server and a JavaScript client.

opam

opam install dream

After that, go to one of the examples, such as1-hello, and build it:

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

Playground

Most of the examples are loaded into theplayground. For instance,2-middleware is athttp://dream.as/2-middleware.

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 ofHello, world!

• Reason syntax — Several of the examples are written in Reason. Seer-hello.

• Full-stack — See skeleton projectsr-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 andlive reloading.

Contributing

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

As an immediate note, if you'd like to clone the repo, be sure to use--recursive, because Dream uses several gitsubmodules:

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

Acknowledgements

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

• Templates are inspired byECaml fromAlexander Markov andEmbedded OCaml Templates fromEmile Trotignon.

• Dream's handler and middleware types are simplified fromOpium byRudi Grinberg and contributors.

• The lower-level HTTP and WebSocket servers arevendored copies ofAntonio Nuno Monteiro's forks and original works, with credit also due to their contributors, andSpiros Eliopoulos in particular, as the original author of two of the 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 provided important early feedback.

1. result
2. psq
3. faraday-lwt-unix
4. faraday>= "0.6.1"
5. digestif>= "0.7.2"
6. bigstringaf>= "0.5.0"
7. angstrom>= "0.14.0"
8. yojson
9. uri>= "4.2.0"
10. ocaml>= "4.08.0" & < "5.0"
11. multipart_form>= "0.3.0" & < "0.4.0"
12. mirage-crypto-rng>= "0.8.0" & < "0.11.0"
13. mirage-crypto>= "0.8.1" & < "1.0.0"
14. magic-mime
15. logs>= "0.5.0"
16. ssl>= "0.5.8"
17. lwt_ssl
18. lwt_ppx>= "1.2.2"
19. lwt
20. hmap
21. graphql-lwt
22. graphql_parser
23. fmt>= "0.8.7"
24. dune>= "2.7.0"
25. cstruct>= "6.0.0"
26. conf-libevos != "win32"
27. caqti-lwt
28. caqti>= "1.4.0" & < "2.0.0~"
29. bigarray-compat
30. base64>= "3.1.0"
31. base-unix

1. tyxml-ppxwith-test & >= "4.5.0"
2. tyxml-jsxwith-test & >= "4.5.0"
3. tyxmlwith-test & >= "4.5.0"
4. reasonwith-test
5. ppx_yojson_convwith-test
6. ppx_expectwith-test
7. lambdasoupwith-test
8. crunchwith-test
9. caqti-driver-sqlite3with-test
10. bisect_ppxwith-test & >= "2.5.0"
11. alcotestwith-test

1. builder-web< "0.2.0"
2. dream-cli< "0.2.0"
3. dream-encoding< "0.2.0"
4. dream-livereload< "0.2.0"
5. dream-serve< "1.0.1"
6. graphql_jsoo_client
7. hyper
8. osh
9. ppx_dream_eml
10. u2f
11. universal-portal
12. webauthn< "0.2.0"

1. tls>= "0.15.0"