Docs / Language Manual / Build System Overview

You are currently looking at the v6.0 - v8.2 docs (Reason v3.6 syntax edition). You can find the latest manual page here.

(These docs are equivalent to the old BuckleScript docs before the ReScript rebrand)

Build System Overview

ReScript comes with a build system, bsb, that's meant to be fast, lean and used as the authoritative build system of the community.

Bsb provides a few templates to quickly start a new project:

bsb -init my-directory-name

Feel free to inspect the various files in the newly generated directory. To see all the templates available, do:

bsb -themes

The build description file is called bsconfig.json. Every ReScript project needs one.

To build a project, run:

bsb -make-world

Add -w to keep the built-in watcher running. Any new file change will be picked up and the build will re-run.

Note: third-party libraries (in node_modules) aren't watched, as doing so may exceed the node.js watcher count limit. If you're doing quick and dirty modifications inside node_modules, you have to do bsb -clean-world -make-world to rebuild them.

Note 3: If you are developing across multiple devices, you may find the -ws configuration useful in order to have live-reloading across the network. Possible configurations are:

  • bsb -make-world -w -ws _ (default)

  • bsb -make-world -w -ws

  • bsb -make-world -w -ws 5000

To build only yourself, use bsb -make.

bsb -help to see all the available options.

Artifacts Cleaning

If you ever get into a stable build for edge-case reasons, use:

bsb -clean-world

Or bsb -clean to clean only your own artifacts.

Editor Support

Bsb generates a .merlin file, used by various editor plugins under the hood to power e.g. autocomplete, type hint, diagnosis, etc.

Tips & Tricks

A typical problem with traditional build systems is that they're not resilient against the user moving/deleting source files. Most don't clean up the old artifacts correctly after such user action*. Bsb is unfortunately no different, unless you turn on "suffix": ".bs.js" in bsconfig.json, in which case we can track which JS artifact belongs to which source file correctly, even against source file moving/deletion.

Design Decisions

* One such build system that tracks these correctly & efficiently is Tup. See the (rather accessible!) paper here. Unfortunately, Tup's implementation uses FUSE and other systems, which we can't safely use on every platform.