A short history of ReScript (BuckleScript)

It takes time to write such a post for a non-native speaker like me, but I appreciate what the OCaml gives me and believe I am doing good for the community, so I decide to write a short history of ReScript and explain the motivations behind this project.

I like OCaml, that’s why I decided to go to PlClub@UPenn for further study after undergraduate (2011). I wrote lots of tutorials around OCaml and used to be one of the maintainers of camlp4, I was even honored to be listed as core maintainers of OCaml once.

However, the reality is brutal that it’s very difficult to find a decent job using OCaml if you are not interested in Finance or get unlucky with a Jane Street interview. Here a decent job, I mean you get paid as good as those Silicon Valley companies while using your favorite programming language.

JSOO started growing mature back in 2013, it is the first compiler which gets bootstrapped in the browser, truly impressive. However, even for OCaml experts like me, it is really hard to get started with JSOO. It is a black box to me that I can not read the generated JS code under the hood. If your code works under the bytecode but stops working in the browser. You have to do a random guess to do the debugging. These are the impressions I have back then.

Another story happened on my side is that I started to have lots of experience in JavaScript in daily jobs and love it. It’s the most beautiful dynamic language I have used – you have a decent IDE everywhere as long as it ships a browser. So the idea comes to my mind that why not make a compiler which compiles OCaml to idiomatic JS for the convenience of JS users?

The beauty of this idea is that OCaml will share the same runtime as JS so that interop is really easy and you can use your favorite language in your daily jobs. I also shared my ideas with JSOO devs: discuss: compiling rawlambda output to javascript · Issue #338 · ocsigen/js_of_ocaml (github.com)

The project was originally named OCamlScript but it has a name conflict with an existing package so that it is renamed into BuckleScript.

At a similar time, ReasonML syntax was released, it is a JS friendly syntax for people to take advantage of OCaml. The combination of ReasonML and BuckleScript is very natural. To avoid confusion to users, we call it ReasonML or projects under the ReasonML umbrella – but the heavy lifting is mostly done by BuckleScript.

The development of ReasonML syntax has slowed down since 2018. What worries me is that the remaining commits keep adding stuff that we don’t want. To maintain the compatibility with OCaml for each release, the ReasonML syntax keeps a snapshot for all versions of OCaml AST, the code gets bloated quickly that the parser is even larger than the compiler itself – this is hard to believe, it means that all my hard work to squeeze the performance will be wasted in the parser.

I wish the very few resources could be put into bug fixes instead. We communicated and realized that the top priority for ReasonML syntax is the compatibility for OCaml ecosystem while our top priority is providing the best dev experience for JS users.

It is open source projects and people can have different visions so that we decide a peaceful separation.

At a similar time, Iwan – one of the major contributors of ReasonML syntax, shows us a POC of a handwritten parser which supports the whole language. This is something I want but do not have time to do – a hand written parser for the best error message and better dev experience.

The original goal is to have the hand written parser 100% compatible with ReasonML syntax so that we can finish the transition, but it ends up being slightly different.

The current status of ReScript

Despite the changes of the syntax, the core gets improved day by day. It has over 11,000 commits in the last few years.

We are going to make a release of version 9, we believe it is currently the fastest compiler on the JS market which generates the most readable JS code and yields the smallest JS output size.

I do wish it could be a useful language for people who like OCaml but can use it in their daily JS work. It is a fierce competition in such a market. We have to compete with languages of huge successes: TypeScript. That’s why given a small team with very few resources, we are very focused and don’t want to get distracted by anything else.


Thanks for taking the time to write this post, @bobzhang.


Thank you for this excellent summary Bob, and for your efforts on ReScript. I remember very clearly an OCaml Industrial Consortium meeting a few years ago when the essential difference between jsoo and Bucklescript/ReScript was explained to us.

jsoo maintains full OCaml compatibility at the cost of some translation complexity, whereas ReScript does not in favour of more optimal JavaScript output that is human-readable. They are very clearly in different parts of the design space, and both clearly valuable in our ecosystem.


Thanks for the reply, it means a lot.


Even after reading this post, I am still confused as to what the different projects are and how they are going to be related going forward. I don’t understand what’s happening with ReasonML, ReScript, etc.

The biggest selling point, IMHO.


That’s mostly because ReasonML hasn’t done any public statement regarding its way forward.

ReasonML started to be heavily OCaml native centric, so it will continue leveraging the esy, dune, jsoo workflows with 100% compatible OCaml semantics.

This means, if you are only interested in the OCaml / opam ecosystem, you will probably want to continue using Reason with the OCaml toolchain.

If you are interested in JS development with seamless interop (especially when doing UI dev with React), you want to use ReScript (+ syntax).

Of course, in certain circumstances you can compile Reason / OCaml files in a ReScript project, but it’s not a use-case we focus on (within the ReScript project, we use ReScript on the frontend, ML / Reason in toolchain).

It’s also worth noting that we maintain our docs and libraries exclusively in ReScript syntax. This is not bc we dislike OCaml / Reason, it’s just that it’s otherwise impossible to build a language community and library ecosystem when everyone is using a different dialect in an already small community. It also doesn’t really make sense honestly; combining native & JS is non trivial and adds a lot of complexity we can’t afford.

That said, OCaml is a fantastic language. Probably the most productive language I’ve had the chance using in my daily work, but this doesn’t mean it’s a fit for everyone. ReScript now makes it possible to leverage the advantages of OCaml’s type checker in a JS centric workflow without referring to any OCaml resources, and this is a great step to make the language (and its language family) more accessible for the masses (also for me as a working JS professional).

I hope this makes it clearer


Thanks for clarifying. Yes, a bit clearer. Are the people involved in ReScript and ReasonML overlapping? Most recently (early January), Jordan Walke left Facebook, so that’s another variable.


Yes, this is helpful.

FWIW, I don’t think that the other thread was meant to be hostile but, rather, expressing confusion. I think that there are two (maybe three) points that I found quite confusing when reading about the ReScript rebranding.

The first was whether this might be announcing a fork–or the end–of Reason. The announcement states that “BuckleScript & Reason are now called ReScript” which is ambiguous. It’s now clear that the intended meaning is that ReScript refers to the combination of the two. But it also could mean that both languages coming under the same umbrella.

(Rereading the announcement, I now understand the paragraph “This has no impact on the development of Reason. On the contrary, Reason can now focus on their goals, as much as we can focus on ours.” But I couldn’t parse them before.)

The other thing that I found confusing is that there wasn’t any discussion of the motivations for the rebrand. The “Why the rebrand?” section identifies the goals of the new project but not the motivation, which is what you’ve provided here. This is what clarified things for me.


I have to admit I’m still confused. Should I be telling people at my company to stop using ReasonML for new projects or not? Should I assume that only jsoo for translating OCaml to Javascript going forward? Those are the questions I need to answer.

I think the answer is “ReasonML is on its way out, and you should not rely on this toolchain to compile ReasonML and OCaml to Javascript for the long run.” For my own purposes, that probably means phasing out ReasonML, and using jsoo for times when I need OCaml itself to run under Javascript.


Maybe ocaml itself should integrate the reason parser (not the rest, just the menhir file and the lexer) and make then official :upside_down_face:. That’d solve any stability problem,perceived or real.

Maybe, but even if that were a serious suggestion (I presume it isn’t), that won’t actually solve the issue, which is that the ReasonML ecosystem was built around the Bucklescript compiler and its tools, not the standard compiler.

One result of this is that people who invested money and labor into building projects on top of ReasonML because they needed compatibility with an existing OCaml code base now get to throw away their work. The folks who built such things believed that they were joining up with an emerging ecosystem, but that ecosystem is gone.


This was my confused understanding, also. Even until you just wrote this. Thanks

There is a recommended path forward which I believe the ReScript team has communicated fairly well: convert BuckleScript projects to ReScript syntax. Migrate to ReScript Syntax | ReScript Language Manual

In general you should find most questions answered in the docs and in the announcements: Announcements - ReScript Forum

1 Like

What if you can’t migrate to ReScript because you need to incorporate existing OCaml code into your project? Say you have a huge existing OCaml codebase and a lot of the appeal was the easy interoperation with it? What if you fear (I think with good reason) that going forward the ReScript team doesn’t care about interoperation?

BTW, just to be clear here: the developers of the Bucklescript and now ReScript toolchain don’t owe anyone their time and can do what they want. However, the situation is disappointing for the people who used the tooling and expected that it was going to survive for the long term. People built stuff on top of a particular ecosystem, the ecosystem they built for seems to have vanished out from under them, and now they’re left wondering if all their work was for nothing.

1 Like

I am confused about your actual use case. This is a thread about BuckleScript/ReScript, so my default assumption is that you have an existing BuckleScript project. For that the ReScript team’s recommendation is to move to ReScript syntax. But they have also said OCaml syntax is supported for those who want to continue using that.

When you say:

Do you actually have a huge OCaml codebase that you are interoperating with a BuckleScript project right now?

1 Like

I still find this confusing. What is “Reason” now, who are “they” in “Reason can focus on their goals”? And ReScript isn’t just Bucklescript + Reason, since it has a new syntax. Or is Reason syntax now ReScript syntax?

I’m not complaining. I think that in the long run this will all become clear. It might be that different people are working on different things, and it hasn’t sorted itself out yet what will happen in the long run. It might be that things are progressing in various ways, but no one has time or is yet ready to make public further clarificatory statements. I’m grateful for Bob Zhang’s brief history post in this thread, which did clarify a lot. That was very helpful. There were also some great recent comments about the value of Reason, ReScript etc. to the posters. But some things are still confusing. Which might be OK.

1 Like

Some clarifications to the comments:

What is the future for ReasonML syntax?

I can not speak for ReasonML maintainers. The project is transferred to Jordan since he left Facebook. The ReScript project is still funded by Facebook (and other companies) and we will upgrade existing ReasonML syntax to ReScript syntax internally.

What will happen to ReasonML existing projects?

The ReasonML projects can be generally categorized BuckleScript projects and revery.

  • We want to be good citizens of OSS. Everything that works will continue working for a long time and we will do our best to do bug fix but we will not promote the Reason syntax.

  • We provide tools and would like to help people migrate into the new syntax.

  • For the revery project, I am unclear what’s their future path.

Shall we add OCaml syntax into the docs section and promote its usage?

I used to be on the camp to support as many as users as possible. Lots of things happened in the last half made me unsure about this: we don’t know how to manage their expectation.

If you look at the discussions of ReScript (or BuckleScript) in various places, lots of negative comments are actually from them. So maybe it is not a terrible choice to not promote OCaml syntax so that we dont have a overlapping use case with JSOO (even though such overlapping is quite small).

The other thing is that our top priority is to make the dev experience better for JS platform users, while the OCaml users are more concerned about using the latest version of compilers from upstream and compatibility. Such mismatch of user expectation and needed communication consumed lots of energy from our side.

I will take a break soon and hope this is the last clarification. I also want to take this opportunity to thanks Bloomberg and Facebook. Their financial support is altruistic, they don’t try to exert any influence over the technical direction of this project.


You a champ Bob. It’s admirable to see someone/team continue to do their thing diligently while bearing public backlash, well intended or not.

Posts like these aid my argument to introduce Rescript to my team.


Bob already mentioned a few things, but I also wanted to add some more context.

There is one particular use-case that is not reflected in our docs, because it is “rather niche” (in comparison to our main target group): Reusing existing OCaml source code (e.g. some types / business logic) within a ReScript codebase.

As already stated, ReScript will continue to be an OCaml based compiler (based on a particular OCaml version), so depending on how you factor your OCaml code, you can still use your ml files, as long as you don’t go wild with advanced OCaml features (object system), or ppxes.

We are in touch with a few production users, such as Ahrefs / Solvuu / NomadicLabs, to make sure that ReScript code-sharing capabilities cover most of their use-cases. We don’t actively advertise this functionality though, especially not on our documentation website (those users who need it, usually know about it). At some point we will eventually create some explicit “OCaml Interop” document to set out the constraints for ReScript compatible .ml files, but it’s most likely going to be very low-key and not a selling feature.

As a general advice, even as an OCaml shop, you will most likely need to write your JS dependent frontend code in ReScript syntax, otherwise you will miss out on a lot of mindshare in the community (blogs, libraries, docs, q&a), and you’d probably also want to hire UI minded webdevs for your projects as well.

The code that OCaml users usually want to share are the types and some plain business logic between the backend and frontend team, and this works perfectly fine now, and will continue to work in the future. The biggest proposition of ReScript / OCaml is that both languages are built on the same type system IMO (easy to interop with, easy to transfer knowledge).

For those who want to stay true to the full OCaml experience should use JSOO instead, which is a much better fit. You can’t have it all unfortunately, so you need to weigh the trade-offs.

Before the rebrand there were “two flavours” of Reason: “Reason / BuckleScript” and “Reason / OCaml”. The main workflow of Reason has always been “Reason / BuckleScript” (since 2017), that’s why we announced that “Reason / BuckleScript” is now ReScript.

From there on, Reason only means one thing: “Reason / OCaml”, the native workflow, which is lead by Jordan. The rest of the team (working on the ReScript related compilation story) has realigned under the ReScript project, taking full ownership of their independent toolchain (syntax, compiler, editor, docs, core libraries), vision and marketing.