Docs / Language Manual / Migrate to v11
Edit

Migrate to ReScript 11

Foreword

The ReScript community is proud to introduce ReScript V11 which comes with a ton of new features but also removes a lot of bulk. A migration to it can be very straightforward, but it can also take some time, depending on your code style or what dependencies you use.

Please have a look at the full set of breaking changes below to be able to decide whether this is a task you want to undertake. There is also the possibilty to opt-out of uncurried mode for now, which is probably the most fundamental change of this release. That and other new and notable features are discussed in the following blogposts:

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 deprecated. Rename bsconfig.json to rescript.json to get rid of the deprecation warning.

ReScript Core standard library

ReScript Core is ReScript's new standard library. It replaces the complete Js module as well as some of the more frequently used modules from Belt and is recommended to use with uncurried mode.

It will be integrated into the compiler in a future version. In ReScript 11, it still 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",
   ]
 }

One major change to be aware of is that array access now returns an option.

RES
let firstItem = myArray[0] // Some("hello")

If you would like to not use an option, you can use Array.getUnsafe.

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

See ReScript Core API docs here.

Removed bindings

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

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 that just don't work with uncurried mode yet, just set it to false in your rescript.json.

JSON
{
  "uncurried": false
}

For more information, read the Build System Configuration about uncurried.

List of all breaking changes

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

Language and Compiler

Compiler Libraries

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

InstallationEditor Plugins