Hello and welcome to this introductory tutorial to the ReasonML language. This is a chance to get familiar with a newer and exciting language in the compile to Javascript world. Now you may be thinking "wait, another language that compiles to Javascript? Don't we already have Elm? CoffeeScript? PureScript? TypeScript? ES8 Babel? and on and on ad nauseum? Sure we do, however it's worth noting that ReasonML does bring its own unique features to the table to help it stand out from the crowd.

What is ReasonML?

So what is ReasonML exactly? Well as we already mentioned it is a compile to Javascript language, however it can also be used to compile to OCaml's native assembly as well. This is significant because this language is largely based off of OCaml. You could even argue that ReasonML is 80% OCaml with some modern Javascript syntax thrown in to enhance the stylistic properties of the language while also enabling an easier transition for developers who are primarily familiar with Javascript.

That being said, ReasonML is statically typed. While there is some data type inference in this language, it is primarily focused on your defining the data types throughout in the same way you would have in C or C++. ReasonML is also made to be type safe which can be a giant relief for many developers.

We also have numerous unique data structures that are pulled straight from OCaml that should enable some powerful functional capabilities. Many of these data structures are immutable by default which is especially useful if you are programming in a functional style. That being said, if you are needing to move in an imperative or object oriented direction, ReasonML does give some ways out to avoid too much inconvenience.

This moves us to our next language feature. ReasonML is primarily geared as a functional programming language which brings all the perks that come with it. The immutable data structures, first class functions, functional iteration methods specific to the different data structures, it's all there. However ReasonML does include some object oriented features to make it friendly to other programming needs.

Another feature that comes with ReasonML is its Javascript interop scheme through Bucklescript. While we won't yet be focusing on Bucklescript, it is definitely worth checking into as it can allow you to have a means to directly drop working Javascript code in to your reason code. Not only that, but it can allow you to use your ReasonML code to interact directly with that Javascript code, even from within the same file.

Lastly it is also worth noting that ReasonML was designed by the same individual who also created React. Yes, the UI library for Javascript. On top of that, ReasonML is made to be particularly good for building user interfaces in React through a companion library called React-Reason. For those who may be wondering, yes, ReasonML does bring a very high level of support for JSX.

Installation and Configuration

Now with all this being said, it's time to switch gears and move towards installing and configuring our systems to run ReasonML. First let's handle the installation through NPM. I already have it installed on my system so I will give you the terminal command for you to work with.

npm install -g reason-cli@3.1.0-darwin

That was easy. However, for some people, NPM or Yarn may not be an option. So we will also look at another way via OPAM which is the native package manager for OCaml. This is useful if you are coming from programming in OCaml and you just can't be bothered with installing Node and NPM. Bare in mind however that there are bugs to this approach if you are using Windows.

opam update
eval $(opam config env)
opam install reason.3.0.4 merlin.2.5.4

Now for our next step we need to configure an editor to work well with ReasonML. Depending on your editor of choice this can get more challenging than usual as ReasonML has a its own unique system of linters such as refmt (Reason Format) and Merlin which acts as the engine handling linting, refactoring, real time errors, etc.

So to get things moving in this tutorial, we will use the editor which is recommended to be the easiest to get configured and up and running with ReasonML and that is Visual Studio Code. If you absolutely do not wish to use this editor, a link will be provided below with the guides to get your specific editor set up to work with ReasonML.

Now let's open up Visual Studio Code and get Reason configured.

video showing ReasonML setup

Not bad, some others will be more challenging but now we should be ready to go.


It's time to switch gears again briefly to talk about the ReasonML ecosystem. We have already touched on Bucklescript and its interop functionalities. It brings a lot to the table. Alongside the drop in Javascript code, we also get seriously fast compilation times and a means for interacting directly with the DOM when writing for client side development. It also makes it possible to import Javascript libraries for use with ReasonML. However, that being said, if we're honest, the manual Bucklescript approach for importing Javascript libraries isn't really the most elegant solution. Thankfully, the ReasonML ecosystem has an alternative.

The key thing is, many Javascript libraries have already been ported to work with ReasonML and all we really need to do is just download and use the ported version. There also many libraries unique specifically to ReasonML that we would like to get access to and that is where Redex comes in. Redex is the central home for all the ReasonML libraries. There you will find many adaptations for React, Express, Web API, WebSockets, file system interaction, etc.


Excellent, we now have an idea of what ReasonML is and what it has to offer, plus we have installed and configured ReasonML to our systems and we're ready to begin learning the fundamentals of the ReasonML language.

Helpful Links