Reason: an OCaml syntax that compiles to JavaScript and native code

What Reason is, and who the repository is actually for

Reason is a syntax for OCaml. The README describes it as "Simple, fast & type safe code that leverages the JavaScript & OCaml ecosystems", and the repository layout backs that up: src/ holds the parser and the tooling, js/ holds the JavaScript-side pieces, and reason.opam, rtop.opam, dune and dune-project are the OCaml build metadata. The project itself is the compiler front end and the refmt formatter, not a framework or a runtime.

The audience is narrower than the tagline suggests. You need to be at least willing to touch OCaml tooling, because the Makefile's install target is `opam pin add reason . -y` and the build target is `dune build`. If you have never run opam or dune, the first hour is spent on toolchain setup, not on writing Reason. The docs for new users live on a separate site, reasonml.github.io, and the repository for that site is reasonml/reasonml.github.io. The README points there rather than reproducing installation steps, which means the README alone is not enough to get started.

The mechanism: a parser, a formatter, and OCaml underneath

Reason does not implement its own type checker or code generator. The repository contains src/reason-parser, whose contents include reason_parser.mly, a Menhir grammar file. The Makefile has an all_errors target that runs `menhir --explain --strict --unused-tokens src/reason-parser/reason_parser.mly --list-errors` to regenerate parser error states. That tells you where the language definition lives: in a Menhir grammar, compiled with dune, producing a parser that turns Reason syntax into OCaml's AST.

The data flow follows from that. Source text goes through the Reason parser, becomes OCaml's AST, and from there the existing OCaml compiler handles typing and code generation for whichever backend you target. The npm package @esy-ocaml/reason is the native esy package published to npm, and package.json sets `"main": "refmt.js"`, so the JavaScript entry point of the npm package is the refmt formatter rather than a compiler. That distinction matters: installing the npm package gives you formatting, not a JavaScript build pipeline by itself.

The formatter is a first-class artifact. .ocamlformat and .ocamlformat-ignore sit at the repository root, and the Makefile has a testFormat target that runs the build and the test suite before formatting checks. If you plan to contribute, expect the formatter to have opinions about your patch.

Installing Reason and running it for the first time

The README gives one installation path for contributors, and it is esy-based. It installs esy globally, clones the repository, and then runs esy inside it. The `esy` command with no arguments resolves and builds the project from esy.json and esy.lock.json.

npm install -g esy@next
git clone https://github.com/reasonml/reason.git
cd reason
esy

After `esy` finishes, the build artifacts are under _build and the project is usable from the esy sandbox. The README's next step is the test suite, which is how you confirm the toolchain actually works on your machine.

esy test # Run the tests

If you prefer to work outside esy, the Makefile exposes a dune-based route. `make build` runs `dune build`, and `make install` runs `opam pin add reason . -y`, which pins the local checkout into your opam switch. The Makefile comments note that CI uses opam while the regular workflow need not, so the two paths are not equivalent in the project's own eyes. There is also a Nix path: flake.nix and flake.lock are at the root, and nix/ exists, though the README does not document how to use them. For end users rather than contributors, the README defers to the Getting Started page at reasonml.github.io/docs/en/installation, which is the only place the project says to look for a normal install.

Where Reason stops being the right tool

The repository is the language toolchain, and nothing in the README suggests it ships an application scaffold. If what you want is a React-like framework, a bundler, or a project generator, this is not it: the README's only user-facing pointer is the documentation site, and the repository's own files are parser, formatter, build metadata and tests. The topics list includes javascript and ocaml, which describes the interop target, not a batteries-included stack.

Version skew is a real hazard. package.json declares `"version": "3.6.2"` while the most recent release listed is 3.18.0 from 2026-06-23. If you depend on the npm package and read its manifest to decide compatibility, you are reading a stale number. Pin explicit releases and check the release notes rather than the manifest.

Toolchain coupling is the other constraint. dune, opam, esy and Nix all appear in the repository, and the Makefile's own targets mix them: `test` runs `esy dune runtest`, while `install` uses opam. A team without OCaml build experience will spend its first effort on that mixture. The README does not document rollback or uninstall for any of these paths.

Reason against plain OCaml

The honest comparison is not Reason versus another JavaScript language. It is Reason versus writing OCaml directly. Both compile through the same OCaml compiler and produce the same output for the same program; the difference is the surface syntax you read and write every day. Reason's grammar is defined in src/reason-parser/reason_parser.mly and the project ships refmt as the formatter, so the practical difference is that Reason code is parsed by a Menhir grammar maintained in this repository rather than by OCaml's own parser.

That has a concrete consequence for tooling. Editors, linters and build integrations that assume OCaml syntax need a Reason-aware path, and the formatter becomes part of your workflow rather than an optional extra. In exchange, you get a syntax that the project positions as simpler, with the same type system and the same JavaScript and native backends. If your team already writes OCaml and is happy with it, switching buys you syntax and costs you a second parser in the toolchain. If you are starting fresh and want OCaml's types with a JavaScript target, the trade is the other way around.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-20. Releases are frequent enough to track: 3.18.0 on 2026-06-23, 3.17.3 on 2026-01-21, and 3.17.2 on 2025-11-30. CHANGES.md exists at the root, so upgrade notes have a home, though the README does not describe a supported upgrade procedure or a version support window.

Upgrade cost is dominated by the toolchain, not by the language. esy.lock.json and esy.lock/ pin the esy dependency graph, rtop.esy.lock/ pins the separate rtop REPL environment, and flake.lock pins the Nix inputs. Moving a project to a new Reason release means regenerating or reviewing those lock files, and the Makefile's clean-for-ci target (`rm -rf ./_build`) is the only cleanup the repository documents. There is no migration guide in the README.

The licence is MIT, stated in package.json and in LICENSE.txt, which is permissive enough for commercial use. The README adds that works forked from other projects remain under their original licences, and ORIGINS.md exists to record that provenance. Treat that as a reason to read ORIGINS.md before redistributing, not as legal advice.

Editorial conclusion

Adopt Reason if you already want OCaml's type system and need a JavaScript or native target, and you are comfortable with esy, dune and opam in the same project. Do not adopt it if you expect an npm-only setup, a React framework, or a project that ships a rollback story: the README documents none. Before committing, install esy, clone the repository, run esy and esy test, and confirm that the docs site at reasonml.github.io covers the version you are pinning. The repository's own package.json still reads version 3.6.2 while the latest release is 3.18.0, so pin an explicit release rather than trusting the manifest.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. reasonml/reason on GitHub
5. Releases