# \[ANN\] Brr 0.0.1, a toolkit for programming browsers
**URL:** https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608
**Category:** Community
**Tags:** announce
**Created:** [October 14, 2020, 12:27pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608 "2020-10-14T12:27:56Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [October 14, 2020, 12:27pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/1 "2020-10-14T12:27:56Z")
Hello,
I’d like to announce the first release of Brr.
The TL; DR is:
> If you are looking for a productive way to program browsers with js\_of\_ocaml but without ppx and ghost OCaml objects, give Brr a try.
The details:
> Brr is a toolkit for programming browsers in OCaml with the
> [`js_of_ocaml`](https://ocsigen.org/js_of_ocaml) compiler. It provides:
>
> - Interfaces to a [selection](https://erratique.ch/software/brr/doc/index.html#supported_apis) of browser APIs.
> - Note based reactive support (optional and experimental).
> - An [OCaml console](https://erratique.ch/software/brr/doc/ocaml_console.html) developer tool for live interaction
> with programs running in web pages.
> - A JavaScript FFI for idiomatic OCaml programming.
>
> Brr is distributed under the ISC license. It depends on [Note](https://erratique.ch/software/note) and on the `js_of_ocaml` compiler and runtime – but not on its libraries or syntax extension.
Homepage: [Brr / Erratique](https://erratique.ch/software/brr)
API Docs & manuals: [index (brr.index)](https://erratique.ch/software/brr/doc/) or `odig doc brr`
Install: `opam install brr`
Brr is essentially what I need to be productive for browser programming with js\_of\_ocaml: an obvious FFI with JavaScript objects as abstract data types without OCaml object phantom types and binding documentation precisely linking into MDN.
The OCaml console is the hack on the cake. In the past I often found it frustrating to have OCaml programs running in my webpages and be greeted with a JavaScript prompt in the browser dev tools. Quite a bit of polishing could be done on that though. Some of which should likely directly be done upstream in the toplevel machinery (e.g. identifier completion, a better toploop API and support for easy pretty printer installation). It would also be nice if we could cut down on `js_of_ocaml`’s toplevel compilation times ;–)
Parts of Brr have been seriously dogfooded in the past but that new incarnation is largely untested for now and certain APIs might need adjustements. Early adopters should study actual binding coverage, expect glitches and little breakages in the future.
The Note reactive functionality was also seriously used in the past but Note itself needs a new design round and I don’t have the ressources to do it right now, expect breakage, don’t pay too much attention to it for now.
My thanks to the `js_of_ocaml` developers for the nice ocaml to javascript compiler and a special shootout to Hugo Heuzard for not getting mad at me when pinging him directly for questions.
Happy browser compatibility bug hunting,
Daniel
---
### Author:  [@gasche](https://discuss.ocaml.org/u/gasche)
#### Post date: [October 14, 2020, 12:36pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/2 "2020-10-14T12:36:52Z")
It’s not really released, but I’m curious about [Note](https://erratique.ch/software/note) now: this is a new FRP library from you, the author of [React](https://erratique.ch/software/react) (the FRP library for OCaml, not the Javascript framework of the same name).
Would you say a few words on why you went for a different library? My guess would be that React depends on runtime mechanisms (weak pointers) that are not well-supported in Javascript-land; but even if the guess is right, I’m not sure what would be the impact on the API or properties of the library.
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [October 14, 2020, 1:20pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/3 "2020-10-14T13:20:35Z")
> [@gasche](#):
>
> Would you say a few words on why you went for a different library?
`Note` is the result from seeing people (and myself) struggling to use `React`/FRP “correctly” over the years.
Some of this, I largely attribute to ergonomic problems with the API. It’s my hope for `Note` to address most of these points (one thing that still needs to be done is replace fix points by a simple lazy infinitesimal delay combinator).
I don’t think I could have made all these changes in `React` itself so I found it better to start a new library. Also I lost the trademark on the name :–)
`Note` also tries to provide a much simpler implementation. `React`’s implementation was based on the [FrTime Phd thesis](http://cs.brown.edu/people/ghcooper/thesis.pdf). It’s quite subtle and involved and, as you suggested, uses weak pointer. `Note` tries to avoid them since those are not available in the browser (but you have things like [MutationObservers](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) which I use as gc in Brr’s Note-based [reactive dom support](https://erratique.ch/software/brr/doc/Brr_note/Elr/index.html)).
However not using weak pointers has a semantic uncleanness cost whose impact I’m unsure yet – without discipline from the programmer it may lead to subtle and hard to track bugs when the reactive graph changes dynamically, which I’m a bit wary of.
When my brain dumped `Note` I wrote a few more technical points in the readme you can read them [here](https://github.com/dbuenzli/note#history).
---
### Author:  [@aryx](https://discuss.ocaml.org/u/aryx)
#### Post date: [October 26, 2020, 12:01pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/4 "2020-10-26T12:01:55Z")
What are the differences with the default bindings provided in js\_of\_ocaml to the browser APIs (e.g., js.mli, dom.mli, etc.)?
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [October 26, 2020, 1:41pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/5 "2020-10-26T13:41:29Z")
I’m not sure exactly what you are asking but:
1. If you are asking about the way API are exposed: `brr` does not type JavaScript’s objects as phantom types. It simply relies on OCaml’s abstract data types and plain functions. More about this can be found in brr’s [FFI manual](https://erratique.ch/software/brr/doc/ffi_manual.html) and [FFI cookbook](https://erratique.ch/software/brr/doc/ffi_cookbook.html).
2. If you are asking about binding coverage, you should be able to get a sense of what is bound in `brr` [here](https://erratique.ch/software/brr/doc/index.html#supported_apis).
Regarding 2. `brr`'s coverage of more recent browser APIs is broader and more consistent than in `js_of_ocaml` – Promise support, Fetch, Service workers, Media capture APIs, WebGL2, Webcrypto, WebAudio, etc. Conversly older APIs supported in `js_of_ocaml` may not supported in `brr` (e.g. XMLHTTPRequest). Besides `brr`'s coverage of some of the DOM _element-specific_ interfaces may be shallower than in `js_of_ocaml`. There is however good coverage for the [`HTMLMediaElement`](https://erratique.ch/software/brr/doc/Brr_io/Media/index.html#el), [`HTMLCanvasElement`](https://erratique.ch/software/brr/doc/Brr_canvas/Canvas/index.html), [`HTMLFormElement`](https://erratique.ch/software/brr/doc/Brr_io/Form/index.html) and [`HTMLInputElement`](https://erratique.ch/software/brr/doc/Brr/El/index.html#ifaces) interfaces. For the rest the [attribute and property API](https://erratique.ch/software/brr/doc/Brr/El/index.html#ats_and_props) and the occasional trivial FFI method binding should be able to get you a long way.
---
### Author:  [@aryx](https://discuss.ocaml.org/u/aryx)
#### Post date: [October 28, 2020, 4:15pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/6 "2020-10-28T16:15:52Z")
In the doc at [https://erratique.ch/software/brr/doc/Brr\_note\_kit/Ui/index.html](https://erratique.ch/software/brr/doc/Brr_note_kit/Ui/index.html) I can see a nice application screenshot. Is there any chance the code of this app is available somewhere, as a way to learn how to code web apps using Brr\_note\_kit.
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [October 28, 2020, 5:04pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/7 "2020-10-28T17:04:27Z")
> [@aryx](#):
>
> I can see a nice application screenshot. Is there any chance the code of this app is available somewhere,
Unfortunately not, I made that for a client and it is closed source.
As I said in the original announce don’t pay too much attention to the `Note` based stuff for now, it needs a few more design iteration.
But on due time I might do a similar drawing app project as sample code, this used [`Vg`](https://erratique.ch/software/vg) for rendering and `Note` for input and the way everything composed and decomposed was quite encouraging.
---
### Author:  [@aryx](https://discuss.ocaml.org/u/aryx)
#### Post date: [October 28, 2020, 6:03pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/8 "2020-10-28T18:03:52Z")
That would be great! I’m a FRP newbie. I used to code lablgtk+cairo desktop app, but I’m curious how similar things could be better encoded with FRP using Brr and Canvas.
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [October 28, 2020, 10:31pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/9 "2020-10-28T22:31:24Z")
One thing I forgot, is that there is a [todomvc](http://todomvc.com/) example in the repo, see `todomvc.{html,ml}` in [this directory](https://github.com/dbuenzli/brr/tree/master/test).
It doesn’t use the UI toolkit you mentioned, just the basic reactive DOM support provided by [`Brr_note`](https://erratique.ch/software/brr/doc/Brr_note/index.html) and [`Brr_note_kit`](https://erratique.ch/software/brr/doc/Brr_note_kit/index.html). But you can see how quickly you get reusable and composable components like [`bool_editor`](https://github.com/dbuenzli/brr/blob/41580885f40bfd184c3d8e5be2ddd56b0712b411/test/todomvc.ml#L229) and [`string_editor`](https://github.com/dbuenzli/brr/blob/41580885f40bfd184c3d8e5be2ddd56b0712b411/test/todomvc.ml#L213-L214).
The program structure in that example is quite similar to the one I had in the drawing app. You define a purely functional, non reactive [data model](https://github.com/dbuenzli/brr/blob/41580885f40bfd184c3d8e5be2ddd56b0712b411/test/todomvc.ml#L36), [actions](https://github.com/dbuenzli/brr/blob/41580885f40bfd184c3d8e5be2ddd56b0712b411/test/todomvc.ml#L101) over the data model, create small UI fragments that renders parts of your data model and generate actions events for it, gradually glue them together using note combinators and finally define a [fixed point signal](https://github.com/dbuenzli/brr/blob/41580885f40bfd184c3d8e5be2ddd56b0712b411/test/todomvc.ml#L314-L324) that holds the data model as massaged by the actions events of your UI (as mentioned I’d like to replace fix points by direct `let rec` and a lazy infinitesimal delay combinator).
There are a few pitfalls like you should avoid retaining parts of your data model in the UI otherwise you could get outdated data come back in your model (makes for very fun and spooky bugs though). Identity in the data model is also a bit tricky, it seems in todomvc I [used](https://github.com/dbuenzli/brr/blob/41580885f40bfd184c3d8e5be2ddd56b0712b411/test/todomvc.ml#L84) `==`. That didn’t work in the drawing app where my surfaces had properties that could be updated but they could also be linked toghether (that window belongs to that wall etc.) so I needed stable identifiers for which I introduced a little abstraction to identify values and define relations between them.
One thing I remember fondly when doing the drawing app is that I would still get the odd interaction glitches you get when coding direct mouse manipulation interactions (surface definition/selection/move/transform) however thanks to the ability to denotationally reason and act (left leaning [`E.select`](https://erratique.ch/software/note/doc/Note/E/index.html#val-select)) on the simultaneity of events, they were easy to understand and fix in an explicit way (that is via a defining _expression_).
Also if you get into [`Note`](https://erratique.ch/software/note/doc/Note/) the denotational semantics notation is not yet explained there, refer to the [one of react](https://erratique.ch/software/react/doc/React/index.html#sem) it’s the same.
---
### Author:  [@aryx](https://discuss.ocaml.org/u/aryx)
#### Post date: [October 29, 2020, 9:23am UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/10 "2020-10-29T09:23:44Z")
How hard would it be to build on top of Brr\_note something like an Elm Architecture-style toolkit? I know there’s a TEA-Bucklescript library, but I’d rather use something relying on dune/jsoo.
I’ve read somewhere else that you were a bit skeptical about the advantage of MVU (movel-view-update) over MVC, but I personnaly find the counter UI example in ELM at
> **[Buttons · An Introduction to Elm](https://guide.elm-lang.org/architecture/buttons.html)**
far simpler than the corresponding one in Brr at
>
There’s no need for those E.select. The UI is IMHO more declarative in ELM.
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [October 29, 2020, 11:30am UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/11 "2020-10-29T11:30:25Z")
> [@aryx](#):
>
> How hard would it be to build on top of Brr\_note something like an Elm Architecture-style toolkit?
I don’t know. I didn’t look into MVU too much, but to me it’s largely a remix of MVC – despite what its proponents try to tell you. Since we now live in an age of software adverstising it’s a bit hard to get frank assessments.
As far as I’m concerned the compositionality story of MVU doesn’t look great. Basically it enforces state machines on you, and composing state machines is a bit meh. In FRP state machines become signals (via `S.accum`) which are highly composable entities with _fine granularity_ (and bonus point, a well defined denotational semantics for equational reasoning).
If you are looking for MVU I think you can simply jump on [LexiFI’s vdom](https://github.com/LexiFi/ocaml-vdom). But when I see how you get to [compose two models](https://github.com/LexiFi/ocaml-vdom/blob/9c5e42888ba72e69d5a018e38a4633e400913bfb/examples/demo/demo.ml#L196-L223) in that paradigm, I’m not convinced.
> [@aryx](#):
>
> There’s no need for those E.select. The UI is IMHO more declarative in ELM.
That example could be rewritten (I didn’t write the examples in this repo) to be more like the ELM one in it’s declarations.
But I think the ELM example is also more rigid. You may not like that `E.select` on this toy example, but you may get to enjoy it you when you start composing larger systems from smaller components.
---
### Author:  [@Yaron\_Minsky](https://discuss.ocaml.org/u/Yaron_Minsky)
#### Post date: [October 29, 2020, 11:11pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/12 "2020-10-29T23:11:27Z")
You might be interested in Bonsai! At some level, you can think of it as a library for building composable state machines. It uses [Incremental](https://github.com/janestreet/incremental) as its engine for incrementalizing the computation of views, with a virtual-dom implementation underneath.
> **[janestreet/bonsai](https://github.com/janestreet/bonsai)**
>
> A library for building dynamic webapps, using Js\_of\_ocaml - janestreet/bonsai
It’s the primary tool we use for building UIs inside of Jane Street.
In some ways, Bonsai is like Elm, but it has its own interesting ideas. Some of the concepts are borrowed from this paper:
> **[the-arrow-calculus.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/the-arrow-calculus.pdf)**
>
> 196.99 KB
though I won’t pretend to understand this paper myself!
Bonsai doesn’t yet have enough public-facing documentation, and really the bleeding edge version on github is considerably better and more usable than the one released into opam. But there’s at least one public-facing UI that’s built with it, if you want a real-world example.
> **[Finding memory leaks with Memtrace](https://blog.janestreet.com/finding-memory-leaks-with-memtrace/)**
>
> Memory issues can be hard to track down. A function that onlyallocates a few small objects can cause a space leak if it’s calledoften enough and those object...
---
### Author:  [@aryx](https://discuss.ocaml.org/u/aryx)
#### Post date: [October 30, 2020, 9:08am UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/13 "2020-10-30T09:08:59Z")
Thx for the links!
The memtrace viewer example is pretty cool, but Bonsai looks far more complicated than ELM.
If you look at the counter example (the hello world of UI), here:
>
and you compare it to the one in ocaml-vdom (thx @dbuenzli for the link) at [https://github.com/LexiFi/ocaml-vdom/blob/master/examples/counters/counters.ml](https://github.com/LexiFi/ocaml-vdom/blob/master/examples/counters/counters.ml)
there’s a huge difference in simplicity.
---
### Author:  [@aryx](https://discuss.ocaml.org/u/aryx)
#### Post date: [October 30, 2020, 9:53am UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/14 "2020-10-30T09:53:22Z")
BTW, is there something similar to ocaml-vdom but for programming desktop GUI? Something like a reactive lablgtk? With a MVU paradigm?
---
### Author:  [@TyOverby](https://discuss.ocaml.org/u/TyOverby)
#### Post date: [October 30, 2020, 11:59pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/15 "2020-10-30T23:59:48Z")
Hi Aryx, I wrote the Bonsai example that you linked, and it certainly isn’t the most concise, but that’s because it was built for a tutorial on building small components (one counter is a single component), how to use more advanced combinators (Bonsai.assoc), and how to move data from one component to another (the add\_counter\_component into the associated counters component.) I think it’s a great example of the power of structuring an UI as a DAG rather than a tree, but it definitely isn’t very small!
In the example, the comments that look like “CODE\_EXCERPT\_BEGIN” are actually preprocessor definitions that are used in the (honestly, kinda out of date) [tutorial here](https://github.com/janestreet/bonsai/blob/master/docs/getting_started/open_source/counters.mdx). A bonsai app implementing the same functionality (but that wasn’t written for such a tutorial) would look more like [this](https://gist.github.com/TyOverby/e0f7e944d002cdf7144aaf0102d16ed5).
---
### Author:  [@grayswandyr](https://discuss.ocaml.org/u/grayswandyr)
#### Post date: [November 5, 2020, 5:27pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/16 "2020-11-05T17:27:22Z")
> [@dbuenzli](#):
>
> One thing I forgot, is that there is a [todomvc](http://todomvc.com/) example in the repo, see `todomvc.{html,ml}` in [this directory](https://github.com/dbuenzli/brr/tree/master/test).
Much appreciated. Too often, tutorials are thought for people who already know modern web development with JS. I seem to remember you were also interested by Android apps as PWAs. Is it possible to use Brr in this setting? In that case, would you update your tutorial with this topic?
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [November 5, 2020, 8:12pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/17 "2020-11-05T20:12:39Z")
> [@grayswandyr](#):
>
> Is it possible to use Brr in this setting?
Brr is just a JavaScript FFI and bindings to browsers API and their documentation – and that’s what it intends to remain.
As a matter of fact you have the bindings to the APIs needed to make PWAs, I didn’t try do one so far but I might in the future; at which point more documentation might be generated.
---
### Author:  [@mudrz](https://discuss.ocaml.org/u/mudrz)
#### Post date: [November 10, 2020, 10:01am UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/18 "2020-11-10T10:01:10Z")
hey, I’ve been checking these different VDom implementations,
but what is the advantage of using Brr or JaneStreet’s Bonsai over something more popular like ReactJS? In terms of development experience ReactJS has a ton of documentation, benchmarks, cross-browser glue that handles edge cases, a dedicated team that works on it and a huge ecosystem and use in the industry -\> you are not likely to be the first encountering bugs;
what problems do other vdom libraries like Brr or Bonsai solve? Are they faster or easier to use or something else entirely?
thanks
---
### Author:  [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)
#### Post date: [November 10, 2020, 1:01pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/19 "2020-11-10T13:01:37Z")
> [@mudrz](#):
>
> but what is the advantage of using Brr or JaneStreet’s Bonsai over something more popular like ReactJS?
As mentioned in my previous message Brr is not a library to make user interfaces:
> [@dbuenzli](#):
>
> Brr is just a JavaScript FFI and bindings to browsers API and their documentation – and that’s what it intends to remain.
You could build one on top of it though.
---
### Author:  [@holmdunc](https://discuss.ocaml.org/u/holmdunc)
#### Post date: [December 21, 2020, 10:30pm UTC](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608/20 "2020-12-21T22:30:58Z")
Tried Brr recently in a miniature project and it was very pleasant to use. The most obvious win vs. standard Js\_of\_ocaml was that the basic types relating to JS interop were much more comprehensible (no super-long OO proxy signatures in editor hovers and compiler error messages!). The module factoring seems very thoughtfully done too.
I will look into using it more, particularly the HTML5 Canvas 2D functionality as an alternative to native code with SDL.
[Next page](https://discuss.ocaml.org/t/ann-brr-0-0-1-a-toolkit-for-programming-browsers/6608.md?page=2)