Forem: Techway

Build a type safe React App with ReasonML, Part 1

Theofanis Despoudis — Fri, 27 Mar 2020 17:18:07 +0000

I wanted to showcase a real world project using ReasonML which is an ecosystem of tools and libraries for developing type safe code using OCaml in the Browser. My aim is to help you see that there are not many differences between ReasonML and plain Javascript as the type system is smart enough to perform type inference without being too explicit.

In this example two-part series we’ll create a sample e-commerce app like the one shown in the inspired article above.

Let's get started:

Building a type-safe ReasonML app

We need to get started working with a ReasonML by configuring our project first.

First install the bsb-platform which is the ReasonML compiler tooling:

$ npm install -g bs-platform

Next create a new ReasonML project using the React Hooks theme which will setup the necessary boilerplate project for us:

$ bsb -init reason-example -theme react-hooks

The default boilerplate maybe not familiar for us. I recommend doing the following changes:

Remove the following files:

indexProduction.html
watcher.js
UNUSED_webpack.config.js

Change the index.html like this:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>ReasonReact Examples</title>
</head>
<body>
  <div id="root"></div>
  <script src="Index.js"></script>
</body>
</html>

Create a new webpack.config.js file with the following content:

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const outputDir = path.join(__dirname, 'build/');

const isProd = process.env.NODE_ENV === 'production';

module.exports = {
  entry: './src/Index.bs.js',
  mode: isProd ? 'production' : 'development',
  output: {
    path: outputDir,
    filename: 'Index.js'
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: 'index.html',
      inject: false
    })
  ],
  devServer: {
    compress: true,
    contentBase: outputDir,
    port: process.env.PORT || 8000,
    historyApiFallback: true
  }
};

Change the bsconfig.json file like this:

{
  "name": "reason-react-example",
  "reason": {
    "react-jsx": 3
  },
  "sources": [{
    "dir" : "src",
    "subdirs" : true
  }],
  "bsc-flags": ["-bs-super-errors", "-bs-no-version-header"],
  "package-specs": [{
    "module": "commonjs",
    "in-source": true
  }],
  "suffix": ".bs.js",
  "namespace": true,
  "bs-dependencies": [
    "reason-react"
  ],
  "bs-dev-dependencies": ["@glennsl/bs-jest"],
  "refmt": 3,
  "gentypeconfig": {
    "language": "typescript",
    "module": "es6",
    "importPath": "relative",
    "debug": {
      "all": false,
      "basic": false
    }
  }
}

Create a babel.config.js file with the following contents:

module.exports = {
  env: {
    test: {
      plugins: ["transform-es2015-modules-commonjs"]
    }
  }
};

Update the package.json so that it has the following contents:

{
  "name": "reason-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "bsb -make-world",
    "start": "bsb -make-world -w",
    "clean": "bsb -clean-world",
    "webpack": "webpack -w",
    "webpack:production": "NODE_ENV=production webpack",
    "server": "webpack-dev-server"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "babel-plugin-transform-es2015-modules-commonjs": "^6.26.2",
    "bs-platform": "^7.2.2",
    "gentype": "^3.15.0",
    "webpack-cli": "^3.3.11"
  },
  "dependencies": {
    "@glennsl/bs-jest": "^0.5.0",
    "bs-fetch": "^0.5.2",
    "html-webpack-plugin": "^3.2.0",
    "react": "^16.13.0",
    "react-dom": "^16.13.0",
    "reason-react": "^0.7.0",
    "webpack": "^4.42.0",
    "webpack-dev-server": "^3.10.3"
  },
  "jest": {
    "transformIgnorePatterns": [
      "/node_modules/(?!@glennsl/bs-jest|bs-platform).+\\.js$"
    ]
  }
}

Finally install the npm dependencies:

$ npm i

If you want to test the application now you need to run the dev server and the bsb compiler in two tabs:

$ npm run start
// In another tab
$ npm run server

However for the example you should delete all the examples inside the src folder and keep an Index.re file with the following example code:

ReactDOMRe.renderToElementWithId(<App />, "root");

This is similar to React's ReactDOM.render method but a little bit more convenient.

Create a new file named App.re in the same folder and add the following code:

[@react.component]
let make = () => {
  <main> {"Hello From ReasonML" |> React.string} </main>;
};

Let's explain here some conventions:

We use the [@react.component] annotation to specify that it's a react component
We name a let binding as make so that by default ReasonReact will discover it
We use regular JSX but when we want to display a string we need to pipe it to the appropriate type. In that case |> React.string.

Every-time you change anything in the code it will reload and see the changes to the UI.

Routing

ReasonReact comes with a router! Let's add the first route to match the home page:

Create a new file named Routes.re and add the following code:

[@react.component]
let make = () => {
  let url = ReasonReactRouter.useUrl();

  switch (url.path) {
  | [] => <Home />
  | _ => <NotFound />
  };
};

This will match either the base path / rendering the Home component or anything else rendering the NotFound component.

Create the following components:

Home.re

[@react.component]
let make = () => {
  <main> {"Hello World  " |> React.string} </main>;
};

NotFound.re

[@react.component]
let make = () => {
  <main> {"404 Page not found!" |> React.string} </main>;
};

Finally update the App component to render the Routes instead:

App.re

[@react.component]
let make = () => {
  <Routes />;
};

Now you know how to handle routing.

Styles and images

We can add stylesheets and images using regular require imports. We just need to define some external helpers that will map from ReasonML to Javascript.

Create a new file named Helpers.re and add the following code:

/* require css file */
[@bs.val] external requireCSS: string => unit = "require";

/* require an asset (eg. an image) and return exported string value (image URI) */
[@bs.val] external requireImage: string => string = "require";

So whenever we want to include css files we use it like:

requireCSS('./styles.css');

and this will compile as:

require('./styles.css');

Let's add styles for the NotFound page:

NotFound.css

.NotFound {
    margin: 30px auto;
    display: flex;
    align-items: center;
    flex-direction: column;
}
.NotFound--image {
    margin-top: 60px;
}

Change the NotFound.re component to import the styles:

open Helpers;

requireCSS("./NotFound.css");

let notFoundImage = requireImage("./notFound.png");

[@react.component]
let make = () => {
  <main className="NotFound">
    <div className="NotFound--Image">
      <img src=notFoundImage alt="Not Found Image" />
    </div>
  </main>;
};

Finally you need to install the webpack dependencies and update the webpack.config:

$ npm i style-loader css-loader file-loader --save-dev

webpack.config.js

...
module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          esModule: false,
        },
      },
      {
        test: /\.css$/,
        use: [
          {
            loader: 'style-loader'
          },
          {
            loader: 'css-loader',
            options: {
              sourceMap: true
            }
          }
        ]
      },
    ]

You need to find a notFound.png image and place it inside the src folder. Once you run the application again you can see the not found page:

Modelling the Domain problem

We have two important domains in the wireframe, inventory and cart:

We will create the application store and structure it based on the domain.

Let’s start with the inventory domain.

Inventory domain

ReasonReact has full support for React Hooks!. We can use reducers, effects, state, context variables to handle our application state. Let's start by defining our model types for the inventory domain based on the class diagram above.

Create a new file named InventoryData.re and add the following code:

type inventory = {
  id: string,
  name: string,
  price: int,
  image: string,
  description: string,
  brand: option(string),
  stockCount: int,
};

type action =
  | Fetch
  | FetchSuccess(list(inventory))
  | FetchError(string);

type state = {
  isLoading: bool,
  data: list(inventory),
  error: option(string),
};

let initialState = {isLoading: false, data: [], error: None};

The above code contains state, action types, and inventory domain mode
A few notes about the code above:

The inventory type determines the specified domain data
The actions variant determines the action types
The state handles the type of domain state. We also define an initialState

Now, it’s time to create an action for fetching the inventory store. Create a new file named InventoryActions.re with the following contents:

let fetchInventory = dispatch => {
  dispatch(InventoryData.Fetch);
  InventoryApi.fetch(payload =>
    dispatch(InventoryData.FetchSuccess(payload))
  )
  |> ignore;
};

The InventoryApi.re file contains the following content:

let fetch = callback => {
  callback(MockData.inventory);
};

Finally the MockData.re file is just a hardcoded list of inventory items:

open InventoryData;

let inventory = [
  {
    name: "Timber Gray Sofa",
    price: 1000,
    image: "../images/products/couch1.png",
    description: "This is a Test Description",
    brand: Some("Jason Bourne"),
    stockCount: 4,
    id: "fb94f208-6d34-425f-a3f8-e5b87794aef1",
  },
  {
    name: "Carmel Brown Sofa",
    price: 1000,
    image: "../images/products/couch5.png",
    description: "This is a test description",
    brand: Some("Jason Bourne"),
    stockCount: 2,
    id: "4c95788a-1fa2-4f5c-ab97-7a98c1862584",
  },
...

The final part of the inventory store is the reducer. Let's create that file:

InventoryReducer.re

open InventoryData;

let reducer: (state, action) => state =
  (state, action) =>
    switch (action) {
    | Fetch => {...state, isLoading: true}
    | FetchSuccess(data) => {...state, isLoading: false, data}
    | FetchError(error) => {...state, isLoading: false, error: Some(error)}
    };

Here we included the InventoryData module so that the types are inferred without prefixing the module name. Note that we can ignore the type definition of the reducer without losing type checking. ReasonML is always on guard if something goes wrong with the types!.

Cart domain

It’s time to implement the types and actions for the cart model. The functionalities of the cart domain are similar to those of the inventory domain.

First, create a file named CartData.re and add the following code:

open InventoryData;

type cart = {
  id: string,
  items: list(inventory),
};

type action =
  | AddToCart(inventory)
  | RemoveFromCart(inventory)
  | Fetch
  | FetchSuccess(option(cart))
  | FetchError(string);

type state = {
  isLoading: bool,
  data: cart,
  error: option(string),
};

let initialState = {isLoading: false, data: {id: "1", items: []}, error: None};

This represents the cart domain attributes, cart action types, and cart state.

Next, create CartActions.re for the cart domain:

let fetchCart = dispatch => {
  dispatch(CartData.Fetch);
  CartApi.fetch(payload => dispatch(CartData.FetchSuccess(payload)))
  |> ignore;
};

let addToCart = (inventory, dispatch) => {
  dispatch(CartData.AddToCart(inventory)) |> ignore;
};

Where CartApi.re is:

let fetch = callback => {
  callback(MockData.cart);
};

Finally, write the code for the cart domain reducer. Create a file, name it CartReducer.re, and add the following code:

open CartData;

let reducer: (CartData.state, CartData.action) => CartData.state =
  (state, action) =>
    switch (action) {
    | Fetch => {...state, isLoading: true}
    | FetchSuccess(data) => {...state, isLoading: false, data}
    | FetchError(error) => {...state, isLoading: false, error: Some(error)}
    | AddToCart(inventory) =>
      let updatedInventory = [inventory, ...state.data.items];
      {
        ...state,
        isLoading: true,
        data: {
          id: state.data.id,
          items: updatedInventory,
        },
      };
    | RemoveFromCart(inventory) =>
      let updatedInventory =
        List.filter(
          (item: InventoryData.inventory) => item.id != inventory.id,
          state.data.items,
        );
      {
        ...state,
        isLoading: true,
        data: {
          id: state.data.id,
          items: updatedInventory,
        },
      };
    };

Next Part

We will continue in the next and final part of this tutorial by defining the view components and glue everything together.

30 minute introduction to ReasonML for React Developers

Theofanis Despoudis — Mon, 23 Mar 2020 12:48:06 +0000

The next level of React Development is with ReasonML. It allows existing Javascript developers to write OCaml code. The major benefits here are type safe inference (much more pleasant and advanced than Typescript) and really fast compilation times (orders of magnitude faster than Typescript). Not to mention is also very fun to work with.

In this article we'll try to go through as many ReasonML snippets as we can, and explain what the keywords and symbols they contain mean.

Let's get started...

Variable Bindings

let introduces variable bindings. This works the same as const in Javascript:

let greeting = "Hello World"

let bindings are immutable, thus they cannot change after the first assignment:

let greeting = "Hello World"
greeting = "Hello Again"
^^^^^^^^
Error

The let assignment should be done immediately as the compiler needs to infer the type:

let greeting
greeting = "Hello Again"
^^^^^^^^
Error

However, using a ref with a wrapped value passed though allows us to assign a new value later on:

let greeting = ref("")
greeting = "Hello World"

You can create new scopes using braces {} and then assign the result to a binding. Everything you bind inside the scope is not available outside. The last expression evaluated is returned as the result. This is very useful for logical grouping of expressions and for better readability:

let fullName = {
  let first = "Theo";
  let last = "Despouds";
  first ++ " " ++ last
};
"Theo Despoudis"

You can bind new values to existing variables. The value of the last binding is what is referred in subsequent calculations:

let a = 10.;
let a = 11;
let a = a * a; // 121

Type Inference

When we use let without specifying the type, the compiler will infer it:

let a = 10.; // float
let a = 10; // int
let a = "abc"; // string
let a = 'a' // char

If we want to be more explicit about the type we can declare it:

let a: float = 10.;
let a: int = 10;
let a: string = "abc";
let a: char = 'a';

You can assign a different name to a type using type aliases:

type statusCode = int
let notFound: statusCode = 404;

Note that a type name must start with a lower-case letter or an underscore. The following will fail:

type StatusCode = int
     ^^^^^^^^^^
let notFound: StatusCode = 404;

The type system of ReasonML is completely "sound" compared to Typescript which is not. See this article for more information.

Strings

Strings are wrapped in double quotes. Characters are wrapped in single quotes. Strings can span multiple lines:

"aaa";
"bbb;
bbb";
'a';

Strings are unicode encoded but chars are not. They are just ASCII so anything other than ASCII throws an error:

"α" // Greek letter alpha

'α';
^^^

Booleans

true and false represent the bool type. All relevant operations that we use in Javascript work the same in ReasonML:

true && false;
true || true;
1 < 2;
2 >= 3;
2 == 2;
3 === 3;

There are no binary or xor operators. The following would not work:

true | true;
false & true;
true ^ true;

Numbers

There are two types of numbers. Integers and floats. Float numbers end with a dot . whereas ints do not.

We use standard operators for integers such as +, -, * and /.

We use different operators for floats such as +., -., *. and /..

1 + 10; // 11
1. +. 10.; // 11.

10. *. 5.; // 50.

We cannot mix operations between types. The following expressions will fail:

1 +. 10 // +. works on floats only
1. + 10; // + works on ints only

Lists and Arrays

Lists and Arrays are collections of similar items. Lists are immutable and the notation is the same as Javascript:

let groceryList = ["eggs", "pasta", "milk"];

You cannot mix types:

let ids = [1,2, "3"];
                ^^^

The type of list is list(<type>) for example list(int) or list(string).

There are not list methods available so you cannot do ids.length. Instead you need to use the List module methods, for example:

let ids: list(int) = [1, 2, 3];
List.length(ids); // 3
let ids = List.append(ids, [4]); // [1, 2, 3, 4]

You can also use the spread(...) operator once to prepend items:

let ids: list(int) = [1, 2, 3];
let ids = [0, ...ids];

Note that appending does not work. You need to use List.concat for anything else:

let ids = [...ids, 4];
           ^^^^^^

To access a list index you need to use List.nth using 0-based indexing:

let ids: list(int) = [1, 2, 3];
let first = List.nth(ids, 0); // 1

Arrays are mutable collections of similar items. We surround them with [| and |] and we can use standard index notation for access:

let ids: array(int) = [|1, 2, 3|];
let first = ids[0]; // 1
ids[0] = 4;
// ids = [|4, 2, 3 |]

Conditional Expressions

if and else are expressions (they return a value) so we can assign them to let bindings. For example:

let ids: array(int) = [|1, 2, 3|];

let safeFirst = if (Array.length(ids) > 0) {
    ids[0]
} else {
    0
}
// safeFirst = 1

You cannot have a naked if expression without an else one:

let ids: array(int) = [|1, 2, 3|];

let safeFirst = if (Array.length(ids) > 0) {
    ids[0]
}^^^^^^^^^^^^^

There is also a ternary operator just like Javascript:

let isLoading = false;
let text = isLoading ? "Loading" : "Submit";

Records

Records in ReasonML are like Objects in Javascript. However they have stronger type guarantees and are immutable:

type user = {
  name: string,
  email: string
};
// Type inference here. This will only work in the same file that the user type is defined.
let theo = {
  name: "Theo",
  email: "theo@example.com"
}

Note that you cannot just define an object without a type:

let theo = {
  name: "Theo",
  ^^^^
  email: "theo@example.com"
}

To use a Record defined in a different file you need to prefix the type. For example if we defined the user model in Models.re:

let theo: Models.user = {
  name: "Theo",
  email: "theo@example.com"
};

Records are immutable:

type user = {
  name: string,
  email: string
};
let theo = {
  name: "Theo",
  email: "theo@example.com"
}

theo.name = "Alex"
^^^^^^^^^^^^^^^^^^

But you can create another Record using the spread operator:

type user = {
  name: string,
  email: string
};
let theo = {
  name: "Theo",
  email: "theo@example.com"
}

let theo = {
  ...theo,
  name: "Alex"
}
// {name: "Alex", email: "theo@example.com"}

Alternatively you can mark a field as mutable and perform updates:

type user = {
  mutable name: string,
  email: string
};
let theo = {
  name: "Theo",
  email: "theo@example.com"
}

theo.name = "Alex"
// {name: "Alex", email: "theo@example.com"}

You can combine different types inside a Record type using type shorthands:

type email = string;
type username = string;

type user = {
  email,
  username
}

Functions

Functions are like es6 lambda expressions. We use parenthesis and an arrow and return a value:

let addOne = (n) => n + 1;
addOne(2); // 3

If the function spans multiple lines we can use a block scope:


let getMessage = (name) => {
  let message = "Hello " ++ name;
  message
}
getMessage("Theo"); // "Hello Theo"

By default, function arguments are positional and the order matters. We have the option to use named (or labeled) arguments (similar to Python) using the tilde (~) operator.

let getMessage = (~greeting, ~name) => {
  let message = greeting ++ " " ++ name;
  message
}
getMessage(~name="Hello", ~greeting="Theo"); // "Theo Hello"

However once we use one named argument we have to use all of them and not skip anything:

let getMessage = (~greeting, ~name) => {
  let message = greeting ++ " " ++ name;
  message
}
getMessage(~name="Hello", "Theo");
                          ^^^^^^

Any function with more than one argument is automatically carried:

let mul = (a, b) => a * b;
let times2 = mul(2);
let result = times2(3); // 6

Recursive functions are declared via the rec keyword:

let rec fact (n) {
  if (n === 0) {
    1
  } else {
    fact(n-1) * n
  }
}

fact(5); // 120

Nulls, Optionals and Undefined

There is no null or undefined in ReasonML. Instead we have the Option Monad which represent either a value - Some(value) or no value at all - None:

let userName = Some("Alex");
let userName = None;
let userName: option(string) = Some("Alex");

You can use the Belt.Option module to perform common operations for Optionals:

let userName = Some("Theo");
print_string(string_of_bool(Belt.Option.isSome(userName))); // true
Belt.Option.isNone(userName); // false

To check is some object is null or undefined (coming from a network response for example) you can use the following API methods:

Js.Nullable.isNullable();
Js.eqNull();
Js.eqUndefined();

Tuples

Tuples are like lists but they can contain different types of items. For example:

let pair = (1, "Theo Despoudis");
let pair : (int, string) = (1, "Theo Despoudis");

As with lists we cannot use the indexing operator [index]. Instead we need to use destructing to extract the i'th element. This makes tuples useful only when there are small in sized (< 3 elements):

let triplet = (1, "Theo Despoudis", "theo@example.com");
let (_, name, _) = triplet;  // use _ for ignoring the extracted value
name // "Theo Despoudis"

Type Variants

Variants are like Union Types in Typescript. It allows us the describe an OR (|) relationship between two or more types:

type status =
  | NotFound
  | Error
  | Success;

let responseStatus = Error;

You can also pass the types of the arguments in some or all of the Type Names of the variant types:

type animalType =
  | Dog(string)
  | Cat(string)
  | Bird;

let myDog = Dog("Wallace");

You cannot use plain types as variants as they need to be Unique tag names or Types with a Constructor:

type number = int | float;
                  ^^^^^^^^

Destructuring

We have seen destructuring before. When we have a tuple or a Record we can extract some or all of their fields to a binding:

type user = {id: int, name: string, email: string};
let me = {id: 1, name: "Theo", email: "theo@example.com"};
let {name, email} = me;

The above is just a syntactic sugar for:

let name = "Theo";
let email = "theo@example.com"

Pattern Matching

Pattern matching is the golden fleece of Functional Programming languages. Essentially they are switch statements on steroids. For example:

type result =
  | OK(string)
  | NotOK(string)
  | Empty;

let response = OK("Success!");

let log =
  switch (response) {
  | OK(message) => "OK:" ++ message
  | NotOK(message) => "Error: " ++ message
  | Empty => "Nothing happened!"
  };

log // OK:Success

Pipes

Pipes act as syntactic shorthand for function composition. If you have 3 functions f, g, h and you want to call them like f(g(h(a))) you can instead use pipes to call them like:

a
 ->h
 ->g
 ->f

For example:

let userName = Some("Theo");
print_string(string_of_bool(Belt.Option.isSome(userName)));

// or

userName
    -> Belt.Option.isSome
    -> string_of_bool
    -> print_string

Modules

Modules are like namespaces. We use blocks {} to define a module name where we can associate similar types or bindings. This aims to improve the code organisation:

module Arena = {
  type warriorKind =
    | Gladiator(string)
    | Hoplite(string)
    | Archer(string);

  let getName = (warriorKind) =>
    switch (warriorKind) {
    | Gladiator(name) => name
    | Hoplite(name) => name
    | Archer(name) => name
    };
};

Then when we need to reference a module in another file we use the module name:

let warrior: Arena.warriorKind = Arena.Gladiator("Brutus");
print_endline(Arena.getName(warrior)); // "Brutus"

For convenience we can use a shorthand for the module name using the open keyword ideally within it's own block scope:

let event = {
  open Arena;
  let warrior: warriorKind = Gladiator("Brutus");
  print_endline(getName(warrior)); // "Brutus"
};

Promises

Using the Js.Promise https://bucklescript.github.io/bucklescript/api/Js.Promise.html) module we can create or interact with promise objects:

let messagePromise =
  Js.Promise.make((~resolve, ~reject) => resolve(. "Hello"))
  |> Js.Promise.then_(value => {
       Js.log(value);
       Js.Promise.resolve("World");
     })
  |> Js.Promise.catch(err => {
       Js.log2("Failure!!", err);
       Js.Promise.resolve("Error");
     });

Note that we prepended a dot . or the uncurry annotation before calling resolve as the compiler will complain. This is because we want the callbacks to be uncurried.

The above will compile to the following Javascript code:

var messagePromise = new Promise((function (resolve, reject) {
            return resolve("Hello");
          })).then((function (value) {
          console.log(value);
          return Promise.resolve("World");
        })).catch((function (err) {
        console.log("Failure!!", err);
        return Promise.resolve("Error");
      }));

That's it

There are more little things to know about ReasonML but in this tutorial we explored the most common ones. Here are some further reference links for learning more about the ReasonML ecosystem: