Here are some reflections on my path to creating a first ReasonReact application.

  1. ReasonReact is still React

    ReasonReact’s API stays as close as possible to React. As you know, ReasonML is a syntax and build chain for OCaml, but it compiles to JavaScript (and React.js).

    You can use your previous knowledge of building React applications. However, ReasonReact ships with the underlying assumptions of React and React hooks: one-way data binding, handling derived state or synchronizing state, the complexities of life-cycle management, useEffect, etc.

  2. Steep Learning Curve for JavaScript developers

    If you’re only used to dynamically typed languages, then the learning curve is hard. If you’re used to working in an object-oriented-fashion, then it’s hard, too.
    OCaml is a functional programming language that is strongly statically typed.

    Playing fast and loose with dynamic JavaScript objects won’t work. Mutating objects left and right won’t work.

    As a JavaScript developer, you’ve learned a lot of patterns that Reason won’t allow.

    It also takes a while to get the hang of the type system and you will encounter a lot of type errors at first.
    The compiler errors might be friendly but can still seem cryptic to a beginner.

  3. Documentation

    The documentation is sorely lacking.
    First, it’s spread across different resources: the ReasonML docs, the BuckleScript docs, the OCaml docs.
    Some of the documentation gives a hint of the type signature, some sparse explanation, but no examples. That’s not beginner-friendly.

    Another example: there are several container types you can use. Let’s take an array, for example. There is the ReasonML Array, but also a BuckleScript Array type - and a native JS Array, too.
    That’s confusing.

    Working with ReasonReact is quite frustrating. There are not even examples for all the hooks. I can understand that the developers reference the React documentation for hooks for the underlying principles. But you don’t get code examples for how the syntax works with ReasonReact.

    When I tried to use useRef, I had to search the forums, GitHub, etc., to get an example.

    There is a recent initiative to improve documentation, so I hope that the situation will improve.

  4. Community

    The community on Discord is extremely welcoming and active. Every time I posted a problem or asked for, I got help shortly afterward (mostly within the hour).
    The tone is friendly.
    The community is quite small compared to others (Elixir, TypeScript/JavaScript).

  5. JavaScript and package management

    Package management and tooling work nicely, as you can rely on npm and webpack. Spinning up a React app only takes seconds. Reason integrates well into the JavaScript ecosystem.

    With Vim, you’ll get adequate editor support via language server plugin.

    Using “native JavaScript” within a Reason file proves to be trickier. There are existing bindings to JavaScript libraries, but many are missing. That means you’ll have to write bindings. That’s very intimidating.
    I haven’t understood how that works yet and got away with googling so far.

  6. ReasonML is fun

    After the initial hurdle, I quite enjoy ReasonML.
    Pattern-matching and variant types are such powerful language features that make development such a joy.
    Creating a mental model by defining types helps reason about a program.
    The syntax is close to JavaScript and thus feels familiar. Thanks to language server protocol, I can rely on my editor to fix my formatting errors.
    The compiler is blazingly fast, and type inference works like magic.

    ReasonML feels like TypeScript on steroids: better type system, faster, with immutable data structures - but much harder to learn.