Sinatra like web toolkit based on Lwt + Cohttp

Executive Summary

Sinatra like web toolkit for OCaml based on cohttp & lwt

Design Goals

  • Opium should be very small and easily learnable. A programmer should
    be instantly productive when starting out.

  • Opium should be extensible using independently developed plugins. This is a
    Rack inspired mechanism borrowed from Ruby. The middleware mechanism in
    Opium is called Rock.

  • It should maximize use of creature comforts people are used to in
    other languages. Such as sexplib, fieldslib, a decent
    standard library.



The latest stable version is available on opam

$ opam install opium


If you'd like to live on the bleeding edge (which is sometimes more stable than

$ opam pin add opium --dev-repo


All examples are built once the necessary dependencies are installed.
$ dune build @examples will compile all examples. The binaries are located in

Hello World

Here's a simple hello world example to get your feet wet:

$ cat hello_world.ml

open Opium.Std

type person = {
  name: string;
  age: int;

let json_of_person { name ; age } =
  let open Ezjsonm in
  dict [ "name", (string name)
       ; "age", (int age) ]

let print_param = put "/hello/:name" begin fun req ->
  `String ("Hello " ^ param req "name") |> respond'

let print_person = get "/person/:name/:age" begin fun req ->
  let person = {
    name = param req "name";
    age = "age" |> param req |> int_of_string;
  } in
  `Json (person |> json_of_person) |> respond'

let _ =
  |> print_param
  |> print_person
  |> App.run_command

compile with:

$ ocamlbuild -pkg opium.unix hello_world.native

and then call

./hello_world.native &
curl http://localhost:3000/person/john_doe/42

You should see a JSON message.


The two fundamental building blocks of opium are:

  • Handlers: Rock.Request.t -> Rock.Response.t Lwt.t

  • Middleware: Rock.Handler.t -> Rock.Handler.t

Almost every all of opium's functionality is assembled through various
middleware. For example: debugging, routing, serving static files,
etc. Creating middleware is usually the most natural way to extend an
opium app.

Here's how you'd create a simple middleware turning away everyone's
favourite browser.

open Opium.Std

(* don't open cohttp and opium since they both define
   request/response modules*)

let is_substring ~substring =
  let re = Re.compile (Re.str substring) in
  Re.execp re

let reject_ua ~f =
  let filter handler req =
    match Cohttp.Header.get (Request.headers req) "user-agent" with
    | Some ua when f ua ->
      `String ("Please upgrade your browser") |> respond'
    | _ -> handler req in
  Rock.Middleware.create ~filter ~name:"reject_ua"

let _ =
  |> get "/" (fun _ -> `String ("Hello World") |> respond')
  |> middleware (reject_ua ~f:(is_substring ~substring:"MSIE"))
  |> App.cmd_name "Reject UA"
  |> App.run_command

Compile with:

$ ocamlbuild -pkg opium.unix middleware_ua.native

Here we also use the ability of Opium to generate a cmdliner term to run your
app. Run your executable with the -h to see the options that are available to
you. For example:

# run in debug mode on port 9000
$ ./middleware_ua.native -p 9000 -d
21 Mar 2019
Reverse Dependencies
< "0.2.0"