janestreet/bonsai: A library for building dynamic webapps, using Js_of_ocaml · GitHub

You rolled a #
<button
style=““ on_click=%
>
Roll the dice
</button>
</div>
|}
;;
end

Most internal Jane Street web applications are built with Bonsai

Components are implemented as purely functional state machines, and are easily
composable. Incrementalization inside the framework means that values don’t get recomputed
until necessary. This applies to every value, not just the view.

Other web frameworks tend to lump together state, incrementality, and rendering into a
single abstraction, the UI component. By contrast, Bonsai allows you to compose state and
incrementality primitives a la carte. The same primitives that prevent re-rendering the
entire page during user interaction can also be used to incrementalize an expensive
business logic computation on a live-updating dataset. (If you’re used to React, imagine
if everything used something very similar to hooks, and state was managed outside of the
component hierarchy.)

Since state is not associated with explicit components, there is an extensive API for
managing the lifecycle and scoping of state as users interact with the page. For instance,
if you wanted to embed a collection of stateful UI components inside another UI component
(in a tabbed interface, say), Bonsai will handle the state management for you instead of
requiring that you manually hoist every internal component’s state to the app’s top-level
model. For more examples of how state is composed, see this composition comparison
written by the creator of Bonsai.

And because Bonsai is written in OCaml, it becomes possible to use the same language and
types on both the backend and frontend. It’s hard to overstate the impact this has on
legibility and keeping a large web app’s codebase manageable, especially when you make
pervasive use of OCaml’s type system to reduce errors. At Jane Street, many internal
systems previously only had terminal UIs, and the framework has made it easy to port the
existing types and business logic to the web.

Bonsai also comes with a powerful templating language, support for component-specific
stylesheets, and a system for whole-app automated tests.

One of Bonsai’s most powerful features is its ability to let you easily write realistic
tests, in which you programatically manipulate UI elements and watch your DOM evolve.

In the following example, we’re testing the behavior of a user-selector. Whatever you type
in the text box gets appended to a little “hello” message:

let%expect_test "shows hello to a specified user" =
  let handle = Handle.create (Result_spec.vdom Fn.id) hello_textbox in
  Handle.show handle;
  [%expect
    🔥];
  Handle.input_text handle ~get_vdom:Fn.id ~selector:"input" ~text:"Bob";
  Handle.show_diff handle;
  [%expect
    ];

Notice that there are two expect
blocks. (This allows you to make
multiple assertions within a given scenario and to scope setup/helper code to just that
scenario.)

The first makes our UI visible, and the second—which contains a diff—shows some
behavior after you programatically input some text. Bonsai will even show you how html
attributes or class names change in response to user input. Tests can include mock server
calls, and can involve changes not just to the UI but to the state that drives it. With
tests like these you can write an entire component without opening your browser.

The Bonsai
Quick Start and Thinking in Bonsai
provide a hands on introduction to Bonsai and are the best places to start learning
about it. There’s also:

• A series of how-to
  articles.
• A short series of posts about Bonsai’s
  history.
• An episode of our Signals &
  Threads podcast about “Building a UI Framework.” Another
  episode on “Building Tools
  for Traders” discussed some of the benefits of using Bonsai.
• A library filled with example websites
  built with Bonsai.
• API documentation can be found in the
  cont.mli
  file.

Er, one wrinkle: Bonsai itself — this library — is actually more generic than the above
makes it sound. It allows you to build general-purpose incremental, composable state
machines. Bonsai_web builds on top of that
core library, specializing it for interactive browser-based UIs, but we also have
Bonsai_term for building interactive
terminal-based UIs. There was even a prototype for April Fools’ Day of Bonsai_vr for
reactive virtual-reality UIs.

The full suite of Bonsai libraries:

Bonsai is a library for building incremental,
composable state machines.

Bonsai_web is a library for building
interactive browser-based UI using bonsai.

Bonsai_term is a library for building
interactive terminal-based UIs using bonsai.

Bonsai web applications often use the following preprocessors:

• ppx_html is a preprocessor for writing HTML
  that is similar to JSX.
• ppx_css is a preprocessor for writing CSS.