Use Existing OCaml Libraries

This section is reserved for advanced usages. Usually, you'd pick an OCaml/Reason library that's already configured to work with our higher-level build system bsb (aka has a bsconfig.json). If not, you'd usually add a bsconfig.json to it. But if you want to directly use an OCaml package that's not part of the npm workflow, or are building some quirky infra with BuckleScript, keep reading!

This guide is also a small walkthrough of how bsb works under the hood.

Built in NPM support

Build an OCaml Library as a NPM Package

Note: this section might be slightly stale. If any of the steps aren't working, please file us an issue! Thanks.

We highly recommend you try this endeavour on a dependency-less library first. It'd avoid lots of trouble.

BuckleScript's compiler, bsc, extends the OCaml compiler options with several flags to provide a better experience for NPM users.

In general, you are expected to see two kinds of build artifacts: the generated JS files and metadata that your OCaml dependencies rely on.

Since CommonJS has no namespaces, to allow JS files to live in different directories, we have a flag

SH
bsc.exe -bs-package-name $npm_package_name -bs-package-output modulesystem:path/to/your/js/dir -c a.ml

By passing this flag, bsc.exe will store your package_name and relative path to package.json in .cmj files. It will also generate JS files in the directory you specified. You can, and are encouraged to, store JavaScript files in a hierarchical directory.

For the binary artifacts (Note that this is not necessary if you only want your libraries to be consumed by JS developers, and it has benefit since end users don’t need these binary data any more), the convention is to store all *.cm data in a single directory package.json/lib/ocaml and Javascript files in a hierachical directory like package.json/lib/js.

Use an OCaml Library as a NPM Package

If you follow the layout convention above, using an OCaml package is pretty straightforward:

SH
bsc.exe -I path/to/ocaml/package/installed -c a.ml

Together

Your command line would be like this:

SH
bsc.exe -I path/to/ocaml/package1/installed -I path/to/ocaml/package2/installed  -bs-package-name $npm_package_name -bs-package-output commonjs:path/to/lib/js/ -c a.ml

Examples

You can see a more elaborate bsc setup like so:

SH
bsb -init dummy-project
cd dummy-project
npm run build
cat lib/bs/build.ninja

The Ninja file, generated by bsb, describes the exact steps needed to build a trivial project using bsc.

Additionally, please consult https://github.com/chenglou/intro-to-reason-compilation, which covers the lowest-level Reason + BuckleScript compilation mechanisms.