master
Branches
Tags
Go to file
Code
Open more actions menu
Folders and files
Name
Name
Last commit message
Last commit date
Latest commit
History
148 Commits
148 Commits
balance_list_tree
balance_list_tree
bench_scenario
bench_scenario
bonsai_kernel_components
bonsai_kernel_components
docs/
assets
docs/
assets
ppx_bonsai
ppx_bonsai
src
src
trampoline
trampoline
.gitignore
.gitignore
.ocamlformat
.ocamlformat
CHANGES.md
CHANGES.md
CONTRIBUTING.md
CONTRIBUTING.md
LICENSE.md
LICENSE.md
Makefile
Makefile
README.md
README.md
bonsai.opam
bonsai.opam
changelog.md
changelog.md
dune-project
dune-project
View all files
Repository files navigation
README
Contributing
MIT license
More
items
Bonsai
Bonsai
Bonsai is a UI library for building performant, reactive web applications in OCaml, partly
inspired by
Elm
. It is used to build almost all web applications
inside Jane Street, everything from the corporate directory to tools that monitor and
interact with our trading systems. A simple Bonsai component with a little interactivity
looks like this:
module
Dice
=
struct
let
faces
=
[
”
⚀
”
;
”
⚁
”
;
”
⚂
”
;
”
⚃
”
;
”
⚄
”
;
”
⚅
”
]
;;
let
component
(
graph
@
local
)
=
(*
Components are implemented as purely functional state machines.
*)
let
face, set_face
=
Bonsai.
state (
List.
hd_exn faces) graph
in
(*
Components are incrementally rendered, only when the relevant parts of the state change.
*)
let
%
arr face
and
set_face
in
{%html|
|
}
;;
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.
Why Bonsai?
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.
Expressive tests that save you from manually clicking through your app
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
{
|
hello
|
}];
Handle.
input_text handle
~get_vdom:
Fn.
id
~selector:
”
input
”
~text:
”
Bob
”
;
Handle.
show_diff handle;
[
%
expect
{
|
–
hello
+
hello
Bob
|
}];
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.
Documentation
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.
Bonsai is really a collection of libraries
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:
General-purpose libraries
Bonsai
is a library for building incremental,
composable state machines.
Testing
Browser-based UI Libraries
Bonsai_web
is a library for building
interactive browser-based UI using
bonsai
.
Examples
Components
Testing
Benchmarking
Terminal-based UI Libraries
Bonsai_term
is a library for building
interactive terminal-based UIs using
bonsai
.
Examples
Components
Testing
Pre-processors
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.
About
A library for building dynamic webapps, using Js_of_ocaml
Resources
Readme
MIT license
Contributing
Contributing
Activity
Custom properties
Stars
869
stars
Watchers
21
watching
Forks
50
forks
Report repository
Releases
Packages
Used by
Contributors
Languages