Reason to Use
- Entirely event driven, this is like React/Flow but type-safe and significantly faster.
- Amazingly fast compile-times, especially with the built-in watcher of Bucklescript.
- You have access to the highly optimized OCaml ecosystem if necessary.
- Open license, same as Bucklescript itself.
This is a library for OCaml-via-Bucklescript (though in the future to support native compilation for back-end template generation) that follows TEA/The Elm Architecture as I see it in various incarnations.
You can read more about it here.
Currently included and planned forms are:
- Elm API: Following the Elm API as closely as OCaml allows. Converting code back and forth between Elm and OCaml should be made as easy as possible and there exists both a converter, as well as documentation for that process. It may be good to 'version' the API, break it out from the latest Elm API to follow different versions of the Elm API behind versioned modules that can be easily opened. This is not done yet but is a 'nice-to-have' goal before hitting version 1.0.0 to ensure even better API stability. Currently the
updatecallback passes the
modelfirst instead of second as it makes matching on the message in a far more expected way, comments on reversing this back to Elm's way?
- WebComponent: TEA is a wonderful way to reason about information flow and view generation, however the implementation in Elm is very broken when wanting to combine it with WebComponents due to lacking a few ways to listen for data changes (which also fits very well into the TEA
updatemodel, just Elm has not done it as of the date of this writing). This may be an extension on the above Elm API however it is possible that it may require breaking away from that API.
- OCamlized-TEA: The Elm API is succinct, but highly inefficient in the amount of allocations it causes, though this is not necessary it would be nice to have a replacement API that takes effort to reduce the amount of allocations. Most real-world use would get near nothing out of this but for a few cases it would be quite useful to have an overhaul of the Virtual-DOM declaration style.
- React: It would also be nice to have a React back-end for easier integration with React projects, both into and out of this component. This should not have any breaking change over the Elm API but would just be an extension on it.
- Binding: Experiment with a method to build a vdom once then 'bind' to various parts of it. This will not follow TEA so precisely but the TEA style central event loop will still exist, this style will be quite different but may be even more simple while allowing even faster DOM diffing and updating.
With the above any PR's are welcome to clean up code, flesh out functionality, and until we hit 1.0.0 break API compatibility if necessary (but as minimally as possible). 1.0.0 should be complete when the Elm API style is followed as closely as possible and becomes as optimized as it can become while following the API, once that is set then API breaking changes will only happen to match Elm updates. PR's are also welcome to add support to other systems such as Yarn as long as it does not break the base NPM packaging system.
First verify you have
bs-platform installed, whether globally or just in your project.
Then install via npm by:
npm install --save-dev bucklescript-tea
Then in your current Bucklescript project just use this as a dependency add this to your bsconfig.json file:
"bs-dependencies" : ["bucklescript-tea"]
If you install it via any other method make sure that
bucklescript-tea is a dependency in your npm's package.json file as
bsb uses that for lookup.
Once you have your Bucklescript project set up and the dependencies configured as above then lets make a new TEA module, the Counter, as is traditional in Elm tutorials, this file will be named
counter.ml in your
src directory for this example. Code is described via inline comments:
var app = require("src/counter.ml").main(document.getElementById("my-element"));
And if you need to shut it down or pass it a message or so then you can do so via the
app variable, or feel free to not assign it to a variable as well.
For further examples see the bucklescript-testing project for now until a full example set up is built.
A list of starter-kits that get you up and running.
Feel free to extend this list!
This one is not so much a starter kit as it is a porting kit, it can actually take in elm files, parse them, and output bucklescript-tea OCaml code (which can be converted to ReasonML via
refmt of course) with only minor'ish tweaks there-after needed to get it working.
See its announcement article at: https://medium.com/@paulbiggar/philip2-an-elm-to-reasonml-compiler-a210aaa6cd04
And its porting guide at: https://github.com/darklang/philip2#how-to-port-your-project