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.

Recommended Migration

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).

• The old configuration filename that was deprecated in v11, bsconfig.json, is removed. Rename it to rescript.json.

• Minimum supported Node.js version is 20.0.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 x = ~a        // bitwise NOT
let y = a ^ b     // bitwise XOR
let z = a & b     // bitwise AND
let w = a | b     // bitwise OR

v12:

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

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