Migrate to ReScript 12

If you encounter any missing information or issues during migration, please open an issue or, even better, send a pull request to help improve this guide.

Prerequisites

  • ReScript V11 project.

  • Uncurried mode must be enabled (i.e. you have not opted-out from it).

  • Your project must not contain any OCaml source code anymore, as support for .ml files is removed in this version. However there are ways to convert OCaml syntax with an older ReScript compiler version (see below).

  • Minimum supported Node.js version is 20.11.0.

Standard Library Changes

In V12, the new standard library ships with the compiler, so you can uninstall and remove the @rescript/core dependency from your rescript.json

CONSOLE
$ npm remove @rescript/core

DIFF
 {
   "bs-dependencies": [
-    "@rescript/core"
   ]
 }

Also remove auto opening of RescriptCore.

DIFF
 {
   "bsc-flags": [
-    "-open RescriptCore",
   ]
 }

if you had @rescript/std installed, remove it as well:

SHELL
npm uninstall @rescript/std

this is replaced by @rescript/runtime, which is a installed as a dependency of rescript now.

Replacements

Some typical name changes include:

  • Error.t -> JsError.t

  • raise(MyException("error")) -> throw(MyException("error"))

  • Js.Exn.Error exception -> JsExn

  • Error.make -> JsExn.make

  • Error.raise -> JsExn.raise

  • Error.message -> JsExn.message

  • Bool.fromStringExn("true") -> Bool.fromStringOrThrow("true")

  • Int.Bitwise.lsl -> Int.shiftLeft

Tip: You can use the migration tool to automatically replace these with the new functions.

SHELL
npx rescript-tools migrate-all 

# preview the changes via
rescript-tools migrate  [--stdout]

Bitwise operations

v11:

RES
let w = lnot(a)     // bitwise NOT
let x = lxor(a, b)  // bitwise XOR
let y = land(a, b)  // bitwise AND
let z = lor(a, b)   // bitwise OR

v12:

RES
let w = ~~~a     // bitwise NOT
let x = a ^^^ b  // bitwise XOR
let y = a &&& b  // bitwise AND
let z = a ||| b  // bitwise OR

Shift operations

v11:

RES
let x = lsl(a, b)  // logical left shift
let y = lsr(a, b)  // logical right shift
let z = asr(a, b)  // unsigned right shift

v12:

RES
let x = a << b  // logical left shift
let y = a >> b  // logical right shift
let z = a >>> b  // unsigned right shift

JSX children spread

v11:

RES
<div> ...children </div>

v12:

RES
<div> children </div>

Attributes

v11:

RES
@bs.as("foo")
@bs.send
@bs.new
@raises
@genType.as

v12:

RES
@as("foo")
@send
@new
@throws
@as

  • @meth and @bs.send.pipe are removed.

Assert

v11:

RES
assert 1 == 2

v12:

RES
assert(1 == 2)  // Now a regular function call

Configuration

Rename bsconfig.json to rescript.json and update these configuration options:

  • bs-dependencies → dependencies

  • bs-dev-dependencies → dev-dependencies

  • bsc-flags → compiler-flags

jsx

  • Set version to 4 (lower versions are not supported)

  • Remove mode option (automatically set to automatic)

Build System Changes

The build system has been completely rewritten in v12.0.0.

In v11, we had:

SHELL
# build
rescript build

# watch build
rescript build -w

# format
rescript format -all

in v12, this becomes:

SHELL
# build
rescript

# watch build
rescript watch

# format
rescript format

Converting generated .ml files

Note: This setup is an escape hatch. It keeps legacy generators like atdgen working but it also forces you to maintain two compiler versions. Whenever possible migrate such things to modern ReScript tooling such as Sury.

Some projects still rely on tools such as atdgen that emit .ml files. ReScript 12 cannot compile those files directly, so you must keep using ReScript 11 only to convert the generated .ml files back to .res files before you run the v12 build.

  1. Keep ReScript 12 as the sole compiler dependency in your main project (i.e. devDependencies.rescript stays at ^12.0.0).

  2. Install ReScript 11 in a dedicated subfolder (so its binaries never replace the v12 ones in node_modules/.bin). A simple option is to store it under a subfolder, e.g. tools (if you're using workspaces, keep this folder out of the root workspace list so hoisting can't swap the v12 shims):

cd into tools and run npm create rescript-app and select the basic template and a v11 version of ReScript. You can name it rescript-11 for instance.

  1. cd back into the root of your project and add a helper script that references the compiler from that folder (adapt the path accordingly):

    JSON
    {
  "scripts": {
    "convert-ml": "tools/rescript-11/node_modules/.bin/rescript convert src/*.ml"
  }
}

  2. Execute the helper script to convert your .ml files to .res files:

CONSOLE
npm run convert-ml

List of all breaking changes

Below is a consolidated excerpt of all the breaking changes from the compiler changelog.

Language & syntax

Standard library & runtime

Build system & CLI

Configuration & platform