DEV Community: Josh Derocher-Vlk

Rescript is truly a game changer for web development. Types are great, but types shine when you can rely on a sound type system, typed errors, and easy to use variant types.

Josh Derocher-Vlk — Sun, 12 Oct 2025 23:16:43 +0000

Cristian Sifuentes

Oct 9 '25

ReScript 2025 — The Top JavaScript Alternative (Tech Deep Dive)

#rescript #javascript #typescript #webdev

Comments 4

4 min read

ReScript has come a long way, maybe it's time to switch from TypeScript?

Josh Derocher-Vlk — Tue, 28 May 2024 14:49:42 +0000

ReScript, the "Fast, Simple, Fully Typed JavaScript from the Future", has been around for awhile now. The name "ReScript" came into existence in 2020, but the project has a history going back to 2016 under the combo of Reason and BuckleScript. The name change came about as the goal of BuckleScript shifted to try and create a language that was a part of the JavaScript ecosystem; JavaScript is the only build target, support for all of the features JavaScript devs expect to have like async/await syntax, and an easy to use standard library for JavaScript's built in functions.

Since the re-brand to ReScript the team behind the project have been very busy. If you look around the internet to see what people have to say about ReScript there are some things that people didn't like or JavaScript features that were missing. Many of these have been addressed, so lets take a look at some of these complaints and features that have been recently addressed. Hopefully you'll give ReScript another look as a strong alternative to TypeScript

My sources of past issues

To create this list of issues I have poured over the official ReScript forum, Hacker News, Reddit, and Twitter. I tried not to omit anything and I wasn't just looking for issues that have been solved. I'll call out anything that hasn't changed that might still be a pain point for some people, but hopefully you'll see the massive steps forward the language has taken in the past 4 years.

I have to understand Reason, BuckleScript, and OCaml before I can use ReScript

You don't need to know anything about Reason, BuckleScript or OCaml to use ReScript.

ReScript's history comes from these languages and tools, but today it's very much it's own thing that works with the standard JS ecosystem of NPM, PNPM, Yarn, or whatever package manager you want to use. The JS it spits out can be used by any build tool like Vite, ESBuild, Webpack, etc... ReScript is fully part of the JS ecosystem and you don't need to know any other languages, new build tools, or new package managers.

Ocaml is still a wonderful language if you want to look into it, and Reason is still going strong as an alternate syntax for OCaml. With either OCaml or Reason you can compile to native code, or use the continuation of BuckleScript now called Melange.

Should I use Belt.Array, Js.Array, or Js.Array2?

Due to ReScript's history being rooted in Ocaml and Reason, it came with some baggage from those languages. Not bad baggage, but Ocaml isn't JavaScript and had it's own patterns and ways of doing things that made sense for that language. Trying to match these patterns to JavaScript was cumbersome when the goal of Reason was to compile to native code or JavaScript while maintaining full interop with OCaml. ReScript now focuses only on the land of JavaScript, so it has a new Core library that is meant to be easy to pick up and understand. The previous standard Js library is being deprecated and will soon be removed from the language, and Belt will evolve into a more fully featured utility library like Lodash that will be optional to use.

The answer to the above question is to just use Array.



let t = [1, 2, 3]->Array.map(n => n + 1)

Core is a separate library for now, but the roadmap is to include it in the language directly before the end of the year.

Lack of async, await, and Promises are cumbersome

Native support for async/await syntax was added in ReScript 10.1 in Early 2023. The new Core library I mentioned above also introduced a streamlined way to work with Promises.



// async/await
let fn = async () => {
  try {
    let result = await getData()
    Console.log(result)
  } catch {
  | err => Console.error(err)
  }
}

// Promises
let fn = () => {
  getData()
  ->Promise.thenResolve(result => Console.log(result))
  ->Promise.catch(err => {
    Console.error(err)
    Promise.resolve()
  })
}

Lack of community types

When ReScript was young you would have to write your own bindings and types for most existing JS libraries before you could use them. There are now hundreds of NPM packages that have bindings and documentation on how to use your favorite JS libraries with ReScript. Bindings exist for React (which also still has first class support directly in the ReScript compiler), Node, Jotai, React Query, React Hook Form, AntD, Material UI, Bun, Vitest, Graphqljs and many others!

There are even some incredible ReScript first libraries out there that really shine and can take advantage of ReScript powerful type system and compiler, like rescript-relay.



/* Avatar.res */
module UserFragment = %relay(`
  fragment Avatar_user on User {
    firstName
    lastName
    avatarUrl
  }
`)

@react.component
let make = (~user) => {
  // this is fully typed!
  let userData = UserFragment.use(user)

  <img
    className="avatar"
    src=userData.avatarUrl
    alt={
      userData.firstName ++ " "
      userData.lastName
    }
  />
}

ReScript also has amazing tooling for parsing JSON into types. Here's an example of rescript-schema:



@schema

type cat = {

  name: string,

  color: string,

}

let _ =

  %raw({ name: 'fluffy', color: 'orange' })

  ->S.parseWith(catSchema) // catSchema is generated automatically!

  ->Console.log

I don't understand how to use existing JavaScript libraries

While there is a growing number of community bindings and libraries written in ReScript, at some point you'll need to dig into writing your own bindings. Thankfully, the documentation is excellent and you can reference one of the many existing NPM packages for ideas.

Just this week I needed to use a function from path-to-regexp and it took me just a few minutes to create bindings and the function I needed.



type t = string => option<{.}>

type m = {

    path: string,

    params: {.}, // this means any object

  }

@unboxed // @unboxed is a way to have a variant type that compiles to simple javascript without a runtime object

  type isMatch =

    | Yes(option<m>) // the JS for this is just an object of type m

    | @as(false) No // the JS for this is just 'false'

type match = string => isMatch

@module("path-to-regexp") // this is the actual binding using the types I made above

  external match: string => match = "match"

let make = url => {

    let fn = match(url) // and now I can call it!

    path =>

      switch fn(path) {

      | Yes(t) => t->Option.map(t => t.params)

      | No => None

      }

  }

I can't have 2 files with the same name?

This hasn't changed, and due to the way the module system works it never will. It might feel weird at first for JS devs, but this isn't that weird in other languages. You get used to it very quickly.

Why would I pick this over TypeScript?

I have another article that dives into this: Tired of Typescript? Check out ReScript!

The short answer is that you would pick ReScript if:

You want a strong, sound type system (no any types!)
You want types, but you don't want to write type annotations (the compiler just knows!)
You want only the "Good Parts" of JavaScript
You want a blazing fast compiler and fast Intellisense in VSCode, even when your repo is massive
You want amazing next gen language features like pattern matching, Option and Result types, and powerful variant types.

Not convinced?

Leave a comment! I'm more than happy to discuss things in more detail and answer questions about ReScript! I've been using it for a few projects over the past 4 years, and it's hard to switch back to writing TypeScript when I need to. It's been incredible to watch the language grow and evolve and it should be considered as an alternative to TypeScript.

Cover Photo by Patrick Tomasso on Unsplash

Tired of Typescript? Check out ReScript!

Josh Derocher-Vlk — Fri, 19 Apr 2024 15:10:12 +0000

If you've spent any amount of time developing with JavaScript you have probably found it difficult to maintain a large code base and avoid runtime errors. The language wasn't designed to do all of the things we use it for today. We've been trying to improve our experience with the language by using tools like ESLint to improve and enforce a shared code quality with our teams. One of the largest shifts in the JavaScript world has been the adoption of TypeScript, which adds a nice layer of types on top of JavaScript. It has done a fantastic job assisting with code maintainability in large JavaScript projects.

However, TypeScript is not without its flaws. It can be slow to compile and show type hints in your IDE, the types require a lot of annotation and can create too much noise around simple code, the type system has unsafe escape hatches like any that reduce our level of trust in the types, and since it's a superset of JavaScript it brings along all of JavaScript's warts and footguns. These issues have led some people to drop TypeScript in favor of using JSDoc with types or even dropping types all together.

Instead of moving back to un-typed JavaScript, perhaps there is another solution?

ReScript

ReScript is a fully typed language with an easy to understand JS like syntax, blazing fast compiler, that compiles to JavaScript. You can easily drop it into an existing project, and there is even a way to generate TypeScript types if you want to add it to a TypeScript project!

While ReScript and TypeScript fill a similar role of improving JavaScript development with types they have different goals and ways of achieving those goals. TypeScript is a superset of JS, which means all valid JS is valid TS and that TypeScript's type system has to be able to add types to anything JavaScript can do. ReScript is a different language with a JS like syntax, so it doesn't have to try and add types to JavaScript code. It's built for types.

Less type annotations

TypeScript requires you to add type annotations to your code in order for the compiler to understand what you are trying to do.



function add(a: number, b: number) {
  return a + b
}

Thankfully it can usually infer the return type. If I omitted the types here I would get an error:



function add(a, b) /* Parameter 'a' implicitly has an 'any' type.ts(7006) */ {
  return a + b
}

ReScript can infer the types based on how you use the values, and when I say infer I don't mean "guess", the type is guaranteed to be correct.



let add = (a, b) => a + b // fully typed!

Here's a slightly larger example:



type person = {name: string}

let greet = person => `Hello ${person.name}`

let bill = {
  name: "bill",
}

let main = () => greet(bill)

That is all fully typed. ReScript knows that greet takes in a person since it accesses name. It knows that bill is a person because it's a record with a name field. So I can call greet with bill. You can take a look at this code with type hints on hover on the ReScript playground.

Here's how we can do the same in TypeScript:



type Person = { name: string }

const greet = (person: Person) => `Hello ${person.name}`

const bill = {
  name: 'bill'
}

const main = () => greet(bill)

It's not much more in this example, but it starts to add up quickly as code gets more complex.

Another cool example is that this also works for React component props (ReScript has first class support for React and JSX!).



@jsx.component
let make = (~name) => <p> {React.string(`Hello ${name}!`)} </p>

It knows that name is a string! Here's the equivalent in TypeScript:



type Props = { name: string }

const Greeting = ({ name }: Props) => `Hello ${name}`

My favorite part of this it not having to remember the correct type for every event handler in React.



@jsx.component
let make = (~handleClick) =>
  <button onClick=handleClick> {React.string("Click me!")} </button>

Removing the need for explicit type definitions allows me to move quicker, and it allows me to add new props easily. You don't have to think about types unless you are defining a shape of data. The types are there acting as a strong guiding hand, but you don't need to tell ReScript what type is which, it just does that for you. Of course, you can always add type annotations if you would like.



let add = (a: int, b: int): int => a + b

Better type system

ReScript has a "sound" type system. In a nutshell this means that if the compiler assigns type a to something we know it has to be type a. I found this conversation around the topic helpful.

How does that help us as developers?

If we see a function that returns a string can know without a doubt that it will return a string.

Doesn't TypeScript do this? It can as long as everyone plays the game correctly, but it's very easy to trick or lie to TypeScript, or to just incorrectly assign something that has an any type.



const t1 = 42 as unknown as string

// @ts-ignore
const t2: string = 42

const fn = (): any => 42

const t3: string = fn()

const t4: any = 42

const t5 = t4 as string

If you saw some of these pop up in a code review you would hopefully demand changes, but it's easy in real world code to let this type of error bleed out into the wild.



type person = {
  name: string,
  age: number
}

function parse(t: string): person {
  return JSON.parse(t)
}

const t1 = parse('{"color": "blue"}')

I have seen something like this in real code, and it led to bugs. ReScript won't allow you to do this, you will have to parse the JSON with a library like rescript-schema (it's like Zod).

ReScript doesn't have an any type. Everything has to have some sort of type, and I can't tell the compiler to ignore the next line or force it to assign a type to a value that is incorrect.

Having a type system you can trust helps you write code with confidence.

Faster compile times

TypeScript can slow down if you have a large enough code base. I've worked on projects with upwards of 150k lines of TypeScript and VSCode would crash frequently and often fail to show type hints on hover.

Your mileage may vary, but here are some numbers from projects I have been working on recently. In a project with almost 32k TypeScript files it takes me 2 minutes to run full type checking. When running tsc in watch mode it takes 4-10 seconds to type check after saving a file.

A ReScript app with 50k files can run full type checking with no cache in 1 minute. After a cache is made this takes no time if nothing has changed, or milliseconds if you have changed things. With all 50k files being watched it takes 338 milliseconds for ReScript to type check and compile after saving a file.

Even with 50k files VSCode intellisense picks up on every module with auto complete without any lag.

When using ReScript, you also don't need tools like ESLint or Prettier. The compiler enforces good practices and it has a built in formatter.

Working on a large project with snappy intellisense and a quick feedback loop is amazing. ReScript doesn't slow down local development when your project grows, and even full builds scale well and can still run full type-checking in half the time it takes TypeScript.

The good parts of JS and more!

ReScript has all of the good parts of JS that we like using such as await/async, object and array spreading, destructuring, and it also has new features like pattern matching, variant types, and Option and Result types that should feel familiar to developers familiar with Rust, Elm, or OCaml.

You can read more about these features in my other posts:

ReScript: Rust like features for JavaScript

Josh Derocher-Vlk — Thu, 18 Jan 2024 18:48:55 +0000

If Rust is "C++ in ML clothing" then ReScript is "JavaScript in ML clothing".

What is ReScript?

ReScript is "Fast, Simple, Fully Typed JavaScript from the Future". What that means is that ReScript has a lightning fast compiler, an easy to learn JS like syntax, strong static types, with amazing features like pattern matching and variant types. Until 2020 it was called "BuckleScript" and is closely related to ReasonML.

ReScript is growing and adding features to make it more appealing as an alternative to JavaScript. ReScript v11 was recently released and adds some very nice quality of life improvements.

Let's take a quick look at a few features that Rust and ReScript share with some code examples.

Types

Rust and ReScript are both strong, statically-typed languages with roots in OCaml. Everything has a type and that type is guaranteed to be correct. Unlike TypeScript you won't find the any type in ReScript.

ReScript relies heavily on type inference which helps remove some clutter from type annotations.

// Typescript
let add = (a, b) => a + b // infers (any, any) => any

// ReScript
let add = (a, b) => a + b // infers (int, int) => int

You can add type annotations if you would like.

// ReScript
let add = (a: int, b: int): int => a + b

Expression based

Rust and ReScript are expression based languages, which means most lines of code or blocks of code return a value. You also don't have to write an explicit return for an expression, the last value in a block is the value returned.

// rust
fn main() {
    let y = {
        let x = 3;
        x + 1
    };

    println!("The value of y is: {y}"); // the value of y is: 4
}

// rescript
let main = () => {
  let y = {
    let x = 3
    x + 1
  }

  Console.log(`The value of y is: ${y->Int.toString}`) // the value of y is: 4
}

Pattern Matching

Pattern matching is a powerful way to do something conditionally based on types or data. You can think of it as a super powered switch statement that can match on the type or the value of the data. Rust and ReScript will give you a compiler error if you fail to handle all possible cases, which makes refactoring much easier to handle. If you ever have to add a new case you'll know exactly where to go in the code to make sure you handle it correctly.

// Rust
fn main() {
    let n = 42;

    match n {
        10 => println!("The number ten."),
        42 => println!("Answer to the Ultimate Question of Life, the Universe, and Everything."),
        _ => println!("Some other number."),
    }
}

// rescript
let main = () => {
  let x = 42
  switch x {
  | 10 => Console.log("The number ten.")
  | 42 =>
    Console.log(
      "Answer to the Ultimate Question of Life, the Universe, and Everything.",
    )
  | _ => Console.log("Some other number.")
  }
}

Tagged Unions and Variant types

Rust's tagged unions and ReScript variant types give you a way to not only create a type, but to also give that type data. This can be combined with pattern matching to make sure you handle all possible cases.

This article I wrote shows how you can use ReScript's variant types to connect business logic to the compiler.

// Rust
enum Widget {
    Red(u8),
    Blue(u8),
    None,
}

fn main() {
    let x = Widget::Red(42);

    match x {
        Widget::Red(_) => println!("You have a red widget!"),
        Widget::Blue(_) => println!("You have a blue widget!"),
        Widget::None => println!("You have no widget!"),
    }
}

// ReScript
type widget =
  | Red(int)
  | Blue(int)
  | None

let main = () => {
  let x = Red(42)

  switch x {
  | Red(_) => Console.log("You have a red widget!")
  | Blue(_) => Console.log("You have a blue widget!")
  | None => Console.log("You have no widget!")
  }
}

`Option` instead of `undefined` or `null`

Not having to deal with null or undefined errors saves so much time and prevents errors and headaches in production. Option forces you to explicitly deal with anything that might not be defined and having it typed this way makes it clear when you expect something to be undefined.

// Rust
fn main() {
    let n = Some("Josh");

    match n {
        Some(name) => println!("Hello there {:?}!", name),
        None => println!("Who are you?")
    }
}

// rescript
let main = () => {
  let n = Some("Josh")

  switch n {
  | Some(name) => Console.log(`Hello there ${name}!`)
  | None => Console.log("Who are you?")
  }
}

`Result` instead of throwing errors

Both languages have the Result type which can represent a response from an expression that might have failed. It's useful to handle expected errors without blowing up the program. Expected errors could be things like an api timing out, or a 400 response for a bad request. It allows the program to track information about an error and handle it gracefully without throwing an exception.

// rust
fn main() {
    let n: Result<&str, &str> = Ok("Josh");

    match n {
        Ok(name) => println!("Hello there {:?}!", name),
        Err(err) => println!("Error: {:?}", err),
    }
}

// rescript
let main = () => {
  let n: result<string, string> = Ok("Josh")

  switch n {
  | Ok(name) => Console.log(`Hello there ${name}`)
  | Error(err) => Console.log(`Error: ${err}`)
  }
}

Learn more about ReScript

If you are interested in learning more about ReScript check out the official site or come over to the forum!

Using variant types in ReScript to represent business logic

Josh Derocher-Vlk — Sun, 15 Oct 2023 11:32:03 +0000

Types can be great at creating documentation to know what parameters are used in function, what a function returns, and to stop us from accidentally omitting required object keys.

In TypeScript most of the types we use daily are primitive types like string or number. We also uses types (or interfaces) to structure an object correctly like type Person = { name?: string, last?: string }. It gives all the developers working on a project a shared understanding of what a Person is and what values it requires and which values are optional. The TypeScript compiler helps us write code that adheres to this shared understanding.

In ReScript we gain access to something that TypeScript doesn't have, variant types. A variant allows us to represent data as "this or that", and each variation can contain unique information. Combine this with ReScript's pattern matching and you have a powerful tool to represent business logic with types.

The feature we have to build

We have an ask from our product team to greet customers who visit a new landing page. The greeting we show will be different depending on what we know about the customer.

If we don't know the customer's name we want to show "Hello stranger!"
If we only know their first name we want to show "Hi FIRST_NAME!"
If we only know their last name we want to show "Hello to the LAST_NAME family!"
If we know the first and last name we want to show "Hello FIRST_NAME LAST_NAME"

Building it in TypeScript

Before we dig into how variant types and pattern matching can make this easy let's take a look at how you would implement this in TypeScript.

Here's how we represent our person in TypeScript:



type Person = {
  name?: {
    first?: string
    last?: string
  }
}

And here's the code to handle our greeting logic:



function greet(person: Person) {
  if (person.name && person.name.last && person.name.first) {
    // first and last name
    return `Hello ${person.name.first} ${person.name.last}!`
  } else if (person.name && person.name.last) {
    // last name only
    return `Hello to the ${person.name.last} family!`
  } else if (person.name && person.name.first) {
    // first name only
    return `Hi ${person.name.first}!`
  } else {
    // no name
    return "Hello stranger!"
  }
}

This meets our requirements and it works as expected, but it can be a little confusing to read even with a few comments. This solution also isn't portable since we have to check for each value like this any time we want to do something with the person's name.

Building it in ReScript

With variant types we can take a step back and change how we represent our data. In our TypeScript example we created a base Person type that shows exactly the keys it could have and what types those values are. It doesn't tell us anything about why this type matters to our application or business logic. The type and the logic are different things that are defined in different places.

Types with logic

Based on the requirements we have for the feature we can create a variant type that will represent each possible state.



type person =
  | NoName
  | FirstName(string)
  | LastName(string)
  | FirstAndLastName(string, string)

We then use pattern matching to handle each possibility:



let greet = person =>
  switch person {
  | FirstAndLastName(first, last) => `Hello ${first} ${last}!`
  | FirstName(first) => `Hi ${first}`
  | LastName(last) => `Hello to the ${last} family!`
  | NoName => "Hello stranger!"
  }

Even without comments or an understanding of anything about our requirements it's fairly easy to grok what's going on here.

You can see this example in the ReScript Playground.

ReScript's compiler will also warn us about missing cases.

Why would I do this?

Variant types add meaning to our data

When you have a lot of developers working on features and functionality it's easy to lose track of the expected business logic as an application grows. A type that is a simple object doesn't carry any meaning with it and it's left up to every developer to handle how to read that data and to implement the required logic for every feature. You also need to know about that logic if you are trying to read these if/else statements to understand what is going on.

Variant types solve this by allowing us to represent our data in a way that carries meaning.

Adding new cases is easy

A few months go by and we need to add support for greeting a person when we only know the city they live in.

We have to add a new case to our variant and rename NoName to NoInfo.



type person =
  | NoInfo
  | FirstName(string)
  | LastName(string)
  | FirstAndLastName(string, string)
  | City(string)

The compiler will error out on NoName and we can quickly fix that. It will then warn us about the missing case so we can go ahead and add that in. Adding { city?: string } to our TypeScript example doesn't do anything to show us where that code is used or where we need to handle this new requirement.

Wrapping up

Using variant types to represent our data allows us to quickly add or change business logic with confidence. The compiler will warn us for missing cases, and will guide us to places that need to change if we remove or rename an existing case.

This is an excellent talk on domain modelling with types by Scott Wlaschin. He's using F# so it's slightly different, but F# and ReScript have a common ancestor in OCaml so the concepts apply to both all similar ML family languages.

If you interested in learning more about ReScript take a look at these other articles I have written.

How to set up a React app using ReScript, Vite, and Tailwind for lightning fast development.

Josh Derocher-Vlk ・ Sep 24 '23

#rescript #react #vite #tailwindcss

Converting a JavaScript React app to a ReScript React app.

Josh Derocher-Vlk ・ Sep 27 '23

#rescript #react #webdev #typescript

Converting a JavaScript React app to a ReScript React app.

Josh Derocher-Vlk — Wed, 27 Sep 2023 18:46:47 +0000

ReScript is "Fast, Simple, Fully Typed JavaScript from the Future". Let's take a look at how we can add it to an existing React project.

Our project

This simple counter app is one of the examples you can find in the React docs.

How does ReScript work with JavaScript?

ReScript can be dropped into an existing JS app and is a part of the JS toolchain and ecosystem. It doesn't have a different package manager so you can use NPM, Yarn, or PNPM (even Bun!).

You just install it with npm i rescript.

Getting started

We'll clone the repo, open up VSCode, and install the ReScript extension so we have syntax highlighting and code completion.

Now we can install our ReScript dependencies:



npm i rescript @rescript/react @rescript/core

rescript: The language compiler
@rescript/react: ReScript bindings to React and support for JSX
@rescript/core: The ReScript standard library

Note: this repo is a bit older and still uses React 16. We'll need to update this to React 18 so we can use the latest version of @rescript/react. We could make it work with React 16, but I think upgrading can be part of our refactoring.

Set up our ReScript config file, bsconfig.json.



{
    "name": "rescript-counter-app",
    "sources": [
        {
            "dir": "src",
            "subdirs": true
        }
    ],
    "package-specs": [
        {
            "module": "es6",
            "in-source": true
        }
    ],
    "suffix": ".bs.js",
    "bs-dependencies": [
        "@rescript/core",
        "@rescript/react"
    ],
    "bsc-flags": [
        "-open RescriptCore"
    ],
    "jsx": {
        "version": 4,
        "mode": "automatic"
    }
}

Note: ReScript used to be known as Bucklescript, so you will see some references to bs scattered around for now.

Let's add a couple scripts to run ReScript:



// package.json
"scripts": {
  ...
  "res:dev": "rescript build -w",
  "res:build": "rescript"
}

Here's a PR for the initial setup: https://github.com/jderochervlk/rescript-counter-app/pull/1

Where to start?

Let's first try and get the app running for local development.



npm run start

I have an issue with the older version of react-scripts. Updating to v5 fixes it and the app is running!

I'll open up a new terminal tab and run npm run res:dev to kick off the ReScript compiler in watch mode.

With a TypeScript app we would be doing this conversion from a "breadth" first approach by changing all of the .js files to .ts files, leaving strict mode off, and slowly fix all of the any types and turn strict mode on. ReScript has a "depth" first approach where we will tackle one file at a time. We have to have all of the types in that file correct before we can compile and move onto the next file. It's usually easiest to do this by starting at the bottom of the code like small components or util functions.

The NavBar component looks like a good place to start.

Navbar

Here's the starting code:



import React from "react";

// Stateless Functional Component

const NavBar = ({ totalCounters }) => {
  return (
    <nav className="navbar navbar-light">
      <div className="navbar-brand">
        <i className="fa fa-shopping-cart fa-lg m-2" aria-hidden="true" />
        <span
          className="badge badge-pill badge-info m-2"
          style={{ width: 50, fontSize: "24px" }}
        >
          {totalCounters}
        </span>
        Items
      </div>
    </nav>
  );
};

export default NavBar;

It's a stateless functional component, so this should be really easy. I'm going to rename it to .res and work through the compiler errors.

There are no imports in ReScript, every file has a module based on the filename. This means we can get rid of import React from "react";. We also delete the export.
there isn't const in ReScript. Everything, including functions, uses let binding. So we can change the const to let.
we will change the name of the NavBar function to make and add the @react.component attribute to it. This tells the compiler that this is a React component, and we don't need to give it a name because it will come from the module name (the filename).
The JS version uses destructured props ({ totalCounter }). ReScript uses labeled arguments so we need to change that to (~totalCounters).
ReScript doesn't use return. The last expression in a block is returned. So we delete return and just leave the JSX expression.
The aria-hidden tag isn't valid in ReScript and it needs to be changed to ariaHidden and the value needs to be boolean instead of a string: <i className="fa fa-shopping-cart fa-lg m-2" ariaHidden=true />
In our style tag we can't use an int, it has to be a string. Everything in ReScript can only be one type so style can't be a record of string or int, it has to just be a record of string.
The text that says "Items" has to be wrapped in React.string. We can't just put text here because of the strict types, we have to pass it to a function that converts a string into a type of React.element. Don't worry, this doesn't exist in our compiled code.

Great! Now it compiles. Here's what it looks like:



@react.component
let make = (~totalCounters) => {
  <nav className="navbar navbar-light">
    <div className="navbar-brand">
      <i className="fa fa-shopping-cart fa-lg m-2" ariaHidden=true />
      <span className="badge badge-pill badge-info m-2" style={{width: "50", fontSize: "24px"}}>
        {totalCounters}
      </span>
      {React.string("Items")}
    </div>
  </nav>
}

It's not that different from our original code and a JavaScript dev should easily be able to read it.

Note: We're not putting type annotations on things because ReScript can correctly infer all of our types. Everything you see here has a type that is guaranteed to be correct. totalCounters is correctly inferred to be a React.element because that's how we use it later.

Now our React app is complaining that it can't find the navbar.js file. We just need to change the import in App.js to import { make as NavBar } from "./components/navbar.bs"; and it will compile and render as expected.

Every thing looks good so far! Here's a PR with the changes: https://github.com/jderochervlk/rescript-counter-app/pull/2

Note: When you are starting out with ReScript it is recommended to commit the compiled JavaScript along with the source ReScript code. This allows people to look at PRs and see the JS code and they should be able to contribute even if they don't fully understand everything in ReScript. It will help you and your team learn the language together.

Counter

This one will be a bit more tricky because it's a class component. ReScript only has functional components, so we'll have to refactor it. I'll do that and then convert it to ReScript.

Here's our starting refactored component



import React from "react";

function Counter({ counter, onIncrement, onDecrement, onDelete }) {
  let getBadgeClasses = () => {
    let classes = "badge m-2 badge-";
    classes += counter.value === 0 ? "warning" : "primary";
    return classes;
  };

  let formatCount = () => {
    const { value } = counter;
    return value === 0 ? "Zero" : value;
  };

  return (
    <div>
      <div className="row">
        <div className="">
          <span style={{ fontSize: 24 }} className={getBadgeClasses()}>
            {formatCount()}
          </span>
        </div>
        <div className="">
          <button
            className="btn btn-secondary"
            onClick={() => onIncrement(counter)}
          >
            <i className="fa fa-plus-circle" aria-hidden="true" />
          </button>
          <button
            className="btn btn-info m-2"
            onClick={() => onDecrement(counter)}
            disabled={counter.value === 0 ? "disabled" : ""}
          >
            <i className="fa fa-minus-circle" aria-hidden="true" />
          </button>
          <button
            className="btn btn-danger"
            onClick={() => onDelete(counter.id)}
          >
            <i className="fa fa-trash-o" aria-hidden="true" />
          </button>
        </div>
      </div>
    </div>
  );
}

export default Counter;

getBadgeClasses

ReScript doesn't have a += operator (values are immutable) so we can just concatenate the string using ++. Before we can access counter.value we need to declare a type for it. We don't have to annotate our function with that type because the compiler will connect them together for us.



type counter = {value: int}

...

let getBadgeClasses = () => {
  "badge m-2 badge-" ++ {counter.value === 0 ? "warning" : "primary"}
}

formatCount

We can't concatonate a string with an int like we can in JavaScript so we need to convert our value to a string first.



let formatCount = () => {
  counter.value == 0 ? "Zero" : counter.value->Int.toString
}

Note: -> is the pipe operator. It allows us to take a value and pass it as the first argument of the next function.

The rest

Clean up our JSX and fix the types passed to DOM elements and update the import in counters.jsx and it will render and work correctly.

PR is here: https://github.com/jderochervlk/rescript-counter-app/pull/3

Counters

This one is also a class component that we need to refactor first, which just takes a minute since it doesn't have state.

We want to use the counter type from counter.res so we will add a type annotation to our prop:



let make = (~onReset, ~onIncrement, ~onDelete, ~onDecrement, ~counters: array<Counter.counter>, ~onRestart) => { ... }

If a type comes from another module you need to usually add an annotation or Open that module so inference will work.

Since we are using counter as the shared type from the Counter module we will rename it to t, which is the normal way in ReScript to say "this is the main type of this module". It's easier to read and use Counter.t for the type instead of doing Counter.counter.

Here's the PR for Counters: https://github.com/jderochervlk/rescript-counter-app/pull/4

App.js

This is another class component we will need to refactor first. It has state and some methods to manage the state. To make this easier and avoid doing rework I will comment out the internals of those functions for now and rework each one into rescript.

Converting it over to a functional component and refactoring it to ReScript allowed us to clean up the state and state management functions to not mutate values and be more declarative.



  let (counters, setCounters) = React.useState(() => [
    {id: 1, value: 0},
    {id: 2, value: 0},
    {id: 3, value: 0},
    {id: 4, value: 0},
  ])

  let handleIncrement = counter => {
    setCounters(prev => prev->Array.map(c => c.id != counter.id ? c : {...c, value: c.value + 1}))
  }

  let handleDecrement = counter => {
    setCounters(prev => prev->Array.map(c => c.id != counter.id ? c : {...c, value: c.value - 1}))
  }

  let handleReset = () => {
    setCounters(prev =>
      prev->Array.map(c => {
        ...c,
        value: 0,
      })
    )
  }

  let handleDelete = counterId => {
    setCounters(prev => prev->Array.filter(c => c.id !== counterId))
  }

handleReset

This function uses window.location.reload() which is a DOM api. We don't currently have any DOM bindings installed and available for ReScript. Let's go ahead and install some bindings.



open Webapi.Dom
open Location

...

let handleRestart = () => {
  location->reload
}

Here's the PR for App.js: https://github.com/jderochervlk/rescript-counter-app/pull/5

index.js

This is what it looks like as index.res:



%%raw("import './index.css'")
%%raw("import 'bootstrap/dist/css/bootstrap.css'")
%%raw("import 'font-awesome/css/font-awesome.css'")

switch ReactDOM.querySelector("#root") {
| Some(rootElement) => {
    let root = ReactDOM.Client.createRoot(rootElement)
    ReactDOM.Client.Root.render(root, <App />)
  }
| None => ()
}

Since we don't have a way to import .css files into ReScript we can use the %%raw expression to tell ReScript that we have a little snippet we aren't going to compiler. Here are some docs on this.

The way this CRA works it needs an index.js file, so index.bs.js won't work. Thankfully we can just update bsconfig.js and it will change all the extensions for us.



{
  ...
  "suffix": ".js",
  ...
}

Here's our final PR: https://github.com/jderochervlk/rescript-counter-app/pull/6

Wrapping up

We did it!

Now our app is fully typed and when saving a ReScript file the compiler updates in under 110 milliseconds so we didn't add any delays to our build process. If we run npx rescript clean and then npx rescript to do a fresh build from scratch it takes about 2 seconds.

We were able to break out the app and switch to ReScript slowly over multiple PRs and we didn't make any other changes to our application or tooling. This is still a CRA and we still use the standard npm run start to run it, and we can also eject it if we want to customize the configs later if we need to.

Feel free to ask any questions in the comments!

Promises, async, and await in ReScript (with Bun!)

Josh Derocher-Vlk — Tue, 26 Sep 2023 16:42:18 +0000

ReScript is "Fast, Simple, Fully Typed JavaScript from the Future"

Let's take a look at how to use JavaScript promises, async, and await in ReScript using Bun v1 to quickly run and see our changes.

ReScript

ReScript is a strongly typed language with a JavaScript like syntax that compiles to JavaScript.

Getting set up

We'll be using Bun as our package manager and to run our code as we work.

If you don't already have Bun installed go ahead and run npm i bun -g.
Create a new folder and open up VSCode or your IDE of choice.
Install the ReScript extension for your IDE.
Set up your project with bun init. Set the entry point to src/index.mjs.
Install ReScript: bun install rescript@next @rescript/core

Create a bsconfig.json file to configure ReScript:



{
    "name": "bun-rescript",
    "sources": [
        {
            "dir": "src",
            "subdirs": true
        }
    ],
    "package-specs": [
        {
            "module": "es6",
            "in-source": true
        }
    ],
    "suffix": ".mjs",
    "bs-dependencies": [
        "@rescript/core"
    ],
    "bsc-flags": [
        "-open RescriptCore"
    ]
}

Create a src/index.res file that logs something to the console:



Console.log("starting...")

Run bun rescript build -w in one terminal tab or window and bun --watch src/index.mjs in another.

You now have ReScript quickly compiling the .res file into a .mjs file in a few milliseconds and then Bun running that code in a few milliseconds. This is a very nice quick feedback loop to use for rapid development.

Promises

I will assume you have a basic working knowledge of Promises in JavaScript.

Here's a really basic example of a Promise in ReScript:



let main = () => {
  let _ = Promise.resolve(42)->Promise.then(n => Console.log(n)->Promise.resolve)
}

main()

Let's walk through each part of the code here.

Let's start by understanding what's going on with main and the let _ = part.



let main = () => {
  let _ = ...
}

main()

In ReScript every line of code is an expression and the last expression in a function is the return value.



let fn = () => {
  42 // this function returns 42
}

Note: even though we aren't adding type annotations, ReScript is able to always correctly infer the types so this function has a type signature of unit => int. unit in ReScript means that we have no value at all, so this function takes in no parameters and returns an int.

Any top level expression has to have a type of unit in ReScript, which means we can't return something in a top level function call like what we are doing with main(). So our we have to make sure it returns a type of unit and we can do that by assigning the value to _. _ is a special syntax for a value that exists but we never intend to use. If we did let x = ... the compiler would warn us that x is never used.

Creating the promise looks identical to JavaScript:



Promise.resolve(42)

The next part is different from JS. In ReScript we don't have dot style chaining so we can't do Promise.resolve(42).then(...). ReScript has pipes, which we use with the -> operator. So we take the Promise we created and "pipe" it into the next step, which is Promise.then.



Promise.resolve(42)->Promise.then(...)

And inside Promise.then we are logging to the console and returning the result (which is unit) as a Promise. In ReScript every Promise.then has to return another Promise. JavaScript Promises do some magic to handle returning a value or another Promise inside of .then, and since a type can only every be one thing in ReScript we have to commit to always explicitly returning a Promise. Thankfully the Promise module has a thenResolve function that can clean this up.



let main = () => {
  let _ = Promise.resolve(42)->Promise.thenResolve(n => Console.log(n))
}

main()

Switching to `async`/`await`

This function can never throw an error so we don't need to worry about .catch so we can safely convert it to async/await syntax. If you want to avoid runtime errors you shouldn't use async/await unless you want to wrap it in a try/catch block, which can get ugly real quick.

In ReScript async/await works pretty much the same as in JavaScript. Since we're now expecting main() to return a Promise we can remove the let _ = ... part and replace it with await.



let main = async () => {
  await Promise.resolve(42)->Promise.thenResolve(n => Console.log(n))
}

await main()

Let's make it do something

Instead of returning a static number and logging it let's take in a number and validate that it is between 0 and 100. If it's out of bounds we want to return an have it log an error.



let main = async n => {
  await Promise.resolve(n)
  ->Promise.then(n =>
    n >= 1 && n <= 100
      ? Promise.resolve(n)
      : Promise.reject(Exn.raiseError("number is out of bounds"))
  )
  ->Promise.thenResolve(n => Console.log(n->Int.toString ++ " is a valid number!"))
}

await main(10)

We should see 10 is a valid number! in the Bun console, but we didn't properly handle the error if we give it an invalid number so we get a runtime exception.



4 | function raiseError(str) {
5 |   throw new Error(str);
            ^
error: number is out of bounds
      at raiseError

We can improve this by using ReScript's Result type, which is a variant type that is either Ok or an Error.



let main = async n => {
  await Promise.resolve(n)
  ->Promise.thenResolve(n =>
    n >= 1 && n <= 100
      ? Ok(n->Int.toString ++ " is a valid number!")
      : Error(n->Int.toString ++ " is out of bounds")
  )
  ->Promise.thenResolve(res =>
    switch res {
    | Ok(message) => Console.log(message)
    | Error(err) => Console.error(err)
    }
  )
}

await main(1000) // => 1000 is out of bounds
await main(10) // => 10 is a valid number!

Wrapping up

You should now have a basic understanding of how to use Promises in ReScript. The part that I think is key is that we don't have to throw errors in our promises because we have the Result type. It's a better developer and user experience to capture known errors and handle them gracefully by returning an it in an API response or rendering an error to a user in a React application.

Unknown exceptions will happen of course, but in this case we expect that the number could be invalid. What if our function was defined here and meant to used somewhere else? Let's rewrite it to return either return the number or an error message.



let validateQuantity = async n => {
  await Promise.resolve(n)->Promise.thenResolve(n =>
    n >= 1 && n <= 100
      ? Ok(n)
      : Error(n->Int.toString ++ " is out of bounds and is not a valid quantity.")
  )
}

Now the function will return promise<result<int, string>> so anyone using this knows that we expect an error case and can handle it appropriately.

We can even make the error messages have more meaning if we change this to use pattern matching:



let validateQuantity = async n => {
  await Promise.resolve(n)->Promise.thenResolve(n =>
    switch [n >= 1, n <= 100] {
    | [false, _] => Error(n->Int.toString ++ " is less than 0 and is not a valid quantity.")
    | [_, false] => Error(n->Int.toString ++ " is greater than 100 and is not a valid quantity.")
    | _ => Ok(n)
    }
  )
}

This would allow us to show a meaningful error message to a user if they try and do something invalid.



let validateQuantity = async n => {

  await Promise.resolve(n)->Promise.thenResolve(n =>

    switch [n >= 1, n <= 100] {

    | [false, ] => Error(n->Int.toString ++ " is less than 1 and is not a valid quantity.")

    | [, false] => Error(n->Int.toString ++ " is greater than 100 and is not a valid quantity.")

    | _ => Ok(n)

    }

  )

}

let addToCart = async quantity => {

  let validatedQuantity = await validateQuantity(quantity)

  switch validatedQuantity {

  | Ok(n) => Console.log(n->Int.toString ++ " items successfully added to cart!")

  | Error(e) => Console.error(e)

  }

}

await addToCart(10) // => 10 items successfully added to cart!

await addToCart(1000) // => 1000 is greater than 100 and is not a valid quantity.

await addToCart(0) // => 0 is less than 1 and is not a valid quantity.

Questions?

Please feel free to ask anything in the comments!

How to render data in a ReScript React app using fetch, promises, and safe types.

Josh Derocher-Vlk — Mon, 25 Sep 2023 20:20:53 +0000

Photo by James Kern on Unsplash.

ReScript is "Fast, Simple, Fully Typed JavaScript from the Future" that has stronger types than TypeScript, a blazing fast compiler, and only includes the good parts of JavaScript.

Let's take a look at how we can create a React app that will fetch some strings from an API and render each string in a paragraph. The strings will be random from Bacon Ipsum. We'll include a loading state, error handling, and a button that will allow the user to reload the strings.

We'll be using ReScript's Variant types to represent the state of our data, which can be "loading", "error", or "data".

We will also be using an opaque type and a parsing library to enforce some logic around what we consider to be valid data.

Set up

I'll be using Vite to build this out. It's focus on speed makes it a great companion to ReScript. I have a guide with details on how to set up our basic ReScript, React, Vite, and TailwindCSS app here.

If you used the generator you should already have a src/Button.res component. If you did it manually go ahead and add these two files.



// src/Button.res
// Styling from https://tailwind-elements.com/docs/standard/components/buttons/
let make = props =>
  <button
    {...props}
    className="inline-block px-6 py-2.5 bg-blue-600 text-white font-medium text-xs leading-tight uppercase rounded shadow-md hover:bg-blue-700 hover:shadow-lg focus:bg-blue-700 focus:shadow-lg focus:outline-none focus:ring-0 active:bg-blue-800 active:shadow-lg transition duration-150 ease-in-out"
  />



// src/Button.resi
let make: JsxDOM.domProps => Jsx.element

Replace the contents of src/App.res with this:



@react.component
let make = () => {
  <div className="p-6">
    <h1 className="text-3xl font-semibold mb-5"> {"Bacon Ipsum"->React.string} </h1>
    <Button> {"refresh data"->React.string} </Button>
  </div>
}

And double check that you have a src/App.resi file.



@react.component
let make: unit => Jsx.element

Kick off the Vite dev server with npm run dev and if you are using VSCode with the ReScript extension it should ask you if you want to start the ReScript build server, otherwise run npm run res:dev in another terminal to start ReScript.

You should now be able to see a basic site with blazing fast HMR when you save a file.

Planning out our data with types

Before we start writing any features let's plan out our data and business logic with types. If you want to learn more about how to do Domain Driven Design in a functional language check out this talk and book from Scott Wlaschin. He's using F#, but ReScript is also in the ML family of languages so we are able to do the same thing here.

What is our data?

In our application we have randomized strings we get from Bacon Ipsum. We will refer to these strings as a bacon. Our application will render bacon to the user, but we want to verify that we're not just allowing any array of strings to be rendered when we expect bacon. This can cause bugs later once our application scales and we have 30 developers, 2 product managers, and 100,000 lines of code.

We know that bacon is always external and that we have to request it from an API. This means that it could be Loading, have an Error, or have Data.

Let's use the strong type system of ReScript to help us define bacon in a way that the compiler will help us follow our own business logic and prevent bugs later.

Create our types

Let's start by creating a type for bacon. In a new file called bacon.res we will add a type t that is an alias to array<string>. t is the standard name for a module's main type. Here we have a module Bacon that is generated from the file bacon.res and the main type is Bacon.t.



type t = array<string>

We'll make this opaque later, but for now let's keep adding types.

We will now make a variant type for bacon to represent the possible states of our data.



type t = array<string>

type error = string

type bacon =
  | Loading // loading has no value
  | Error(error)
  | Data(t) // and our data contains our internal type t

Those are our main two types we will be working with. Let's create a bacon.resi file. This is ReScript's interface file and it allows us to define types for a module. Having an interface file speeds up the already fast compiler and it allows us to keep some things in our module private.



// src/bacon.resi
type t
type error

type bacon =
  | Loading
  | Error(error)
  | Data(t)

Notice how it looks almost identical to our implementation file, but we didn't alias t to array<string> or error to string. This now means that you can't just make anything be Bacon.Data or a Bacon.Error.

Note: Bacon is now a module in our application created from the file bacon.res. ReScript doesn't have imports, so to access the types and values in bacon.res you use Bacon.Data.

To test this out let's go into App.res and try and add the following to the bottom of the file.



let bacon = Bacon.Data(["foo", "bar"])

You will see a compiler error.

To anything outside of the Bacon module it's unknown what the type is for Bacon.t. This means we just can't put any value in there. The Bacon module will need a way for us to create something that is Bacon.t.

Smart constructor

In order to take in an array<string> and turn it into valid Bacon.t we will be using a smart constructor which is a function that looks at our unknown input and has a runtime validation to make sure the data is correct.

We'll be using rescript-struct as our parsing library.

Note: the links are for v4 which is not the latest version. v5 depends on ReScript v11 which I am not using yet. V4 and V5 have slightly different APIs, but the concept is the same.

Install it with npm install rescript-struct@v4 and add it to bsconfig.json.



"bs-dependencies": [
  "@rescript/react",
  "@rescript/core",
  "rescript-struct"
],
"bsc-flags": [
  "-open RescriptCore",
  "-open RescriptStruct"
],

We'll add this to bacon.res



/**
We are creating a struct that validates that the input is what we expect it to be. This check is done at run time and the function generates types that we can use when compiling.

Check the rescript-struct docs for more details.
*/
let baconStruct = S.array(S.string())

let constructBacon = x => {
  // we use parseAnyWith because we the data coming from our fetch request will be of an unknown type 
  let val = x->S.parseAnyWith(baconStruct)
  // val will be a Result, which is either OK or an Error
  // we can map this to internal values of Bacon.Data or Bacon.Error
  switch val {
  | Ok(a) => Data(a)
  | Error(e) => Error(e->S.Error.toString)
  }
}

Fetch our data and assign it to the correct type

Now that we have our types defined and a way to verify the incoming data is correct, let's go ahead and fetch some data.

We'll need to install a ReScript library for DOM bindings including fetch.



npm install rescript-webapi

Add it to bsconfig.json:



  "bs-dependencies": [
    "@rescript/react",
    "@rescript/core",
    "rescript-struct",
    "rescript-webapi" // new
  ],
  "bsc-flags": [
    "-open RescriptCore",
    "-open RescriptStruct",
    "-open Webapi", // new
    "-open Promise" // new
  ],

Now we can add a fetch function to bacon.res:



let url = "https://baconipsum.com/api/?type=meat-and-filler"

let fetch = () => {
  // instead of .then we pipe to the then function for the next step
  Fetch.fetch(url)->then(res =>
    // we can switch on res.ok to handle a success or failure
    switch res->Fetch.Response.ok {
    // if the response is ok we can parse the json and use constructBacon to validate that the data is correct
    | true => res->Fetch.Response.json->then(res => res->constructBacon->resolve) // every Promise in ReScript has to return another Promise 
    | false =>
      // if the response isn't ok we create an Error string with the status and statusText
      Error(
        `${res->Fetch.Response.status->Int.toString}: ${res->Fetch.Response.statusText}`,
      )->resolve
    }
  )
  // and if an unknown error occurs we use Promise.catch to hande it
  ->catch(_ => Error("Something went wrong")->resolve)
}

We want that function to be available outside of the Bacon module so let's add it to bacon.resi:



type t
type error

type bacon =
  | Loading
  | Error(error)
  | Data(t)

let fetch: unit => Promise.t<bacon>

Nice! Hopefully you can start to see how the .resi file allows us to keep everything that we mean to be consumed from the outside in a clean and easy to understand place. We can do whatever we want in the implementation file, but the outside world can only use what we allow them to.

Fetch the data on page load

Now we have all of plumbing set up for the Bacon module we can start adding it to our React page in App.res.

Create a local state to track our bacon data:



@react.component
let make = () => {
  // the default state will be Loading
  let (bacon, setBacon) = React.useState(() => Bacon.Loading) //  new

  <div className="p-6">
    <h1 className="text-3xl font-semibold mb-5"> {"Bacon Ipsum"->React.string} </h1>
    <Button> {"refresh data"->React.string} </Button>
  </div>
}

We'll add in a useEffect0 to call a side effect with an empty dependency array in our main App.res component. This will call our Bacon.fetch only once when the component first mounts.



@react.component
let make = () => {
  let (bacon, setBacon) = React.useState(() => Bacon.Loading)

  /* new */
  let handleBacon = () => Bacon.fetch()->then(t => setBacon(_ => t)->resolve)

  /* new */
  React.useEffect0(() => {
    let _ = handleBacon() // we assign this to _ since we aren't returning it
    None // we have nothing to clean up so we return None
  })

  <div className="p-6">
    <h1 className="text-3xl font-semibold mb-5"> {"Bacon Ipsum"->React.string} </h1>
    <Button> {"refresh data"->React.string} </Button>
  </div>
}

Let's add in a quick console log to make sure we are fetching the data.



@react.component
let make = () => {
  let (bacon, setBacon) = React.useState(() => Bacon.Loading)

  let handleBacon = () => Bacon.fetch()->then(t => setBacon(_ => t)->resolve)

  React.useEffect0(() => {
    let _ = handleBacon()
    None
  })

  /* new */
  React.useEffect1(() => {
    Console.log(bacon)
    None
  }, [bacon])

  <div className="p-6">
    <h1 className="text-3xl font-semibold mb-5"> {"Bacon Ipsum"->React.string} </h1>
    <Button> {"refresh data"->React.string} </Button>
  </div>
}

We can see 3 console logs happening!

Once for the blank loading state, and two times from our useEffect hook in React Strict mode.

Let's go ahead and render the data with pattern matching:

Let's add a render function to bacon.res to handle each possible state.



let render = bacon =>
  switch bacon {
  | Loading => <p className="my-3"> {React.string("loading...")} </p>
  | Error(err) => <p className="my-3"> {React.string(err)} </p>
  | Data(data) => data->Array.map(text => <p className="my-3"> {React.string(text)} </p>)->React.array
  }

Add that function to our bacon.resi file:



type t
type error

type bacon =
  | Loading
  | Error(error)
  | Data(t)

let fetch: unit => Promise.t<bacon>

let render: bacon => React.element

And we can render it now in our app:



// src/App.res
@react.component
let make = () => {
  let (bacon, setBacon) = React.useState(() => Bacon.Loading)

  let handleBacon = () => Bacon.fetch()->then(t => setBacon(_ => t)->resolve)

  React.useEffect0(() => {
    let _ = handleBacon()
    None
  })

  <div className="p-6">
    <h1 className="text-3xl font-semibold mb-5"> {"Bacon Ipsum"->React.string} </h1>
    <Button> {"refresh data"->React.string} </Button>
    // new
    {bacon->Bacon.render}
  </div>
}

Finally let's attach the handleBacon function to the onClick of our Button.



<Button
  onClick={_ => {
    let _ = handleBacon()
  }}>
  {"refresh data"->React.string}
</Button>

App.res will now look like this:



// src/App.res
@react.component
let make = () => {
  let (bacon, setBacon) = React.useState(() => Bacon.Loading)

  let handleBacon = () => Bacon.fetch()->then(t => setBacon(_ => t)->resolve)

  React.useEffect0(() => {
    let _ = handleBacon()
    None
  })

  <div className="p-6">
    <h1 className="text-3xl font-semibold mb-5"> {"Bacon Ipsum"->React.string} </h1>
<Button
  onClick={_ => {
    let _ = handleBacon()
  }}>
  {"refresh data"->React.string}
</Button>
    {bacon->Bacon.render}
  </div>
}

Wrapping up

We now have a simple application that fetches data from an external source, verifies that data is the shape we expect, and with types can represent the possible states of our data.

Why do we need these opaque and variant types?

In our example bacon is means more than just a bunch of strings. bacon is a list of strings that comes from a certain API. There is no other way to create bacon. This is incredibly powerful because we can now rely on the compiler and type system to know the source of this list of strings. We have given extra meaning to the data.

In 6 months or a year if another developer has to work on this code, or worse we have to come back to it and remember what we did, we have set up a system that enforces data flow and will help us catch bugs.

Here are some features we will have to add to our app over the next few months. As we add these features our team will be hiring 5 new developers to help us implement all of these. I'll let you imagine how this would go in a traditional JavaScript application compared to our

Add a new page and api for eggs
Log anytime a user sees bacon
Show a special pop up to users who are seeing eggs
Capitalize every first word in bacon
Add a new page and api for sausage
Show a log in prompt for users who are seeing sausage
sausage now has two api responses depending on if the user is logged in or not
if a logged in user sees bacon we want to send an email to that user
business is going great! We need to add pages and apis for fruit, juice, and coffee!

And so on.

In our ReScript app we have strong guarantees that we can't accidentally use data with functions that might have unintended side effects. We don't want to log the wrong thing to our database, or show a popup on the wrong page. Sure, we can do all of this without types, but eventually something will be missed or forgotten.

Imagine that we have a dozen functions that do something with bacon and we have to add a new variant type for AuthenticatedData:



type bacon =
  | Loading
  | Error(error)
  | Data(t)
  | AuthenticatedData(t)

In any function that does pattern matching with bacon we will get a warning from the compiler:



You forgot to handle a possible case here, for example: AuthenticatedData(_)

We can now go through each function and update the switch to handle the new case. We can even configure the ReScript compiler to error instead of warn for this to prevent us from shipping it to production.

Codesandbox

Here's the app running in Codesandbox if you want to take a look around.

Questions?

Feel free to ask anything in the comments!

My other ReScript articles

How to set up a React app using ReScript, Vite, and Tailwind for lightning fast development.

Josh Derocher-Vlk ・ Sep 24 '23

#rescript #react #vite #tailwindcss

How to handle routing in a ReScript React app using pattern matching.

Josh Derocher-Vlk ・ Sep 24 '23

#rescript #react #routing #vite

How to handle routing in a ReScript React app using pattern matching.

Josh Derocher-Vlk — Sun, 24 Sep 2023 20:04:59 +0000

Photo by Alexander Schimmeck on Unsplash

Most React applications have multiple pages and you need to set up some type of routing. Let's take a look at how to add multiple pages to a React application created with ReScript and Vite.

We'll be starting with a basic React app created with ReScript, Vite, and Tailwindcss. This guide will help you get that set up.

@rescript/react comes with a router already so we don't need to install anything else to get started. Here are the full docs, but let's walk through each step in detail to make sure we understand it.

Create two page components

We'll need to create a component for each page we want to be able to navigate to. Let's make a page called dog and one called cat. We're using Tailwind for our styles.



// src/Dog.res
@react.component
let make = () => {
  <div>
    <h2 className="text-xl"> {React.string("Dog")} </h2>
    <img
      className="max-w-full mx-auto mt-5"
      alt="a dog"
      src="https://media.giphy.com/media/4Zo41lhzKt6iZ8xff9/giphy.gif"
    />
  </div>
}



// src/Cat.res
@react.component
let make = () => {
  <div>
    <h2 className="text-xl"> {React.string("Cat")} </h2>
    <img
      className="max-w-sm mx-auto mt-5"
      alt="a cat"
      src="https://media.giphy.com/media/7YCA4XbA0ArQuWEfqJ/giphy.gif"
    />
  </div>
}

You will also want to create an interface file (.resi) for each of these components to make sure Vite's HMR works correctly and to speed up the already fast ReScript compiler. If you are using VSCode with the ReScript extension you can do this automatically by hitting f1 and looking for ReScript: Create an interface file for this implementation file. It's always good practice to create .resi files.



// src/Dog.resi
@react.component
let make: unit => React.element



// src/Cat.resi
@react.component
let make: unit => React.element

Note: unit means the function doesn't take in any parameters.

Creating a Page component to handle what to render

We'll need a Page component to handle rendering the correct content based on the route.

This will use ReScript's Pattern Matching feature to handle what we want to show based on the route. We'll switch on the url.path, which is a list. In our case we want to render <Dog/> if the list has one item that is "dog", which would be a path of /dog. If the path had multiple parts, like /dog/poodle/fluffy we would have #list{"dog", "poodle", "fluffy"}. For now let's just focus on handling "dog" and "cat".



@react.component
let make = () => {
  let url = RescriptReactRouter.useUrl()

  switch url.path {
  | list{"dog"} => <Dog />
  | list{"cat"} => <Cat />
  | _ => <h2> {React.string("404: page not found")} </h2>
  }
}

Remember to generate the .resi file for this component!

Add the Page component to `App.res`

Clear out the contents of the existing src/App.res file and set it up to render our new Page component.



@react.component
let make = () =>
  <div className="text-center p-5 text-gray-700">
    <h1 className="text-3xl m-5"> {React.string("Cats or Dogs?")} </h1>
    <Page />
  </div>

You should now see our 404 error.

If you manually add /cats to the url you should see the cat page.

Creating our navigation bar

We'll need a quick nav bar to move between pages:



// src/Nav.res
@react.component
let make = () => {
  <nav className="flex justify-center space-x-2 w-full mx-auto">
    <button className="bg-blue-300 p-2 mx-1 rounded text-white"> {React.string("cat")} </button>
    <button className="bg-blue-300 p-2 mx-1 rounded text-white"> {React.string("dog")} </button>
  </nav>
}

Add it to App.res:



@react.component
let make = () =>
  <div className="text-center p-5 text-gray-700">
    <h1 className="text-3xl m-5"> {React.string("Cats or Dogs?")} </h1>
    <Nav />
    <Page />
  </div>

Now we have buttons, but they don't do anything, and we start out on a 404 page.

Hooking it all up.

Redirect to a default page

If a user opens our app we don't want them to see a 404 page, so let's redirect them to "/cat".

We can get the current url from RescriptReactRouter.useUrl() and then switch on it inside of a useEffect hook. url.path is a list and we can pattern match for an empty list and replace the url with cat or do nothing by returning () (that's how you write unit).

Here's our new code:



  let url = RescriptReactRouter.useUrl()

  React.useEffect0(() => {
    switch url.path {
    | list{} => RescriptReactRouter.replace("cat")
    | _ => ()
    }
    None
  })

You'll notice we used useEffect0 instead of useEffect. In ReScript a value can only have one type so we need different functions depending on how many values we plan on using in the dependency array. We only want to do this once so we would be passing it an empty array if we were in normal JavaScript, but here we just use useEffect0. If we had one item we would use useEffect1 and so on.

ReScript forces us to always return something as part of cleaning up a useEffect hook, and since we don't have anything to clean up here we just use None as the last expression.

Here's what App.res looks like now:



@react.component
let make = () => {
  let url = RescriptReactRouter.useUrl()

  React.useEffect0(() => {
    switch url.path {
    | list{} => RescriptReactRouter.replace("cat")
    | _ => ()
    }
    None
  })

  <div className="text-center p-5 text-gray-700">
    <h1 className="text-3xl m-5"> {React.string("Cats or Dogs?")} </h1>
    <Nav />
    <Page />
  </div>
}

Set up navigation

We need to show a new page after a user clicks on a navigation button.

Let's make on function to handle clicking on a navigation button:



  let handleClick = React.useCallback0(path => {
    RescriptReactRouter.push(path)
  })

.push will change our URL in a way that allows the browsers back button to still work and it will stay in sync with the useUrl hook we have in the Page.res component.

We can call this from each navigation button with the correct path.



// src/Nav.res
@react.component
let make = () => {
  let handleClick = React.useCallback0(path => {
    RescriptReactRouter.push(path)
  })

  <nav className="flex justify-center space-x-2 w-full mx-auto">
    <button onClick={_ => handleClick("cat")} className="bg-blue-300 p-2 mx-1 rounded text-white">
      {React.string("cat")}
    </button>
    <button onClick={_ => handleClick("dog")} className="bg-blue-300 p-2 mx-1 rounded text-white">
      {React.string("dog")}
    </button>
  </nav>
}

You now have a small app with functioning navigation!

Please let me know in the comments if you have any questions.

How to set up a React app using ReScript, Vite, and Tailwind for lightning fast development.

Josh Derocher-Vlk — Sun, 24 Sep 2023 17:23:15 +0000

Let's set up a modern React application using tools that give the fastest local development experience while still enabling strict type checking.

ReScript modules can almost instantly compile to JavaScript Modules (ESM) which allows us to use a tool like Vite to quickly load them directly into the browser when changes are made.

Note: This guide will walk you through all of the steps manually to set up ReScript, Vite, and Tailwindcss. I suggest you do this at least once to learn how it all works, but you can also use npm create rescript-app to quickly create an app with these tools. Just select "vite" for a template and include the new @rescript/core library when asked.

What is ReScript?

ReScript is a language that compiles to JavaScript with strong types, a speedy compiler, no null exceptions, and pattern-matching.

You can add it to your existing JS toolchain and build system, and it uses your standard JS package manager like NPM or Yarn.

Using it feels very similar to using TypeScript, but there are a few key differences to each language:

ReScript is strongly typed, which means nothing can be of an any type or unknown. If something has a type it is guaranteed to be correct.
TypeScript is a superset of JavaScript, which means that all valid JS is valid TS. While ReScript has a JS like syntax it is a different language, so most of the JS foot guns don't exist like knowing when to use == or ===.
While you can adopt both languages gradually into a project the approach is different. With TypeScript you start off without strict mode, rename the files from .js to .ts, slowly convert all of the any types to known types, and (hopefully) turn on strict mode. With ReScript you would convert a single file at a time.

You can see more differences here.

Set up your IDE

Installing a ReScript plugin into your IDE will give you syntax highlighting, auto-complete, and clicking to sources for functions, types, and values.

For VSCode you can search for and install the ReScript extension. If you are using a different IDE you can find instruction on the ReScript site.

Set up the workspace

I'll be using npm, but you can swap this out for your package manager of choice.



mkdir my-rescript-vite-app
cd my-rescript-vite-app
npm init -y

Open this folder in your IDE.

Install ReScript

Let's install ReScript and the ReScript Core library.



npm i rescript @rescript/core

Now we have to create the ReScript config file.

Note: ReScript is based on a combination of the Reason and BuckletScript, so you'll see bs used in places.

Create a rescript.json file in the root of the application.



{
    "name": "my-rescript-vite-app",
    "sources": [
        {
            "dir": "src",
            "subdirs": true
        }
    ],
    "package-specs": {
        "module": "es6",
        "in-source": true,
        "suffix": ".mjs"
    },
    "bs-dependencies": [
        "@rescript/core"
    ],
    "bs-dev-dependencies": [],
    "bsc-flags": [
        "-open RescriptCore"
    ]
}

Quick breakdown of the config options

name: the name of our application
sources: where our code lives
package-specs: what module system we want to use and if we want the output to live in the same folder as the source
bs-dependencies: similar to npm dependencies
bs-dev-dependencies: similar to npm dev-dependencies
bsc-flags: Additional options for the compiler }

We've set up ESM files since we'll be using Vite, added @rescript/core as a dependencies, and we're opening up that module to make it easier to access later.

You can read the full documentation on the ReScript site.

Verify that ReScript compiles

We should be able to compile and run some code now!
Add a couple scripts to the package.json file:



"scripts": {
  "res:build": "rescript",
  "res:dev": "rescript -w"
}

Create a file named src/hello.res and log something to the console:



Console.log("Hello world!")

Compile the source code with npm run res:build and execute it with node src/hello.mjs.

You should see Hello world! print to the console.

Install React

Install React, React Dom, and Rescript bindings for React.



npm i react react-dom @rescript/react

Then add @rescript/react as a dependency in bsconfig.json and configuration for JSX.



"jsx": { "version": 4, "mode": "automatic" },
"bs-dependencies": ["@rescript/core", "@rescript/react"]

Let's change hello.res to be a React component and rename it to App.res.



@react.component
let make = () => <p> {React.string("Hello world!")} </p>

We'll also want to make an interface file (.resi) for each React component. This enables Vite's hot module reloading (HMR) to work as expected when making changes to our ReScript components.

Note: For HMR to work correctly each file can only contain one component and cannot export any other functions.

Install Vite



npm i vite @vitejs/plugin-react -D

Create an index.html file in the project root:



<!doctype html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ReScript Vite App</title>
</head>

<body>
    <div id="root"></div>
    <script type="module" src="./src/Main.mjs"></script>
</body>

</html>

Create our main app at src/Main.res:



switch ReactDOM.querySelector("#root") {
| Some(rootElement) => {
    let root = ReactDOM.Client.createRoot(rootElement)
    ReactDOM.Client.Root.render(root, <App />)
  }
| None => Exn.raiseError("No element has ID of #root!")
}

Create vite.config.mjs in the root of the project:



import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(
    {
       include: ["**/*.mjs"], // since we're not using .jsx files we have to tell Vite to watch for HMR changes to .mjs files
    }
  )],
});

And finally let's add some more npm scripts to build our app:



"scripts": {
    "res:build": "rescript",
    "res:clean": "rescript clean",
    "res:dev": "rescript build -w",
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },

Open up two terminal windows or tabs. In the first one run npm run res:dev and in the second run npm run dev. If you are using VSCode with the ReScript extension installed it will ask you if you want to run a ReScript build server which you can use instead of running npm run res:dev. I choose to run it from the terminal so I can see both outputs next to each other easily.

You should now be able to open up http://127.0.0.1:5173/ and see "Hello world!". Make a change to App.res and you should see Vite apply the changes with HMR.

Adding Tailwind CSS

Starting by installing Tailwind and running the setup command.



npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add html and mjs files to the tailwind.config.js file:



/** @type {import('tailwindcss').Config} */
export default {
  content: ["./src/**/*.{html,mjs}"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Add src/main.css with the basic Tailwind setup:



@tailwind base;
@tailwind components;
@tailwind utilities;

Import that file into index.html.



<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link href="./src/main.css" rel="stylesheet">
    <title>ReScript + Vite + React</title>
</head>

<body>
    <div id="root"></div>
    <script type="module" src="/src/Main.mjs"></script>
</body>

</html>

Now we can use Tailwind classes in our ReScript components! Go ahead and add some to App.res.



@react.component

let make = () =>

  <div className="text-3xl text-center m-5 text-gray-700"> {React.string("Hello world.")} </div>

Wrapping up

You now have the basic shell to build out a React application quickly and with confidence.

During local development we can see change appear in milliseconds instead of minutes or seconds, and we can do this while still having confidence in our code because of ReScript's strong type system and compiler. ReScript removes the need for TypeScript (has types already), ESLint (ReScript doesn't have the "bad parts" of JS and the compiler helps us write clean code), and Prettier (ReScript has a built in formatter). Since we don't need these tools it speeds up VSCode because these don't have to run every time we save a file.

Make sure to check out other articles on ReScript!

DEV Community: Josh Derocher-Vlk

Rescript is truly a game changer for web development. Types are great, but types shine when you can rely on a sound type system, typed errors, and easy to use variant types.

ReScript 2025 — The Top JavaScript Alternative (Tech Deep Dive)

ReScript has come a long way, maybe it's time to switch from TypeScript?

My sources of past issues

I have to understand Reason, BuckleScript, and OCaml before I can use ReScript

Should I use Belt.Array, Js.Array, or Js.Array2?

Lack of async, await, and Promises are cumbersome

Lack of community types

I don't understand how to use existing JavaScript libraries

I can't have 2 files with the same name?

Why would I pick this over TypeScript?

Not convinced?

Tired of Typescript? Check out ReScript!

ReScript

Less type annotations

Better type system

Faster compile times

The good parts of JS and more!

ReScript: Rust like features for JavaScript

What is ReScript?

Types

Expression based

Pattern Matching

Tagged Unions and Variant types

Option instead of undefined or null

Result instead of throwing errors

Learn more about ReScript

Using variant types in ReScript to represent business logic

The feature we have to build

Building it in TypeScript

Building it in ReScript

Types with logic

Why would I do this?

Variant types add meaning to our data

Adding new cases is easy

Wrapping up

How to set up a React app using ReScript, Vite, and Tailwind for lightning fast development.

Josh Derocher-Vlk ・ Sep 24 '23

Converting a JavaScript React app to a ReScript React app.

Josh Derocher-Vlk ・ Sep 27 '23

Converting a JavaScript React app to a ReScript React app.

Our project

How does ReScript work with JavaScript?

Getting started

Where to start?

Navbar

Counter

getBadgeClasses

formatCount

The rest

Counters

App.js

handleReset

index.js

Wrapping up

Promises, async, and await in ReScript (with Bun!)

ReScript

Getting set up

Promises

Switching to async/await

Let's make it do something

Wrapping up

Questions?

How to render data in a ReScript React app using fetch, promises, and safe types.

Set up

Planning out our data with types

What is our data?

Create our types

Smart constructor

Fetch our data and assign it to the correct type

Fetch the data on page load

Wrapping up

Why do we need these opaque and variant types?

Codesandbox

Questions?

My other ReScript articles

How to set up a React app using ReScript, Vite, and Tailwind for lightning fast development.

Josh Derocher-Vlk ・ Sep 24 '23

How to handle routing in a ReScript React app using pattern matching.

`Option` instead of `undefined` or `null`

`Result` instead of throwing errors

Switching to `async`/`await`

Add the Page component to `App.res`