Get started

From nothing to a served page. You need OCaml 5.1 or newer and opam 2.x.

1. Add the repository

The araara libraries are published in their own opam repository. Add it once per switch:

$ opam repo add araara git+https://tangled.org/gdiazlo.tngl.sh/repo
$ opam update

2. Install the stack

Install only what you need — every library stands alone. For a typical web application:

$ opam install hcs pure-html repodb repodb-sqlite simdjsont climate testo

3. Declare the project

dune-project
(lang dune 3.22)
(generate_opam_files true)

(name my_app)

(package
 (name my_app)
 (synopsis "My first araara application")
 (depends
  (ocaml (>= 5.1.0))
  dune
  (eio (>= 1.2))
  (eio_main (>= 1.2))
  (hcs (>= 0.11))
  (pure-html (>= 3.11))
  (simdjsont (>= 0.3))
  (repodb (>= 0.7))
  (repodb-sqlite (>= 0.7))
  (climate (>= 0.9))
  (testo :with-test)))

4. Serve a page

A complete application: a typed view, a route, a pipeline- ready endpoint, and a multi-domain HTTP server.

bin/main.ml
(* The smallest araara service: one route, one typed view, one server.
   Run with: dune exec examples/hcs_hello/main.exe *)

let hello_page =
  let open Pure_html in
  let open HTML in
  html
    [ lang "en" ]
    [
      head [] [ title [] "Hello from araara" ];
      body [] [ h1 [] [ txt "Hello, araara!" ] ];
    ]

let hello _params _req =
  Hcs.Server.respond_html (Pure_html.to_string hello_page)

let () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let routes =
    Hcs.Router.(compile_scopes [ scope "/" [ Route.get "/" hello ] ])
  in
  let handler =
    Hcs.Endpoint.(
      create default_config |> Fun.flip router routes |> to_handler)
  in
  Hcs.Server.run ~sw
    ~net:(Eio.Stdenv.net env)
    ~clock:(Eio.Stdenv.clock env)
    handler
bin/dune
; bin/dune
(executable
 (name main)
 (public_name my-app)
 (libraries hcs pure-html eio_main))
$ dune exec my-app

Open http://localhost:8080 — that's the whole loop.

Where to go next