Home

Awesome

Bucklescript-TEA

NPM

Build Status

Reason to Use

Description

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:

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.

Installation

NPM

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.

Usage

Example project

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:

(* This line opens the Tea.App modules into the current scope for Program access functions and types *)
open Tea.App

(* This opens the Elm-style virtual-dom functions and types into the current scope *)
open Tea.Html

(* Let's create a new type here to be our main message type that is passed around *)
type msg =
  | Increment  (* This will be our message to increment the counter *)
  | Decrement  (* This will be our message to decrement the counter *)
  | Reset      (* This will be our message to reset the counter to 0 *)
  | Set of int (* This will be our message to set the counter to a specific value *)
  [@@bs.deriving {accessors}] (* This is a nice quality-of-life addon from Bucklescript, it will generate function names for each constructor name, optional, but nice to cut down on code, this is unused in this example but good to have regardless *)

(* This is optional for such a simple example, but it is good to have an `init` function to define your initial model default values, the model for Counter is just an integer *)
let init () = 4

(* This is the central message handler, it takes the model as the first argument *)
let update model = function (* These should be simple enough to be self-explanatory, mutate the model based on the message, easy to read and follow *)
  | Increment -> model + 1
  | Decrement -> model - 1
  | Reset -> 0
  | Set v -> v

(* This is just a helper function for the view, a simple function that returns a button based on some argument *)
let view_button title msg =
  button
    [ onClick msg
    ]
    [ text title
    ]

(* This is the main callback to generate the virtual-dom.
  This returns a virtual-dom node that becomes the view, only changes from call-to-call are set on the real DOM for efficiency, this is also only called once per frame even with many messages sent in within that frame, otherwise does nothing *)
let view model =
  div
    []
    [ span
        [ style "text-weight" "bold" ]
        [ text (string_of_int model) ]
    ; br []
    ; view_button "Increment" Increment
    ; br []
    ; view_button "Decrement" Decrement
    ; br []
    ; view_button "Set to 42" (Set 42)
    ; br []
    ; if model <> 0 then view_button "Reset" Reset else noNode
    ]

(* This is the main function, it can be named anything you want but `main` is traditional.
  The Program returned here has a set of callbacks that can easily be called from
  Bucklescript or from javascript for running this main attached to an element,
  or even to pass a message into the event loop.  You can even expose the
  constructors to the messages to javascript via the above [@@bs.deriving {accessors}]
  attribute on the `msg` type or manually, that way even javascript can use it safely. *)
let main =
  beginnerProgram { (* The beginnerProgram just takes a set model state and the update and view functions *)
    model = init (); (* Since model is a set value here, we call our init function to generate that value *)
    update;
    view;
  }

If anything is typed wrong than the OCaml type checker will catch it and advise. Compilation times are wonderfully fast, probably faster than about any other compile-to-javascript language that you will come across.

To use this from javascript (with your bundler of choice) you can just do:

  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.

Starter-Kits

A list of starter-kits that get you up and running.

Feel free to extend this list!

tcoopman/bucklescript-tea-starter-kit

feluxe/bs-tea-starter-kit

darklang/philip2

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

tcoopman/dream-melange-tea-tailwind

This example works with melange and adds tailwindcss