ReScript: a typed language that compiles to readable JavaScript

The problem ReScript solves for JavaScript teams

JavaScript ships without a type checker, and TypeScript adds one on top of a language that was never designed for it. ReScript takes the opposite route: a small language with its own syntax, its own type system, and a compiler whose only output is JavaScript. The README puts the goal plainly, calling it a "robustly typed language that compiles to efficient and human-readable JavaScript", and the pitch is aimed at people who want types to be total rather than optional. The README states there is no `any`, no magic types, and no surprise `undefined` in a ReScript program.

The audience is narrower than "JavaScript developers". It is teams that already accept a build step, want the compiler to catch mistakes before CI, and care about the shape of the generated code because they may read it. The README also claims a compiler that "scales to any codebase size" and a feedback loop that stays fast when you refactor or switch branches. That is a claim about the toolchain rather than a measured result, and there is no benchmark in the repository to check it against.

How the compiler, runtime and rewatch fit together

The repository is a monorepo, and the top-level layout tells you the architecture before you read any source. `compiler/` holds the compiler itself, written in OCaml, which is the primary language of the repository. `rewatch/` is a separate directory, and the Makefile's default target is `build: compiler rewatch`, so the two are built together. `packages/` holds the published npm packages, including `packages/@rescript/runtime/` and `packages/@rescript/belt/`, and the Makefile references a per-platform binary directory at `packages/@rescript/$(RESCRIPT_PLATFORM)/bin`.

That platform variable is the interesting part. The Makefile derives `RESCRIPT_PLATFORM` from `uname` and `OS`, producing values like `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64` and `win32-x64`, and errors out on anything else. So the compiler is distributed as prebuilt binaries per platform rather than compiled from OCaml on the user's machine. The npm package exposes three binaries, `bsc`, `rescript` and `rescript-tools`, each mapped to a JavaScript file under `cli/`. The data flow is therefore: ReScript source goes into the compiler, JavaScript comes out, and the runtime package supplies the small helpers that the generated code calls into. Nothing in the README describes a type-checking server or a language server protocol implementation; the editor story is delegated to the separate VSCode and Vim plugins the README links to.

Installing ReScript and running a first build

The README does not inline installation steps. It points to the Installation Guide on rescript-lang.org for both a new project and integration into an existing JavaScript project, and to rescript-react documentation for React apps. What the repository does fix is the runtime requirement: `package.json` sets `engines.node` to `>=22`, so the toolchain expects Node 22 or newer.

The package is published on npm as `rescript`, and the binaries are declared in the `bin` field. A global install exposes the `rescript` command directly:

npm install -g rescript
rescript

Running `rescript` with no arguments in a project directory is the documented entry point for the build; the README does not enumerate its flags, so treat the Installation Guide as the authority on project setup. For a project-local install, the same binaries are reachable through the package scripts:

npm install --save-dev rescript
npx rescript

The `bsc` binary is the standalone compiler, and `rescript-tools` is a third entry point listed alongside it in `package.json`. If you are integrating into an existing JavaScript project rather than starting fresh, the README's claim worth testing early is the export path: it says you can export ReScript libraries to JavaScript and "automatically generate TypeScript types", which is the feature that decides whether a mixed codebase stays workable.

What the ReScript type system deliberately leaves out

The README is explicit that the type system prioritises "simpler types over complex types for the sake of clarity and easy debugability". That is a design decision with a cost. Developers arriving from TypeScript will look for conditional types, mapped types, template literal types and the rest of the type-level programming toolkit, and the README does not offer equivalents. If your codebase encodes business rules in the type system itself, ReScript is the wrong tool, and no amount of syntax familiarity will fix that.

The second limitation is the build step itself. ReScript is not a drop-in checker over existing `.js` files; it compiles its own source language. The README frames adoption as gradual and reversible, saying you can remove all source files and keep the clean JavaScript output, but that only holds if you have not started depending on ReScript-only constructs in the parts you intend to keep. The escape hatch is real, but it is a one-way door in practice once generated code is your production artifact.

A third gap is documentation surface. The README's Upgrading section links to the Installation Guide rather than describing an upgrade procedure, and the repository's CHANGELOG.md is not reproduced in the README. Given that the newest published release is `13.0.0-alpha.6` from 2026-09-16 while `12.3.1` from 2026-08-24 is the current stable line, anyone planning a version bump should read the changelog directly instead of assuming a smooth path.

ReScript compared with TypeScript and Melange

ReScript versus TypeScript is the comparison most teams actually face. TypeScript annotates JavaScript in place: your `.ts` files are JavaScript with types, the compiler strips the types, and the ecosystem you already use keeps working unchanged. ReScript replaces the syntax and the type system, then emits JavaScript. The practical difference is that TypeScript can be adopted file by file with no build-output boundary, while ReScript introduces a generated artifact you have to decide whether to commit, ignore or ship.

Melange is the closer comparison for anyone coming from the OCaml side, and it appears in the search data around this project. Melange compiles OCaml to JavaScript, so you keep OCaml's syntax and its type system, including the parts ReScript simplified away. ReScript is its own language with its own syntax. The trade-off is direct: Melange gives OCaml developers a shorter path and more type-level power, while ReScript gives JavaScript developers a smaller language to learn and, per the README, generated output that stays readable. Neither is a superset of the other, and the repository does not position ReScript as an OCaml tool.

Licensing and the cost of staying current

The licence situation is not a single licence, and this is the detail that most often stalls adoption. `package.json` declares `"license": "(LGPL-3.0-or-later AND MIT)"`, and the README breaks the monorepo down by directory: `compiler/` is LGPL-3.0-or-later, `compiler/syntax/` is MIT, `packages/@rescript/runtime/` is MIT, and `rewatch/` is MIT. Full texts sit in `COPYING.LESSER` and `LICENSE.MIT`. The repository also carries a `COPYING` file and a `LICENSE` index. What that means for a given product is a question for your own legal review; the repository does not offer guidance on linking or distribution scenarios, and nothing here should be read as legal advice.

Upgrade cost is the other ongoing expense. The release cadence visible in the repository shows an alpha line and a stable line running in parallel, with `13.0.0-alpha.6` published on 2026-09-16 and `12.3.1` on 2026-08-24. The README's Upgrading section points at the Installation Guide rather than documenting migration steps itself, so upgrade planning depends on CHANGELOG.md and the release notes. The last push to the default branch was on 2026-09-21, one day before the date of this writing, and the repository is not archived. That tells you the project is moving; it does not tell you how much of a version bump will land in your code.

Who should pick ReScript and what to check first

ReScript fits teams that want a total type system over a JavaScript target and are comfortable owning a compiled artifact. The README's list of targets is concrete: JavaScript, Node and ReactJS applications, with separate documentation for rescript-react and rescript-react-native. It fits least well where TypeScript's type-level features are load-bearing, where a build-output boundary is unacceptable, or where the team has no appetite for a language whose syntax differs from JavaScript.

The practical first check is the Node version. `package.json` requires `>=22`, so a CI image pinned to an older runtime will fail before anything else does. The second is the licence split: confirm with your own reviewers whether LGPL-3.0-or-later on `compiler/` is acceptable for how you distribute, since the MIT terms elsewhere in the monorepo do not extend to that directory. The third is the alpha line. If you are evaluating `13.0.0-alpha.6` from 2026-09-16 rather than the stable `12.3.1` from 2026-08-24, you are choosing a pre-release, and the README does not promise API stability across it.

Editorial conclusion

Adopt ReScript if you want full type coverage over an existing JavaScript codebase and are willing to keep the emitted JavaScript as the source of truth for anything you hand back to plain JS. Do not adopt it if your team's tooling depends on TypeScript's type-level programming, since ReScript's type system is deliberately simpler. Before committing, verify two things yourself: that Node 22 or newer is available in your build image, because package.json sets engines.node to >=22, and that the LGPL-3.0-or-later terms on compiler/ are acceptable to your legal reviewers, since that directory is not covered by the MIT licence used elsewhere in the monorepo.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. rescript-lang/rescript on GitHub