Fine-tuning

Author: fhammerschmidt

markdown-pages/blog/release-12-0-0.mdx

@@ -20,92 +20,36 @@ The new tooling provides focused commands, better diagnostics, and smaller downl
 
 You can find the complete migration guide [here](../docs/manual/migrate-to-v12.mdx).
 
-## Breaking Changes
+## New Features
 
-### Build system redesign
+### New Build System
 
 ReScript 12 ships with the new build system introduced earlier this month in the [Reforging the Build System](./reforging-build-system.mdx) preview.
-The tooling now relies on a modern architecture that tracks dependencies more precisely, avoids unnecessary recompilations, and integrates with incremental workflows.
-The old build system remains available through `rescript-legacy`, but active projects should switch to the new commands to benefit from faster feedback loops and clearer output.
-
-### Runtime package split
-
-The compiler no longer embeds runtime modules.
-Instead, the runtime lives in the dedicated `@rescript/runtime` npm package, which contains Belt, Stdlib, Js, primitive modules, and supporting artifacts compiled in both ES Module and CommonJS formats.
-Earlier versions bundled these files inside the `rescript` package and exposed an optional `@rescript/std` helper.
-ReScript 12 removes `@rescript/std`; install `rescript` and `@rescript/runtime` together to keep projects in sync.
-Projects that previously published custom runtime shims should revisit their setup to ensure the new package structure remains discoverable.
-
-### Bitwise operators
-
-ReScript now supports F#-style bitwise operators `&&&` (AND), `|||` (OR), `^^^` (XOR), and `~~~` (NOT) for both `int` and `bigint`.
-Legacy OCaml-style bitwise functions such as `land`, `lor`, and `lsl` are deprecated.
-
-### API naming alignment
-
-APIs that previously ended with `Exn` now end with `OrThrow`.
-Examples include `Option.getOrThrow`, `List.headOrThrow`, `BigInt.fromStringOrThrow`, and `JSON.parseOrThrow`.
-The change clarifies that these functions throw JavaScript errors, aligning the naming with the language’s semantics.
-The deprecated `*Exn` variants remain available in v12 to ease the transition, and the codemod bundled with the migration tool can perform a mechanical rename.
-Note that `Result.getOrThrow` now throws a JavaScript exception, so please update any exception-handling logic that relied on OCaml exception names. We also revamped the API around JS exceptions and errors.
-
-We’ve renamed JS errors to `JsError.t` to better distinguish them from the `Result.Error` variant. Since JavaScript allows throwing anything (not only proper Error objects), the previous way of catching JS exceptions was unsafe:
-
-```res
-let foo = switch myUnsafeJsResult() {
-| exception Exn.Error(e) => Error(e->Error.message)
-  // ☝️ this will crash if `e` is undefined or null
-| myRes => Ok(myRes)
-}
-```
-
-Additionally, the coexistence of `Result.Error` and the `Error` module caused confusion.
-
-The new recommended pattern is:
-
-```res
-let foo = switch myUnsafeJsResult() {
-| exception JsExn(e) => Error(e->JsExn.message))
-// ☝️ this is now safe even `e` is undefined or null
-| myRes => Ok(myRes)
-}
-```
-
-Utility helpers for working with JS errors are now in `JsError`, eg:
+The tooling now relies on a modern architecture that tracks dependencies more precisely, avoids unnecessary recompilations, and integrates with incremental workflows even across monorepo packages.
 
-```res
-JsError.throw(JsError.RangeError.make("the payload should be below 16"))
-```
+### Improved Standard Library
 
-### JSX version requirement
+The new standard library [`@rescript/core`](https://github.com/rescript-lang/rescript-core) is now included in the compiler runtime. So you can get rid if the dependency on `@rescript/core` in your projects. To avoid collisions we have named the new internal library just `Stdlib`, so you can keep using it alongside `Core` if you cannot migrate yet. There have been tons of additions as well, so you can shrink your `Utils` files down a bit. Check it out here: [Stdlib](../docs/manual/api/stdlib).
 
-JSX v3 has been removed.
-ReScript 12 requires JSX v4 configuration in `rescript.json`, using the `"jsx": { "version": 4 }` schema.
-ReScript React projects must update their configuration before moving to v12.
-Projects attempting to compile with v3 will receive an explicit error, ensuring that your codebase uses the current transform and associated tooling.
+### Operator Improvements
 
-### Deprecation of OCaml compatibility helpers
+#### Unified Operators
 
-The standard library continues its shift away from OCaml-specific aliases.
-Functions such as `succ`, `pred`, `abs_float`, `string_of_int`, `fst`, `raise`, and the `char` type are now deprecated.
-The recommended replacements are the JavaScript-aligned counterparts in `Int`, `Float`, `Bool`, `Pair`, and related modules, alongside the `throw` keyword for exceptions.
-References to the OCaml composition operators (`|>`, `@@`) now warn and will be removed in a future version; the ReScript pipe operator `->` replaces them.
-The migration tool highlights deprecated usage, and incremental cleanups are encouraged so your codebase is ready before the next major release.
+ReScript 12 finalizes the unified operator work introduced [earlier this year](./introducing-unified-operators.mdx).
+Arithmetic operators (`+`, `-`, `*`, `/`, and the newly added `%` and `**`) now work consistently for `int`, `float` and `bigint`, allowing the compiler to infer the correct specialization from the left operand. You can ditch all the `+.`, `-.`, `*.`, and `/.` now! 
 
-## New features
+In addition you can also now use `+` for string concatenation, while `++` still works as before.
 
-### Unified operators
+#### Bitwise Operators
 
-ReScript 12 finalizes the unified operator work introduced [earlier this year](./introducing-unified-operators.mdx).
-Arithmetic, comparison, and bitwise operators now behave consistently across `int` and `bigint`, allowing the compiler to infer the correct specialization from the left operand.
+ReScript now supports F#-style bitwise operators `&&&` (AND), `|||` (OR), `^^^` (XOR), and `~~~` (NOT) for both `int` and `bigint`.
+Legacy OCaml-style bitwise functions such as `land`, `lor`, and `lsl` are deprecated.
 
-### Expanded bitwise capabilities
+#### Shift Operators
 
-In addition to deprecating the OCaml-style helpers, ReScript 12 adds new operator spellings.
-JavaScript-style bitwise operators (`&`, `|`, `^`, `~`) and shift operators (`<<`, `>>`, `>>>`) are first-class citizens that compile directly to their JavaScript equivalents.
-Combined with the unified F#-style operators, developers can select the syntax that best fits their code policies without sacrificing performance or type safety.
+For shift operators there was luckily no conflict in the character space, which means ReScript now supports `<<` (logical left shift), `>>` (logical right shift) and `>>>` (unsigned right shift), just like JavaScript.
 
-### Dict literals and pattern matching
+### Dict Literals and Pattern Matching
 
 The language now supports dictionary literals (`dict{"foo": "bar"}`) that compile to plain JavaScript objects.
 Dict literals work with variables, multi-line formatting, and optional entries, and they drastically reduce the boilerplate compared to `Dict.fromArray`.
@@ -121,9 +65,9 @@ switch user {
 }
 ```
 
-### Nested and inline record types
+### Nested Record Types
 
-Nested record definitions and inline record payloads remove the need for auxiliary type declarations.
+Nested record definitions remove the need for auxiliary type declarations.
 You can define optional nested structures directly inside records, or attach record payloads to variant constructors without creating standalone types.
 The feature supports mutable fields, type parameters, and record spreading, providing better locality for complex domain models with no runtime penalty.
 
@@ -137,7 +81,7 @@ type profile = {
 }
 ```
 
-### Variant pattern spreads
+### Variant Pattern Spreads
 
 Pattern spreads (`| ...SomeVariant as value =>`) allow you to reuse handlers for entire subsets of constructors.
 When a variant extends another variant through spreads, you can match the shared constructors in one branch and delegate to helper functions, keeping exhaustive matches concise even as the hierarchy grows.
@@ -154,22 +98,23 @@ let handle = (event: extended) =>
   }
 ```
 
-### JSX preserve mode
+### JSX Preserve Mode
 
 Projects that rely on downstream JSX tooling can enable [preserve mode](../docs/manual/jsx.mdx#preserve-mode) via `"jsx": { "version": 4, "preserve": true }`.
 The compiler will emit JSX syntax directly instead of transforming elements to `react/jsx-runtime` calls, allowing bundlers such as ESBuild, SWC, or Babel to apply their own transforms.
-This mode keeps JSX readable in the output, retains spread props, and maintains compatibility with React Server Components.
+This mode keeps JSX readable in the output and maintains compatibility with React Compiler.
+
 React classic mode is no longer supported, so projects must use the JSX v4 transform regardless of preserve mode settings.
 When preserve mode is disabled, the compiler continues to output the optimized runtime calls you are accustomed to.
 
-### Function-level directives
+### Function-Level Directives
 
 The new `@directive` attribute emits JavaScript directive strings at the top of generated functions.
 Use it to mark server actions with `'use server'`, memoized handlers with `'use memo'`, or any other directive that your framework requires.
 The attribute works on synchronous and asynchronous functions, supports labeled parameters, and removes the need for `%raw` blocks.
 Combined with JSX preserve mode, this enables clean integration with [React Server Components](../docs/react/server-components.mdx) and other directive-based runtimes.
 
-### Regex literals
+### Regex Literals
 
 ReScript now understands JavaScript-style regular expression literals (`/pattern/flags`).
 They are full equivalents of `%re` expressions, supporting all ECMAScript flags, Unicode character classes, and sticky searches.
@@ -188,7 +133,7 @@ switch emailPattern->RegExp.exec("invalid") {
 }
 ```
 
-### Experimental `let?` syntax
+### Experimental `let?` Syntax
 
 This release introduces an experimental `let?` syntax for zero-cost unwrapping of `option` and `result` values.
 The syntax remains behind an opt-in flag while the community evaluates its ergonomics.
@@ -208,29 +153,91 @@ let userCity = (user: user): option<string> => {
 }
 ```
 
-## Platform and tooling improvements
+## Platform and Tooling Improvements
 
-### Cleaner JavaScript output
+### Cleaner JavaScript Output
 
 The printer now emits compact arrow functions and streamlines anonymous function expressions, making generated JavaScript easier to audit.
 These changes preserve semantics while aligning the output with modern JavaScript style.
 
-### Internal architecture updates
+### Internal Architecture Updates
 
 The compiler cleans up its internal abstract syntax tree, removes unused OCaml-era nodes, and tracks async and partial function metadata directly on AST nodes.
 These changes simplify future feature work and reduce maintenance overhead.
 
-### ESM-first distribution
+### ESM-First Distribution
 
 The `rescript` npm package declares `"type": "module"` and ships ESM code across the CLI.
 Import statements replace CommonJS `require` usage, improving compatibility with contemporary bundlers and enabling better tree-shaking.
 
-### Platform-specific binaries
+### Platform-Specific Binaries
 
 Installer footprints shrink thanks to platform-specific binary packages such as `@rescript/darwin-arm64`, `@rescript/linux-x64`, and `@rescript/win32-x64`.
 npm installs only the binary that matches your operating system and architecture, delivering substantially faster installs and smaller cache footprints for CI pipelines.
 The primary `rescript` package loads the appropriate binary at runtime and surfaces clear error messages if the matching package is missing.
 
+## Breaking Changes
+
+### Build System
+
+The old build system remains available through `rescript-legacy`, but active projects should switch to the new commands to benefit from faster feedback loops and clearer output.
+
+### Runtime Package Split
+
+The runtime modules were moved from the main `rescript` npm package to a dedicated `@rescript/runtime` npm package. It is automatically installed as a dependency of the main `rescript` package.
+The new `@rescript/runtime` package also replaces the standalone runtime package `@rescript/std` from earlier versions.
+
+### API Naming Alignment
+
+APIs that previously ended with `Exn` now end with `OrThrow`.
+Examples include `Option.getOrThrow`, `List.headOrThrow`, `BigInt.fromStringOrThrow`, and `JSON.parseOrThrow`.
+The change clarifies that these functions throw JavaScript errors, aligning the naming with the language’s semantics.
+The deprecated `*Exn` variants remain available in v12 to ease the transition, and the codemod bundled with the migration tool can perform a mechanical rename.
+Note that `Result.getOrThrow` now throws a JavaScript exception, so please update any exception-handling logic that relied on OCaml exception names. We also revamped the API around JS exceptions and errors.
+
+We’ve renamed JS errors to `JsError.t` to better distinguish them from the `Result.Error` variant. Since JavaScript allows throwing anything (not only proper Error objects), the previous way of catching JS exceptions was unsafe:
+
+```res
+let foo = switch myUnsafeJsResult() {
+| exception Exn.Error(e) => Error(e->Error.message)
+  // ☝️ this will crash if `e` is undefined or null
+| myRes => Ok(myRes)
+}
+```
+
+Additionally, the coexistence of `Result.Error` and the `Error` module caused confusion.
+
+The new recommended pattern is:
+
+```res
+let foo = switch myUnsafeJsResult() {
+| exception JsExn(e) => Error(e->JsExn.message))
+// ☝️ this is now safe even `e` is undefined or null
+| myRes => Ok(myRes)
+}
+```
+
+Utility helpers for working with JS errors are now in `JsError`, eg:
+
+```res
+JsError.throw(JsError.RangeError.make("the payload should be below 16"))
+```
+
+### JSX Version Requirement
+
+JSX v3 has been removed.
+ReScript 12 requires JSX v4 configuration in `rescript.json`, using the `"jsx": { "version": 4 }` schema.
+ReScript React projects must update their configuration before moving to v12.
+Projects attempting to compile with v3 will receive an explicit error, ensuring that your codebase uses the current transform and associated tooling.
+
+### Deprecation of OCaml Compatibility Helpers
+
+The standard library continues its shift away from OCaml-specific aliases.
+Functions such as `succ`, `pred`, `abs_float`, `string_of_int`, `fst`, `raise`, and the `char` type are now deprecated.
+The recommended replacements are the JavaScript-aligned counterparts in `Int`, `Float`, `Bool`, `Pair`, and related modules, alongside the `throw` keyword for exceptions.
+References to the OCaml composition operators (`|>`, `@@`) now warn and will be removed in a future version; the ReScript pipe operator `->` replaces them.
+The migration tool highlights deprecated usage, and incremental cleanups are encouraged so your codebase is ready before the next major release.
+
 ## Acknowledgments
 
 <Image
@@ -243,7 +250,7 @@ Thank you to every contributor, tester, and partner who helped shape ReScript 12
 The core team gathered in Vienna earlier this year to map out this release, and your feedback guided every decision.
 Community pull requests, bug reports, and experiments across the ecosystem gave us the confidence to complete large refactors and deprecations.
 
-## Reach out
+## Reach Out
 
 Join the conversation on the community forum if you have migration questions or want to share what you build with ReScript 12.
 Businesses that rely on ReScript can contact the association at https://rescript-association.org/contact to explore support, sponsorship, or collaboration.