I'm not sure what to do with Reason

Think of what project you'd usually make if it was pure JavaScript; try porting/writing that in Reason + BuckleScript instead! We recommend trying to make concrete, end-user projects (e.g. a little command line util) rather than infra-level projects (e.g. a boilerplate generator). The latter category requires expertise and understanding idiomatic Reason code.

What's the relation between Reason, BuckleScript and OCaml?

Reason's a syntax for OCaml and supports all its features. BuckleScript compiles OCaml/Reason code into JavaScript.

Where do all these print_endline, string_of_int functions come from?

They're from the standard library, pre-opened during the compilation of your file. This is why you see them in scope.

You can read more about the Pervasives library in the api documentation:


Can I have a function to print arbitrary data structures?

If you're compiling to JavaScript through BuckleScript, you can use the JS console.log through Js.log.

Why is there a + for adding ints and +. for adding floats, etc.?

See here.

Does library ___ work with Reason?

Most JS libraries should easily work under Reason + BuckleScript.

What's the server-side story? Should I compile to native or to JS and use node.js?

At this time, we recommend compiling to JS through BuckleScript and use the JS wrappers at reasonml-community or somewhere else.

What's BuckleScript's async story?

If you're not interfacing with any library that uses promises, you can simply use callbacks. Everyone gets them and they're performant.

If you need to bind to a JS library that uses promises, or communicate with such library, you can use BS's Js.Promise.

What's the (unit) test story?

Some of OCaml's language features (not just types) might be able to defer the need for unit testing until later. In the meantime, for compilation to JS, we're working on Jest wrapper. We'll look into using Jest for native too, if Jest is written using Reason in the future (no concrete plan yet). OUnit is a good, small native OCaml testing library right now.

What's the .merlin file at the root of my project?

That's the metadata file for editor support. This is usually generated for you; You don't need to check that into your version control and don't have to manually modify it.

I don't see any import or require in my file; how does module resolution work?

Reason/OCaml doesn't require you to write any import; modules being referred to in the file are automatically searched in the project. Specifically, a module Hello asks the compiler to look for the file hello.re or hello.ml (and their corresponding interface file, hello.rei or hello.mli, if available).

A module name is the file name, capitalized. It has to be unique per project; this abstracts away the file system and allows you to move files around without changing code.

Is Some | None, contents, Array, List and all of these special? Where do they come from?

They're ordinary variants/records/module definitions that come with the standard library, opened by default during compilation out of convenience.

What does an argument with a prepended underscore (e.g. _ or _foo) mean?

Say you have List.map(item => 1, myList);. The argument item isn't used and will generate a compiler warning. Using _ => 1 instead indicates that you're intentionally receiving and ignoring the argument, therefore bypassing the warning. Alternatively, _item => 1 has the same effect, but indicates more descriptively what you're ignoring.

What's this MyModule.t I keep seeing?

Assuming MyModule is a module's name, t is a community convention that indicates "the type that represents that module, whatever that means". For example, for the Js.String module, String.t is the type carried around and representing "a string".

Why is there a Js_promise and then a Js.Promise? What about Js_array, Js_string and whatever else?

As a convention, Js_foo is the actual module, and Js.Foo is just an alias for it. They're equivalent. Prefer Js.Foo, because that's the official, public module name.