Bonsai: Jane Street's Incremental UI Library for OCaml

Overview

Bonsai is a UI library designed for building performant, reactive web applications using OCaml and Js_of_ocaml. Developed by Jane Street, it is used for the majority of the firm's internal web applications, ranging from corporate directories to trading system monitoring tools. Unlike traditional frameworks that bundle state, incrementality, and rendering into a single "component" abstraction, Bonsai treats these as separate, composable primitives.

Core Architecture and State Management

Bonsai implements UI components as purely functional state machines. This architecture allows for high composability and precise control over how data flows through the application.

Incremental Rendering

Bonsai uses incrementalization to ensure that values—including the view—are only recomputed when their relevant dependencies change. This prevents the framework from re-rendering the entire page during user interactions, applying the same optimization to expensive business logic computations on live datasets as it does to the UI.

Decoupled State

Because state is not strictly tied to the component hierarchy, Bonsai provides an extensive API for managing state lifecycle and scoping. This eliminates the need for "state hoisting," where internal component state must be manually moved to a top-level model to be shared or managed by a parent component. For example, stateful UI components embedded within a tabbed interface are handled automatically by the framework.

Language Integration and Ecosystem

By leveraging OCaml, Bonsai enables developers to share the same language and type definitions across both the backend and frontend. This unification reduces errors and simplifies the process of porting existing business logic from terminal-based systems to the web.

The Bonsai Library Suite

Bonsai is not a single library but a collection of specialized tools:

  • Bonsai (Core): A general-purpose library for building incremental, composable state machines.
  • Bonsai_web: Specializes the core library for interactive browser-based UIs.
  • Bonsai_term: Adapts the core library for interactive terminal-based UIs (TUI).
  • Bonsai_test: Provides tools for testing state machines.

Pre-processors

To streamline development, Bonsai web applications typically utilize two pre-processors:

  • ppx_html: A pre-processor for writing HTML, similar in syntax to JSX.
  • ppx_css: A pre-processor for writing CSS.

Testing Framework

Bonsai includes a system for automated, expressive tests that allow developers to programmatically manipulate UI elements and observe DOM evolution without a browser. These tests can include mock server calls and assertions on both the UI and the underlying state.

Tests are written using expect blocks, which allow for multiple assertions within a single scenario. Developers can use Handle.show_diff to see exactly how HTML attributes or class names change in response to specific user inputs.

Community Insights and Perspectives

Discussion among developers highlights a tension between Bonsai's technical rigor and its visual presentation. While some praise its utility and information density, others criticize its aesthetics.

Performance vs. Aesthetics

Some users note that the library prioritizes function over form, with one observer stating:

It focuses on utility and information density over design. It looks like someone took a terminal UI and transplanted it to the web, Bloomberg terminal style.

Conversely, other critics argue that the UI elements appear "unpolished" and reminiscent of 1990s software.

Technical Trade-offs

Developers have raised questions regarding the ecosystem trade-offs of using Bonsai, specifically the potential loss of access to the vast JavaScript ecosystem (e.g., React, GraphQL). There is also a technical note regarding the lack of tail call optimization in Js_of_ocaml, which necessitates the use of a userland trampoline.

Sources