V12 migration guide #1048
Open
V12 migration guide #1048
+272
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Deploying rescript-lang-org with
|
| Latest commit: |
96f546f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7a8e2b18.rescript-lang.pages.dev |
| Branch Preview URL: | https://v12-migration-guide.rescript-lang.pages.dev |
Member
Author
|
|
mediremi
reviewed
Jul 24, 2025
Member
|
Somewhere in this guide, we should mention that people need to bump to latest |
Member
Author
|
Concerning pipe-last: |
Member
|
@fhammerschmidt sorry for pushing to this branch, I hope I didn't mess anything local up on your end. |
tsnobip
reviewed
Nov 11, 2025
Member
Author
|
It's fine. In fact we could and should crowdsource more articles. |
shulhi
approved these changes
Nov 18, 2025
cknitt
requested changes
Nov 18, 2025
| - 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](#converting-generated-ml-files)). | ||
| - The old configuration filename that was deprecated in v11, `bsconfig.json`, is removed. Rename it to `rescript.json`. |
Member
There was a problem hiding this comment.
Actually support bsconfig.json is not removed yet in v12.
| - 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](#converting-generated-ml-files)). | ||
| - 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 |
|
|
||
| Some typical name changes include: | ||
|
|
||
| `Error.t` -> `JsError.t` |
Member
There was a problem hiding this comment.
The following is rather unreadable on the website, best make it a list.
|
|
||
| ### Bitwise operations | ||
|
|
||
| v11: |
Member
There was a problem hiding this comment.
I don't think the following is true. AFAIK we did not have such operators in v11 at all.
| npm run convert-ml | ||
| ``` | ||
|
|
||
| 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](https://github.com/DZakh/sury/). |
Member
There was a problem hiding this comment.
Maybe it's better to say that this is an escape hatch at the beginning of this section already.
|
|
||
| ### Build system & CLI | ||
|
|
||
| - The new Rust-based `rewatch` build system now powers the `rescript` command. The old Ninja builder moved behind `rescript legacy`, the standalone `rewatch` command was removed, and `--compiler-args` became the `compiler-args` subcommand. https://github.com/rescript-lang/rescript/pull/7551 https://github.com/rescript-lang/rescript/pull/7593 |
Member
There was a problem hiding this comment.
Suggested change
| - The new Rust-based `rewatch` build system now powers the `rescript` command. The old Ninja builder moved behind `rescript legacy`, the standalone `rewatch` command was removed, and `--compiler-args` became the `compiler-args` subcommand. https://github.com/rescript-lang/rescript/pull/7551 https://github.com/rescript-lang/rescript/pull/7593 | |
| - The new Rust-based `rewatch` build system now powers the `rescript` command. The old Ninja-based builder system moved behind `rescript legacy`, and `--compiler-args` became the `compiler-args` subcommand. https://github.com/rescript-lang/rescript/pull/7551 https://github.com/rescript-lang/rescript/pull/7593 |
| ### Build system & CLI | ||
|
|
||
| - The new Rust-based `rewatch` build system now powers the `rescript` command. The old Ninja builder moved behind `rescript legacy`, the standalone `rewatch` command was removed, and `--compiler-args` became the `compiler-args` subcommand. https://github.com/rescript-lang/rescript/pull/7551 https://github.com/rescript-lang/rescript/pull/7593 | ||
| - The `rescript legacy` subcommand was removed in favor of a stand-alone `rescript-legacy` binary. https://github.com/rescript-lang/rescript/pull/7928 |
| - The `rescript legacy` subcommand was removed in favor of a stand-alone `rescript-legacy` binary. https://github.com/rescript-lang/rescript/pull/7928 | ||
| - `rescript format` was reimplemented in Rust, its options now use the `--check` / `--stdin` long-form spelling, and the `--all` flag was removed because every tracked file (non-dev by default) is formatted automatically. https://github.com/rescript-lang/rescript/pull/7603 https://github.com/rescript-lang/rescript/pull/7752 | ||
| - The `rescript dump` command was removed; call `bsc` directly if you need to inspect `.cmi` files. https://github.com/rescript-lang/rescript/pull/7710 | ||
| - `rewatch` now builds packages marked with `"type": "dev"` (and their `dev-dependencies`) by default, and the CLI `--dev` flag no longer has any effect. https://github.com/rescript-lang/rescript/pull/7934 |
Member
There was a problem hiding this comment.
This can be removed (not a change compared to v11).
|
|
||
| ### Configuration & platform | ||
|
|
||
| - The minimum supported Node.js version is now 20. https://github.com/rescript-lang/rescript/pull/7354 |
|
|
||
| - The minimum supported Node.js version is now 20. https://github.com/rescript-lang/rescript/pull/7354 | ||
| - The `experimental-features` key in `rescript.json` now uses kebab-case to match the other config fields. https://github.com/rescript-lang/rescript/pull/7891 | ||
| - The legacy `-bs-super-errors` flag was removed along with Super_errors. https://github.com/rescript-lang/rescript-compiler/pull/6814 |
Member
There was a problem hiding this comment.
Suggested change
| - The legacy `-bs-super-errors` flag was removed along with Super_errors. https://github.com/rescript-lang/rescript-compiler/pull/6814 | |
| - The legacy `-bs-super-errors` flag was removed. https://github.com/rescript-lang/rescript-compiler/pull/6814 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.