A couple of people have asked me how to get up and running recently, so I thought I’d put something together. If you’re looking for a “just clone this repo & go”, here’s a very simple boilerplate I put together for this post, or you can check out the reason-react-example repository.
What’s Reason?
Reason is a transpiler for OCaml. It allows you to use a syntax that’s much more familiar to javascript developers (and anyone coming from a C-like syntax), and also supports JSX.
What’s OCaml?
OCaml is one of those languages that gets listed on “5 programming languages that will change the way you think about programming.”
It’s been around for a long time (~20 years), but the community has stayed small and fairly focused on academia. Because of this, community resources are sparse, documentation is worse than other modern languages, and it’s historically taken a ton of effort to even install and manage packages.
The Reason initiative is very focused on making it easier for newcomers to learn OCaml and join the community.
What’s BuckleScript?
BuckleScript (by Bob Zhang over at Bloomberg) is a new backend for the ocaml compiler, which takes OCaml (or Reason) code and produces performant, readable JavaScript. It has excellent documentation, very readable output, and easy-to-use interop with JavaScript.
Installation
You can just git clone https://github.com/jaredly/reason-bucklescript-example to get ahead of the game if you want.
I’m assuming you’re on a unix-like machine (linux or mac), but BuckleScript also works on windows!
mkdir my-new-project
cd my-new-project
echo {} > package.json # shortcut to avoid answering any 'npm init' questions
npm install bs-platform
Installing bs-plaform will take a little time (~30 seconds on my macbook pro), because it’s building the BuckleScript compiler for you.
The version of bs-platform that I installed was
1.7.4, so if yours is later, some details might be different. Buckelscript includes reason, so it’s the only thing you have to install!
Then make a bsconfig.json file that looks like this
{
"name": "my-new-project",
"sources": "src"
}
Your first file
In src/hello.re, put:
Js.log "hello";
Now to compile, run ./node_modules/.bin/bsb -make-world.
And now run the compiled javascript with node ./lib/js/src/hello.js!
$ node ./lib/js/src/hello.js
hello
If you take a peek at the compiled javascript, this is what you get:
// Generated by BUCKLESCRIPT VERSION 1.7.4, PLEASE EDIT WITH CARE
'use strict';
console.log("hello");
Pretty nice!
Bundling for the web
If you’re targeting node, then you can skip this part. BuckleScript’s javascript output has all the
requires you need for node to be happy.
Once you have more than one file, you’ll need a bundler like webpack or rollup. Here’s my simple webpack.config.js (go ahead and npm install webpack to install it as well).
module.exports = {
entry: './lib/js/src/hello.js',
output: {
path: __dirname +'/public',
filename: 'bundle.js',
},
};
And here’s a basic html file to put in ./public/index.html
<!doctype html>
<meta charset="UTF-8">
<title>Hello Reason</title>
<script src="./bundle.js"></script>
Now run ./node_modules/.bin/webpack and open ./public/index.html and you’re good to go!
What’s next?
If you need a primer on the syntax, the Reason documentation has a useful list of javascript comparisons.
I’m also writing a post about BuckleScript interop that should be helpful 😄.
If you’re interested in using React, you can take a look at the react-reason-example repository.
If you have questions or just want to hang out, join us on Discord!