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.jsonto 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.
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
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
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
Use an OCaml Library as a NPM Package
If you follow the layout convention above, using an OCaml package is pretty straightforward:
bsc.exe -I path/to/ocaml/package/installed -c a.ml
Your command line would be like this:
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
You can see a more elaborate
bsc setup like so:
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
Additionally, please consult https://github.com/chenglou/intro-to-reason-compilation, which covers the lowest-level Reason + BuckleScript compilation mechanisms.