Migrate from BuckleScript/Reason

ReScript is a rebranding and cleanup of BuckleScript (since v8.2.0) & Reason (v3.6) that enables us to ship a tighter compile-to-JS stack with more coherent documentation & tools. If you're an existing user of BuckleScript & Reason, here's the gist:

• ReScript is mostly just BuckleScript rebranded, with a new syntax that's like the Reason syntax, but catered more toward the JavaScript crowd.

• All your existing code will keep working even if you don't upgrade.

Upgrade Your Codebase

There are lots of exciting improvements in the new syntax (features, speed, error messages, etc.). The upgrade is trivial, backward-compatible and can be done on a per-file basis:

• Upgrade your project to bs-platform 8.2.0 or later.

• Choose a file to convert, for example MyFile.re

• Compile your project and keep the generated JavaScript file around (probably MyFile.bs.js but might depend on your bsconfig.json config).

• Run node_modules/.bin/bsc -format MyFile.re > MyFile.res.

• If your new MyFile.res looks good, you can delete (or move/rename) MyFile.re before compiling again your project (otherwise you will have an error Invalid bsconfig.json implementation and interface have different path names or different cases MyFile vs MyFile because 2 files with the same module name (file basename) cannot coexist in your project).

• Last thing you can do to ensure conversion is correct: build your project with the new MyFile.res file to compare the newly generated JavaScript file with the old one. You should get almost identical generated JavaScript code.

That's it! MyFile.re could be any .re, .rei, .ml and .mli file.

Enjoy the improved experience!

Upgrade an Entire Folder

Please use this with caution. Migrating an entire codebase at once is an unnecessary risk. It is recommended to migrate small portion of code to ensure correctness. That being said, for small codebases or some tiny folders that are safely versioned, you can try the following:

CONSOLE
for f in your-folder/**/*.re; do; node_modules/.bin/bsc -format $f > ${f%.re}.res && rm $f; done;

This command loops on the .re files from the your-folder folder, converts them with a proper .res extension, and asks you if you want to remove the previous file (check the newly created .res file first and refer to instructions above to follow the check to do on your generated JavaScript). If you are confident enough, you can add -f option to the rm command to avoid all checks. This will convert your entire folder without any confirmations.

Difference With Old Reason

• Complete removal of semicolon (you can still write them).

• No need for parentheses around if, switch and try.

• Type arguments: from option(int) to option<int>.

• Old interpolated string: from {j|hello ${name}|j} to j`hello ${name}`. Now with proper unicode support!

• New interpolated string: `hello world`. Also supports multiline and unicode. "hello world" string is now singleline.

• Polymorphic variants: from `red to #red.

• Arrays: from [|1,2,3|] to [1,2,3]. In JS, arrays are the right default.

• Lists: from [1,2,3] to list[1,2,3] (8.1.1 update: now it is list{1, 2, 3}). This ties with upcoming plans to access containers in a uniform way: set[...] and map[...]. Maybe temporary.

• Exception: from try (compute()) { | Not_found => Js.log("oops")} to try compute() catch { | Not_found => Js.log("oops")}.

• First class module: from (module S: Student) to module(S: Student).

• No custom infix operator for now (including mod).

• Object access: from settings##visible #= true to settings["visible"] = true. Rejoice!

• Object: from Js.t({"age": int}) to just {"age": int}. The Js.t part is now implicit.

• Attribute: from [@myAttribute "hello"] to @myAttribute("hello"). From [%re bla] to %re(bla).

• Removed dereference syntax result^. Just use result.contents.

• fun pattern matching syntax removed.

• Type declaration is non-recursive by default, consistent with let bindings. To have recursive types, use type rec myList<'a> = Nil | Cons('a, myList<'a>).

• Use any words, including reserved keywords, as your identifier name: let \"try" = true.