From 221ebb33139aa9e61c56014f9f7764627c32c8fb Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <fh@cca.io>
Date: Thu, 12 Jun 2025 18:43:41 +0200
Subject: [PATCH 1/9] WIP: V12 migration guide

---
 pages/docs/manual/v12.0.0/migrate-to-v11.mdx | 131 -------------------
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx |  57 ++++++++
 2 files changed, 57 insertions(+), 131 deletions(-)
 delete mode 100644 pages/docs/manual/v12.0.0/migrate-to-v11.mdx
 create mode 100644 pages/docs/manual/v12.0.0/migrate-to-v12.mdx

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v11.mdx b/pages/docs/manual/v12.0.0/migrate-to-v11.mdx
deleted file mode 100644
index b1977a59a..000000000
--- a/pages/docs/manual/v12.0.0/migrate-to-v11.mdx
+++ /dev/null
@@ -1,131 +0,0 @@
----
-title: "Migrate to v11"
-description: "Instructions on upgrading to ReScript 11"
-canonical: "/docs/manual/v12.0.0/migrate-to-v11"
----
-
-# 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](#list-of-all-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](#minimal-migration) 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:
-
-- [Better interop with customizable variants](/blog/improving-interop)
-- [Enhanced Ergonomics for Record Types](/blog/enhanced-ergonomics-for-record-types)
-- [First-class Dynamic Import Support](/blog/first-class-dynamic-import-support)
-- [Uncurried Mode](/blog/uncurried-mode)
-
-## 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](/docs/manual/next/build-configuration#suffix).
-
-### 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](https://github.com/rescript-association/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`](api/core/array#value-getUnsafe).
-
-For a detailed explanation on migration to ReScript Core, please refer to its [migration guide](https://github.com/rescript-association/rescript-core#migration). A semi-automated script is available as well.
-
-See ReScript Core API docs [here](api/core).
-
-### Removed bindings
-
-Many Node bindings have been removed from the compiler. Please use [rescript-nodejs](https://github.com/TheSpyder/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](/docs/manual/next/build-configuration#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
-
-- 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:
-  - `npx rescript@9 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](https://github.com/rescript-lang/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
diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
new file mode 100644
index 000000000..d94878389
--- /dev/null
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -0,0 +1,57 @@
+---
+title: "Migrate to v12"
+description: "Instructions on upgrading to ReScript 12"
+canonical: "/docs/manual/v12.0.0/migrate-to-v12"
+---
+
+# Migrate to ReScript 12
+
+## 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`.
+
+### 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",
+   ]
+ }
+```
+
+## Replacements
+
+Some typical name changes include:
+
+`Error.t` -> `JsError.t`
+`raise(` ->  `throw(`
+`Js.Exn.Error` exception -> `JsExn`
+`Error.make` -> `JsExn.make`
+`Error.raise` -> `JsExn.raise`
+`Error.message` -> `JsExn.message` 
+ `Int.Bitwise.lsl` -> `Int.shiftLeft`
+
+
+

From 1b1fe737c268aaa534a381abcbcea6ee33029481 Mon Sep 17 00:00:00 2001
From: nojaf <florian.verdonck@outlook.com>
Date: Tue, 11 Nov 2025 10:11:05 +0100
Subject: [PATCH 2/9] Add configuration section

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index d94878389..1c7149c8b 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -46,12 +46,22 @@ Also remove auto opening of `RescriptCore`.
 Some typical name changes include:
 
 `Error.t` -> `JsError.t`
-`raise(` ->  `throw(`
+`raise(` -> `throw(`
 `Js.Exn.Error` exception -> `JsExn`
 `Error.make` -> `JsExn.make`
 `Error.raise` -> `JsExn.raise`
-`Error.message` -> `JsExn.message` 
- `Int.Bitwise.lsl` -> `Int.shiftLeft`
+`Error.message` -> `JsExn.message`
+`Int.Bitwise.lsl` -> `Int.shiftLeft`
 
+## 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`)

From d13222a4707f5231916ba3a17daee27018a0b028 Mon Sep 17 00:00:00 2001
From: nojaf <florian.verdonck@outlook.com>
Date: Tue, 11 Nov 2025 14:46:10 +0100
Subject: [PATCH 3/9] Moar migrate stuff

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 123 ++++++++++++++++++-
 1 file changed, 122 insertions(+), 1 deletion(-)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index 1c7149c8b..3ac834cae 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -14,6 +14,7 @@ canonical: "/docs/manual/v12.0.0/migrate-to-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).
 - 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
 
@@ -41,18 +42,108 @@ Also remove auto opening of `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(` -> `throw(`
+`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 <root>
+
+# preview the changes via
+rescript-tools migrate <file> [--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:
@@ -65,3 +156,33 @@ Rename `bsconfig.json` to `rescript.json` and update these configuration options
 
 - 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
+```

From 4641f485c6f32dd3c30686a8ac4acace143bbfba Mon Sep 17 00:00:00 2001
From: nojaf <florian.verdonck@outlook.com>
Date: Tue, 11 Nov 2025 18:04:44 +0100
Subject: [PATCH 4/9] Correct jsx children spread sample

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index 3ac834cae..46108c12c 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -103,7 +103,7 @@ v11:
 v12:
 
 ```res
-<div> {...children} </div>
+<div> children </div>
 ```
 
 ### Attributes

From edef13f24d4dfb7fdf503133cc068a7203a3647c Mon Sep 17 00:00:00 2001
From: nojaf <florian.verdonck@outlook.com>
Date: Tue, 11 Nov 2025 18:06:28 +0100
Subject: [PATCH 5/9] Ask users for help

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index 46108c12c..c921f7785 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -6,6 +6,8 @@ canonical: "/docs/manual/v12.0.0/migrate-to-v12"
 
 # Migrate to ReScript 12
 
+If you encounter any missing information or issues during migration, please [open an issue](https://github.com/rescript-lang/rescript-lang.org/issues/new?template=documentation_issue.md) or, even better, [send a pull request](https://github.com/rescript-lang/rescript-lang.org/) to help improve this guide.
+
 ## Recommended Migration
 
 ### Prerequisites

From 59f22a364dd33a8887cacf5270fc3814c9059f66 Mon Sep 17 00:00:00 2001
From: nojaf <florian.verdonck@outlook.com>
Date: Tue, 11 Nov 2025 19:41:09 +0100
Subject: [PATCH 6/9] Add page to sidebar

---
 data/sidebar_manual_v1200.json | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/data/sidebar_manual_v1200.json b/data/sidebar_manual_v1200.json
index 24b37f62e..3db722c89 100644
--- a/data/sidebar_manual_v1200.json
+++ b/data/sidebar_manual_v1200.json
@@ -1,5 +1,11 @@
 {
-  "Overview": ["introduction", "installation", "editor-plugins", "llms"],
+  "Overview": [
+    "introduction",
+    "installation",
+    "migrate-to-v12",
+    "editor-plugins",
+    "llms"
+  ],
   "Guides": ["converting-from-js", "editor-code-analysis", "project-structure"],
   "JavaScript Interop": [
     "interop-cheatsheet",

From 84aa1aad6b43cd1502b14a0243ee7051a43a4d10 Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <florianh89@gmail.com>
Date: Fri, 14 Nov 2025 00:21:24 +0100
Subject: [PATCH 7/9] Add section about converting ml files

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 29 +++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index c921f7785..5a2897d99 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -14,7 +14,7 @@ If you encounter any missing information or issues during migration, please [ope
 
 - 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).
+- 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
 
@@ -188,3 +188,30 @@ rescript watch
 # format
 rescript format
 ```
+
+## Converting generated `.ml` files
+
+Some projects still rely on tools such as `atdgen` that emit OCaml `.ml` files. ReScript 12 cannot compile those files directly, so you must keep using ReScript 11 **only** to convert the generated `.ml` files back to `.res` files before you run the v12 build.
+
+1. Keep ReScript 12 as the sole compiler dependency in your main project (i.e. `devDependencies.rescript` stays at `^12.0.0`).
+
+2. Install ReScript 11 in a dedicated subfolder (so its binaries never replace the v12 ones in `node_modules/.bin`). A simple option is to store it under a subfolder, e.g. `tools` (if you're using workspaces, keep this folder out of the root workspace list so hoisting can't swap the v12 shims):
+
+`cd` into `tools` and run `npm create rescript-app` and select the basic template and a v11 version of ReScript. You can name it `rescript-11` for instance.
+
+3. `cd` back into the root of your project and add a helper script that references the compiler from that folder (adapt the path accordingly):
+
+   ```json
+   {
+     "scripts": {
+       "convert-ml": "tools/rescript-11/node_modules/.bin/rescript convert src/*.ml"
+     }
+   }
+   ```
+
+4. Execute the helper script to convert your `.ml` files to `.res` files: 
+```console
+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/).

From dca31f6976f8d5a71505b4e85894367e90b06d98 Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <florianh89@gmail.com>
Date: Fri, 14 Nov 2025 00:34:29 +0100
Subject: [PATCH 8/9] Breaking changes

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 47 ++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index 5a2897d99..8a6e43110 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -215,3 +215,50 @@ 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/).
+
+## List of all breaking changes
+
+Below is a consolidated excerpt of all the breaking changes from the compiler changelog.
+
+### Language & syntax
+
+- Tag functions named `j` or `js` are no longer reserved, so add your own implementation whenever a tagged template expects them. https://github.com/rescript-lang/rescript-compiler/pull/6817
+- `lazy` syntax was removed; use the `Lazy` module or `React.lazy_` instead. https://github.com/rescript-lang/rescript-compiler/pull/6342
+- All legacy `@bs.*` attributes (e.g. `@bs.as`, `@bs.send`) and `@bs.open` were removed; use their prefix-free successors (`@as`, `@send`, `@open`, …). https://github.com/rescript-lang/rescript-compiler/pull/6643 https://github.com/rescript-lang/rescript-compiler/pull/6629
+- `@bs.send.pipe` was removed, together with the helper functions in `Js_typed_array` that relied on it; rewrite bindings to use explicit piping. https://github.com/rescript-lang/rescript-compiler/pull/6858 https://github.com/rescript-lang/rescript-compiler/pull/6891
+- OCaml `.ml` files are no longer supported anywhere: `.ml` parsing/formatting went away and the `rescript convert` CLI was removed, so convert legacy files to `.res` before upgrading. https://github.com/rescript-lang/rescript-compiler/pull/6848 https://github.com/rescript-lang/rescript-compiler/pull/6852 https://github.com/rescript-lang/rescript-compiler/pull/6860
+- The `%time` extension and the `caml_external_polyfill` module were deleted. https://github.com/rescript-lang/rescript-compiler/pull/6924 https://github.com/rescript-lang/rescript-compiler/pull/6925
+- Some global names and old keywords are no longer automatically prefixed during JS emission; update any code that was relying on the mangled names. https://github.com/rescript-lang/rescript-compiler/pull/6831
+- JSX v3 and the `-bs-jsx-mode` option were removed and JSX children spreads are no longer valid; JSX v4 semantics are now the only supported mode. https://github.com/rescript-lang/rescript-compiler/pull/7072 https://github.com/rescript-lang/rescript/pull/7327 https://github.com/rescript-lang/rescript/pull/7869
+- Bitwise operators switched to the F#-style spellings `~~~`, `^^^`, `&&&`, `|||`; the previous `~`, `^`, `&`, `|` tokens are no longer accepted. https://github.com/rescript-lang/rescript/pull/7894
+
+### Standard library & runtime
+
+- OCaml compatibility layers in the stdlib and primitives were removed/deprecated. https://github.com/rescript-lang/rescript-compiler/pull/6984
+- Deprecated modules `Js.Vector` and `Js.List` were deleted. https://github.com/rescript-lang/rescript-compiler/pull/6900
+- The legacy `js_cast.res` helpers disappeared; migrate to explicit externals. https://github.com/rescript-lang/rescript-compiler/pull/7075
+- `JsError` and related modules were renamed/cleaned up under `JsExn`. https://github.com/rescript-lang/rescript/pull/7408
+- `BigInt.fromFloat` now returns `option` and exposes `BigInt.fromFloatOrThrow`, and the `Exn`-suffixed helpers across `Bool`, `BigInt`, `JSON`, `Option`, `Null`, `Nullable`, `Result`, and `List` now end with `OrThrow`. https://github.com/rescript-lang/rescript/pull/7419 https://github.com/rescript-lang/rescript/pull/7518 https://github.com/rescript-lang/rescript/pull/7554
+- `Result.getOrThrow` throws a JS `Error` (instead of `Not_found`), and `Result.equal` / `Result.compare` now provide a comparison function for `Error` values. https://github.com/rescript-lang/rescript/pull/7630 https://github.com/rescript-lang/rescript/pull/7933
+- `Iterator.forEach` now emits `Iterator.prototype.forEach`. https://github.com/rescript-lang/rescript/pull/7506
+- `Date.make` uses `~day` instead of `~date`. https://github.com/rescript-lang/rescript/pull/7324
+- Plain `int` multiplication is implemented as a regular int32 operation instead of `Math.imul`. https://github.com/rescript-lang/rescript/pull/7358
+- The `List` API was cleaned up—several functions were renamed or removed (see the PR for the exact surface). https://github.com/rescript-lang/rescript/pull/7290
+- `String.getSymbol` / `String.setSymbol` were removed; only `String.getSymbolUnsafe` remains on strings. https://github.com/rescript-lang/rescript/pull/7571 https://github.com/rescript-lang/rescript/pull/7626
+- `String.charCodeAt` now returns `option<int>` and exposes `String.charCodeAtUnsafe` for unchecked access. https://github.com/rescript-lang/rescript/pull/7877
+- Runtime files now live in the `@rescript/runtime` package and the legacy `@rescript/std` package was removed, so ensure `@rescript/runtime` is installed wherever you depend on the compiler. https://github.com/rescript-lang/rescript/pull/7796 https://github.com/rescript-lang/rescript/pull/7811
+- `Intl.*.supportedLocalesOf` bindings now return `array<string>` and the non-portable `Intl.PluralRules.selectBigInt` / `selectRangeBigInt` were removed. https://github.com/rescript-lang/rescript/pull/7995
+
+### 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
+- `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
+
+### Configuration & platform
+
+- 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

From 96f546f1f26915b39c675f2b3e4f2896c01bb399 Mon Sep 17 00:00:00 2001
From: Florian Hammerschmidt <florianh89@gmail.com>
Date: Fri, 14 Nov 2025 00:34:54 +0100
Subject: [PATCH 9/9] format

---
 pages/docs/manual/v12.0.0/migrate-to-v12.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
index 8a6e43110..414693307 100644
--- a/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
+++ b/pages/docs/manual/v12.0.0/migrate-to-v12.mdx
@@ -209,7 +209,8 @@ Some projects still rely on tools such as `atdgen` that emit OCaml `.ml` files.
    }
    ```
 
-4. Execute the helper script to convert your `.ml` files to `.res` files: 
+4. Execute the helper script to convert your `.ml` files to `.res` files:
+
 ```console
 npm run convert-ml
 ```