rescript-lang · jderochervlk · Nov 21, 2025 · Nov 21, 2025 · Nov 21, 2025 · fhammerschmidt
diff --git a/app/root.res b/app/root.res
@@ -52,28 +52,29 @@ let default = () => {
   <html>
     <head>
       <style> {React.string("html {opacity:0;}")} </style>
-      <link rel="preload" href={mainCss} as_="style" />
+      // preloading causes issues in dev mode with HMR
+      {Env.dev ? React.null : <link rel="preload" href={mainCss} as_="style" />}
       <link rel="stylesheet" href={mainCss} />
       <link rel="stylesheet" href={hljsCss} />
       <link rel="stylesheet" href={utilsCss} />
       <link rel="icon" href="/favicon.ico" />
-      <Links />
-      <Meta />
       <meta
         name="viewport"
         content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, minimal-ui"
       />
       <meta charSet="UTF-8" />
+      <Meta />
+      <Links />
     </head>
     <body className={isScrollLockEnabled ? "overflow-hidden" : ""}>
       <ScrollLockContext.Provider lockState=(isScrollLockEnabled, setIsScrollLockEnabled)>
         <EnableCollapsibleNavbar isEnabled={!isOverlayOpen}>
           <Navigation isOverlayOpen setOverlayOpen />
           <Outlet />
           <ScrollRestoration />
-          <Scripts />
         </EnableCollapsibleNavbar>
       </ScrollLockContext.Provider>
+      <Scripts />
     </body>
   </html>
 }
diff --git a/markdown-pages/docs/manual/api.mdx b/markdown-pages/docs/manual/api.mdx
@@ -9,11 +9,8 @@ canonical: "/docs/manual/api"
 
 ## Stdlib
 
-[Stdlib](/docs/manual/api/stdlib) 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.
-
-In ReScript 11, it was shipped as a separate npm package `@rescript/core`.
-
-Since Rescript 12, it is now included with the `rescript` npm package itself.
+[Stdlib](/docs/manual/api/stdlib) is ReScript's new builtin standard library.
+It will cover just about you need for day-to-day programming in ReScript and covers most of the built in JavaScript API.
 
 ## Additional Libraries
 

diff --git a/markdown-pages/docs/manual/build-configuration.mdx b/markdown-pages/docs/manual/build-configuration.mdx
@@ -9,7 +9,7 @@ order: 2
 
 # Configuration
 
-`rescript.json` (or `bsconfig.json` in versions prior ReScript 11) is the single, mandatory build meta file needed for `rescript`.
+`rescript.json` is the single, mandatory build meta file needed for `rescript`.
 
 **The complete configuration schema is [here](./build-configuration-schema.mdx)**. We'll _non-exhaustively_ highlight the important parts in prose below.
 
@@ -173,18 +173,6 @@ Generating JS files with the `.res.js` suffix means that, on the JS side, you ca
 - It avoids clashes with a potential `TheFile.js` file in the same folder.
 - It avoids the need of using a build system loader for ReScript files. This + in-source build means integrating a ReScript project into your pure JS codebase **basically doesn't touch anything in your build pipeline at all**.
 
-## uncurried
-
-**Since 11.0**: While we strongly encourage all users to use uncurried mode, it is still possible to opt out. Just set `"uncurried"` to `false` to get the old behavior back:
-
-```json
-{
-  "uncurried": false
-}
-```
-
-We've also published a blog post on the [transition to the new uncurried mode by default](../../blog/uncurried-mode.mdx).
-
 ## warnings
 
 Selectively turn on/off certain warnings and/or turn them into hard errors. Example:
@@ -238,12 +226,6 @@ To enable genType, set `"gentypeconfig"` at top level in the project's `rescript
 
 `debug`: Enable debug logs.
 
-### Deprecated options
-
-`language`: the `language` setting is not required from compiler v10.1.
-
-`shims`: Required only if one needs to export certain basic ReScript data types to JS when one cannot modify the sources to add annotations (e.g. exporting ReScript lists), and if the types are not first-classed in genType.
-
 ## Environment Variables
 
 We heavily disrecommend the usage of environment variables, but for certain cases, they're justified.

diff --git a/markdown-pages/docs/manual/build-monorepo-setup.mdx b/markdown-pages/docs/manual/build-monorepo-setup.mdx
@@ -11,7 +11,7 @@ canonical: "/docs/manual/build-monorepo-setup"
 
 > A monorepo is a single repository containing multiple separate projects, with clear relationships between them.
 
-ReScript 12.0 introduces improved support for native monorepos through the new "Rewatch" build system. This guide walks you through the setup process.
+ReScript 12.0 introduces improved support for native monorepos through the new ["Rewatch"](../../blog/reforging-build-system.mdx) build system. This guide walks you through the setup process.
 
 **Note:** This feature requires the new build system and is **not compatible** with `rescript-legacy`.
 

diff --git a/markdown-pages/docs/manual/editor-plugins.mdx b/markdown-pages/docs/manual/editor-plugins.mdx
@@ -39,7 +39,7 @@ The code analysis provides extra checks for your ReScript project, such as detec
 
 ### Configuration
 
-Add a `reanalyze` section to your `rescript.json` to control what the analyzer checks or ignores. You’ll get autocomplete for config options in the editor.  
+Add a `reanalyze` section to your `rescript.json` to control what the analyzer checks or ignores. You'll get autocomplete for config options in the editor.  
 More details: [reanalyze config docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson)
 
 ### Exception analysis

diff --git a/markdown-pages/docs/manual/exception.mdx b/markdown-pages/docs/manual/exception.mdx
@@ -473,7 +473,7 @@ let BadArgument = /* @__PURE__ */ Primitive_exceptions.create(
 
 function myTest() {
   throw {
-    RE_EXN_ID: BadArgument,
+    RE_EXN_ID: BadArgument, // `RE_EXN_ID` is an internal API and you should NEVER try and access it from JavaScript
     myMessage: "Oops!",
     Error: new Error(),
   };
@@ -494,8 +494,6 @@ try {
 }
 ```
 
-> Note: `RE_EXN_ID` is an internal field for bookkeeping purposes. Don't use it on the JS side. Use the other fields.
-
 The above `BadArgument` exception takes an inline record type. We special-case compile the exception as `{RE_EXN_ID, myMessage, Error}` for good ergonomics. If the exception instead took ordinary positional arguments, l like the standard library's `Invalid_argument("Oops!")`, which takes a single argument, the argument is compiled to JS as the field `_1` instead. A second positional argument would compile to `_2`, etc.
 
 ## Tips & Tricks

diff --git a/markdown-pages/docs/manual/installation.mdx b/markdown-pages/docs/manual/installation.mdx
@@ -10,8 +10,8 @@ order: 2
 
 ## Prerequisites
 
-<div class="install-list">
-- [Node.js](https://nodejs.org/) version >= 20 
+<div className="install-list">
+- [Node.js](https://nodejs.org/) version >= 22
 - One of the following package managers: 
   - [npm](https://docs.npmjs.com/cli/) (comes with Node.js) 
   - [yarn](https://yarnpkg.com/) 
@@ -54,10 +54,12 @@ bun create rescript-app
 
 - Follow the steps of the setup.
 - Trigger a ReScript build:
+
   ```sh
   npm run res:build
   ```
 - If you selected the "basic" template, simply run it with:
+
   ```sh
   node src/Demo.res.mjs
   ```

diff --git a/markdown-pages/docs/manual/module.mdx b/markdown-pages/docs/manual/module.mdx
@@ -579,7 +579,7 @@ It is possible to use non-conventional characters in your filenames (which is so
 - `src/Button.ios.res`
 - `pages/[id].res`
 
-Please note that modules with an exotic filename will not be accessible from other ReScript modules.
+Please note that modules with an exotic filename will not be accessible from other ReScript modules and will only produce JavaScript files.
 
 ## Tips & Tricks
 

diff --git a/markdown-pages/docs/manual/pattern-matching-destructuring.mdx b/markdown-pages/docs/manual/pattern-matching-destructuring.mdx
@@ -504,8 +504,6 @@ if (person1.TAG) {
 
 </CodeTab>
 
-**Note:** Rescript versions < 9.0 had a `when` clause, not an `if` clause.  Rescript 9.0 changed `when` to `if`.  (`when` may still work, but is deprecated.)
-
 ### Match on subtype variants
 
 You can refine a variant A to variant B using the [variant type spread syntax](./variant.mdx#variant-type-spreads) in pattern matching. This is possible if variant B [is a subtype of](./variant.mdx#coercion) variant A.

diff --git a/markdown-pages/docs/manual/pipe.mdx b/markdown-pages/docs/manual/pipe.mdx
@@ -250,11 +250,3 @@ namePerson(personDetails, __x);
 ```
 
 </CodeTab>
-
-## Triangle Pipe (Deprecated)
-
-You might see usages of another pipe, `|>`, in some codebases. These are deprecated.
-
-Unlike `->` pipe, the `|>` pipe puts the subject as the last (not first) argument of the function. `a |> f(b)` turns into `f(b, a)`.
-
-For a more thorough discussion on the rationale and differences between the two operators, please refer to the [Data-first and Data-last comparison by Javier Chávarri](https://www.javierchavarri.com/data-first-and-data-last-a-comparison/)
diff --git a/markdown-pages/docs/manual/promise.mdx b/markdown-pages/docs/manual/promise.mdx
@@ -14,7 +14,7 @@ order: 21
 
 **Since 10.1**
 
-In ReScript, every JS promise is represented with the globally available `promise<'a>` type. For ReScript versions < 10.1, use its original alias `Js.Promise.t<'a>` instead.
+In ReScript, every JS promise is represented with the globally available `promise<'a>` type.
 
 Here's a usage example in a function signature:
 
@@ -36,8 +36,6 @@ A builtin module to create, chain and manipulate promises.
 
 ```res
 let p1 = Promise.make((resolve, reject) => {
-  // We use uncurried functions for resolve / reject
-  // for cleaner JS output without unintended curry calls
   resolve("hello world")
 })
 
@@ -113,69 +111,3 @@ export { logAsyncMessage };
 ```
 
 </CodeTab>
-
-## Js.Promise module (legacy - do not use)
-
-> **Note:** The `Js.Promise` bindings are following the outdated data-last convention from a few years ago. We kept those APIs for backwards compatibility. Either use [`Promise`](/docs/manual/api/stdlib/promise) or a third-party promise binding instead.
-
-ReScript has built-in support for [JavaScript promises](/docs/manual/api/stdlib/promise). The 3 functions you generally need are:
-
-- `Js.Promise.resolve: 'a => Js.Promise.t<'a>`
-- `Js.Promise.then_: ('a => Js.Promise.t<'b>, Js.Promise.t<'a>) => Js.Promise.t<'b>`
-- `Js.Promise.catch: (Js.Promise.error => Js.Promise.t<'a>, Js.Promise.t<'a>) => Js.Promise.t<'a>`
-
-Additionally, here's the type signature for creating a promise on the ReScript side:
-
-```res
-Js.Promise.make: (
-  (
-    ~resolve: (. 'a) => unit,
-    ~reject: (. exn) => unit
-  ) => unit
-) => Js.Promise.t<'a>
-```
-
-This type signature means that `make` takes a callback that takes 2 named arguments, `resolve` and `reject`. Both arguments are themselves [uncurried callbacks](./function.mdx#uncurried-function) (with a dot). `make` returns the created promise.
-
-### Usage
-
-Using the [pipe operator](./pipe.mdx):
-
-<CodeTab labels={["ReScript", "JS Output"]}>
-
-```res example
-let myPromise = Js.Promise.make((~resolve, ~reject) => resolve(. 2))
-
-myPromise->Js.Promise.then_(value => {
-  Console.log(value)
-  Js.Promise.resolve(value + 2)
-}, _)->Js.Promise.then_(value => {
-  Console.log(value)
-  Js.Promise.resolve(value + 3)
-}, _)->Js.Promise.catch(err => {
-  Console.log2("Failure!!", err)
-  Js.Promise.resolve(-2)
-}, _)
-```
-
-```js
-var myPromise = new Promise(function (resolve, reject) {
-  return resolve(2);
-});
-
-myPromise
-  .then(function (value) {
-    console.log(value);
-    return Promise.resolve((value + 2) | 0);
-  })
-  .then(function (value) {
-    console.log(value);
-    return Promise.resolve((value + 3) | 0);
-  })
-  .catch(function (err) {
-    console.log("Failure!!", err);
-    return Promise.resolve(-2);
-  });
-```
-
-</CodeTab>
diff --git a/markdown-pages/docs/manual/typescript-integration.mdx b/markdown-pages/docs/manual/typescript-integration.mdx
@@ -264,19 +264,6 @@ export type inputFocusEvent = React.FocusEvent<HTMLInputElement>;
 
 More complete example shims can be found [here](https://github.com/rescript-lang/rescript-compiler/blob/master/jscomp/gentype_tests/typescript-react-example/src/shims/).
 
-## Deprecated features
-
-Features related to generating runtimes were deprecated since v11 and should no longer be used.
-
-- **`@genType("alias")`** and **`@genType.as("alias")`**
-- **`@genType.opaque`**
-- **`@genType.import`**
-- TypeScript Shims
-
-genType does not generate anything runtime-related, and in the near future it generates definition files (`*.d.ts`) directly (See the [roadmap](https://github.com/rescript-lang/rescript-compiler/issues/6196)).
-
-If any runtime code is required for interoperability with JavaScript / TypeScript projects, it can be written by hand, or request a relevant features (e.g. `@deriving`) to the compiler.
-
 ## Limitations
 
 - **in-source = true**. Currently only supports ReScript projects with [in-source generation](./build-configuration.mdx#package-specs) and file suffixes that end on `.js`, like `.res.js` or `.bs.js`.

diff --git a/markdown-pages/docs/react/hooks-effect.mdx b/markdown-pages/docs/react/hooks-effect.mdx
@@ -313,4 +313,4 @@ let make = (~friendId: string) => {
 
 If you want to run an effect and clean it up only once (on mount and unmount), use `React.useEffect` with an empty dependency array `[]`.
 
-If you are interested in more performance optmization related topics, have a look at the ReactJS [Performance Optimization Docs](https://reactjs.org/docs/hooks-faq.html#performance-optimizations) for more detailed infos.
+If you are interested in learning about performance optimization related topics, have a look at the ReactJS [improving application performance](https://react.dev/learn/build-a-react-app-from-scratch#improving-application-performance) for more detailed infos.
diff --git a/markdown-pages/docs/react/hooks-overview.mdx b/markdown-pages/docs/react/hooks-overview.mdx
@@ -107,7 +107,7 @@ Hooks are just simple functions, but you need to follow _two rules_ when using t
 
 ### Rule 1) Only Call Hooks at the Top Level
 
-**Don’t call Hooks inside loops, conditions, or nested functions.** Instead, always use Hooks at the top level of your React function. By following this rule, you ensure that Hooks are called in the same order each time a component renders. That’s what allows React to correctly preserve the state of Hooks between multiple `useState` and `useEffect` calls. (If you’re curious, you can check out the in depth explanation in the [ReactJS Hooks docs](https://reactjs.org/docs/hooks-rules.html#explanation))
+**Don’t call Hooks inside loops, conditions, or nested functions.** Instead, always use Hooks at the top level of your React function. By following this rule, you ensure that Hooks are called in the same order each time a component renders. That’s what allows React to correctly preserve the state of Hooks between multiple `useState` and `useEffect` calls. (If you’re curious, you can check out the in depth explanation in the [ReactJS Rules of Hooks docs](https://react.dev/reference/rules/rules-of-hooks))
 
 ### Rule 2) Only Call Hooks from React Functions
 

diff --git a/markdown-pages/docs/react/installation.mdx b/markdown-pages/docs/react/installation.mdx
@@ -51,21 +51,3 @@ After a successful installation, `@rescript/react` will make the following modul
 - `ReactDOMStyle`: Bindings to the inline style API
 - `RescriptReactRouter`: A simple, yet fully featured router with minimal memory allocations
 - `RescriptReactErrorBoundary`: A component which handles errors thrown in its child components gracefully
-
-## Automatic vs. Classic Mode
-
-By default, JSX v4 uses the new JSX runtime (`react/jsx-runtime`) introduced in React 17. This is called "automatic mode", and can also be specified explicitly like this:
-
-```json
-{
-  "jsx": { "version": 4, "mode": "automatic" }
-}
-```
-
-To keep using the legacy `React.createElement` API (like with JSX v3), you can activate classic mode instead:
-
-```json
-{
-  "jsx": { "version": 4, "mode": "classic" }
-}
-```
diff --git a/markdown-pages/syntax-lookup/decorator_obj.mdx b/markdown-pages/syntax-lookup/decorator_obj.mdx
diff --git a/markdown-pages/syntax-lookup/decorator_uncurried.mdx b/markdown-pages/syntax-lookup/decorator_uncurried.mdx
Original file line number	Diff line number	Diff line change
Expand Up		@@ -313,4 +313,4 @@ let make = (~friendId: string) => {

		If you want to run an effect and clean it up only once (on mount and unmount), use `React.useEffect` with an empty dependency array `[]`.

		If you are interested in more performance optmization related topics, have a look at the ReactJS [Performance Optimization Docs](https://reactjs.org/docs/hooks-faq.html#performance-optimizations) for more detailed infos.
		If you are interested in learning about performance optimization related topics, have a look at the ReactJS [improving application performance](https://react.dev/learn/build-a-react-app-from-scratch#improving-application-performance) for more detailed infos.