Migrate to ReScript 11

Minimal Migration

This guide describes the things to do at least to migrate to ReScript 11.

Disable uncurried mode

If you use currying extensively and don't want to bother with adapting your code (or have dependencies )

JSON
{
  "uncurried": false
}

Recommended Migration

Uncurried Mode

For uncurried mode to take effect in ReScript 11 there is nothing to configure, it is activated by default.

Adapt suffix

ReScript 11 now allows having arbitrary suffixes in the generated JavaScript files. However it is still recommended to stick to using .res.js, .res.mjs or .res.cjs. For more information, read the Build System Configuration about suffixes.

rescript.json

The old configuration filename bsconfig.json is finally deprecated. Rename it to rescript.json.

ReScript Core standard library

There is a new standard library in development that can already be installed called ReScript Core. It replaces the complete Js module as well as some of the more frequently used modules from Belt and is the recommended standard library to use with uncurried mode. At a later stage it will be integrated into the compiler while Belt will be maintaned as a separate npm package.

Until it's integrated in the compiler, it needs to be installed manually:

CONSOLE
$ npm install @rescript/core

Then add @rescript/core to your rescript.json's dependencies:

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

Open it so it's available in the global scope.

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

For a detailed explanation on migration to ReScript Core, please refer to its migration guide. A semi-automated script is available as well.

Note: ReScript Core API docs will be added to this documentation platform at a later stage. For now check out the .resi files in the repository or, more conveniently, read the docs for a certain module or function directly in the editor tooling.

Removed bindings

Many Node bindings have been removed from the compiler. Please use rescript-nodejs instead or write your own local bindings.

List of all breaking changes

Below is an excerpt from the compiler changelog about all the breaking changes of ReScript 11.

Language and Compiler

• Add smart printer for pipe chains. https://github.com/rescript-lang/rescript-compiler/pull/6411 (the formatter will reformat existing code in certain cases)

• Parse assert as a regular function. assert is no longer a unary expression. Example: before assert 1 == 2 is parsed as (assert 1) == 2, now it is parsed as assert(1 == 2). https://github.com/rescript-lang/rescript-compiler/pull/6180

• Remove support for the legacy Reason syntax. Existing Reason code can be converted to ReScript syntax using ReScript 9 as follows:

  • npm i -g rescript@9

  • rescript convert <reason files>

• Curried after uncurried is not fused anymore: (. x) => y => 3 is not equivalent to (. x, y) => 3 anymore. It's instead equivalent to (. x) => { y => 3 }. Also, (. int) => string => bool is not equivalen to (. int, string) => bool anymore. These are only breaking changes for unformatted code.

• Exponentiation operator ** is now right-associative. 2. ** 3. ** 2. now compile to Math.pow(2, Math.pow(3, 2)) and not anymore Math.pow(Math.pow(2, 3), 2). Parentheses can be used to change precedence.

• Stop mangling object field names. If you had objects with field names containing "_" or leading "", they won't be mangled in the compiled JavaScript and represented as it is without changes. https://github.com/rescript-lang/rescript-compiler/pull/6354

• $$default is no longer exported from the generated JavaScript when using default exports. https://github.com/rescript-lang/rescript-compiler/pull/6328

• -bs-super-errors flag has been deprecated along with Super_errors. https://github.com/rescript-lang/rescript-compiler/pull/6243

• Remove unsafe j`$(a)$(b)` interpolation deprecated in compiler version 10 https://github.com/rescript-lang/rescript-compiler/pull/6068

• @deriving(jsConverter) not supported anymore for variant types https://github.com/rescript-lang/rescript-compiler/pull/6088

• New representation for variants, where the tag is a string instead of a number. https://github.com/rescript-lang/rescript-compiler/pull/6088

Compiler Libraries

• Fixed name collision between the newly defined Js.Json.t and the variant constructor in the existing Js.Json.kind type. To address this, the usage of the existing Js.Json.kind type can be updated to Js.Json.Kind.t. https://github.com/rescript-lang/rescript-compiler/pull/6317

• Remove rudimentary node bindings and undocumented %node extension. https://github.com/rescript-lang/rescript-compiler/pull/6285

• @rescript/react >= 0.12.0-alpha.2 is now required because of the React.fragment's children type fix. https://github.com/rescript-lang/rescript-compiler/pull/6238

• Remove deprecated module Printexc

Build System and Tools

• Update watcher rules to recompile only on config and *.res/*.resi/*.ml/.mli file changes. Solves the issue of unnecessary recompiles on .css, .ts, and other unrelated file changes. https://github.com/rescript-lang/rescript-compiler/pull/6420

• Made pinned dependencies transitive: if a is a pinned dependency of b and b is a pinned dependency of c, then a is implicitly a pinned dependency of c. This change is only breaking if your build process assumes non-transitivity.

• Remove obsolete built-in project templates and the "rescript init" functionality. This is replaced by create-rescript-app which is maintained separately.

• Do not attempt to build ReScript from source on npm postinstall for platforms without prebuilt binaries anymore.

• GenType: removed support for @genType.as for records and variants which has become unnecessary. Use the language's @as instead to channge the runtime representation without requiring any runtime conversion during FFI. https://github.com/rescript-lang/rescript-compiler/pull/6099 https://github.com/rescript-lang/rescript-compiler/pull/6101