Build System Overview

ReScript comes with a fast, native build system through the rescript package.

Every ReScript project needs a build description file, rescript.json.

The current build system was introduced in ReScript 12. It tracks dependencies across packages and schedules only the work affected by a change. See Reforging the Build System for a deeper look at its architecture.

Commands

Run rescript help to see the available commands:

❯ rescript help
Usage: rescript [OPTIONS] <COMMAND>

Commands:
  build          Build the project (default command)
  watch          Build, then start a watcher
  clean          Clean the build artifacts
  format         Format ReScript files
  compiler-args  Print the compiler arguments for a ReScript source file
  help           Print this message or the help of the given subcommand(s)

Use rescript help <command> for the options of a particular command.

Build a Project

Each build will create build artifacts from your project's source files.

To build a project, including its dependencies, run:

SH
rescript

This is an alias for rescript build.

To build once and then watch for changes, run:

SH
rescript watch

Any new file change will be picked up and the build will re-run.

Third-party libraries in node_modules aren't watched.

For monorepo setup in ReScript 12+, see Setting up a monorepo.

Incremental Builds

The build system recompiles only files affected by a change. Interface files (.resi) can reduce this work further: if an implementation change doesn't alter the corresponding interface, dependent modules don't need to be recompiled. See Module signatures and Build Performance.

Clean a Project

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

SH
rescript clean

Format Source Files

Format the project's ReScript files with:

SH
rescript format

Use rescript format --check in CI to check formatting without writing changes. You can also format selected files by passing their paths, or format standard input with --stdin .res or --stdin .resi.

Compile with Stricter Errors in CI

Since 11.1

You may want to compile your project with stricter rules in CI than during development. Use the --warn-error build flag:

SH
rescript build --warn-error "+110"

Here, warning number 110, which is triggered when a %todo has been found, gets promoted to an error. The full list of warning numbers can be found here.

TypeScriptConfiguration