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 tyxml repodb repodb-sqlite simdjsont climate alcotest qcheck

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))
   tyxml
  (simdjsont (>= 0.3))
  (repodb (>= 0.7))
  (repodb-sqlite (>= 0.7))
  (climate (>= 0.9))
   (alcotest :with-test)
   (qcheck :with-test)))

4. Serve a page

A complete little application in one file: a typed view, a route, an endpoint ready to drop into a pipeline, and an HTTP server that can host more than one site at once.

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 Tyxml.Html in
  html
    (head (title (txt "Hello from araara")) [])
    (body [ h1 [ txt "Hello, araara!" ] ])

let hello _params _req =
  Hcs.Server.respond_html (Format.asprintf "%a" (Tyxml.Html.pp ()) 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 tyxml eio_main))
$ dune exec my-app

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

Where to go next