Docs / BuckleScript / AutomaticInterfaceGeneration

Automatic Interface Generation

"Interface files" (.mli, .rei files) are the "public description" of their corresponding "implementation files" (.ml, .re), exposed as documentation, and containing nothing but type declarations. Since a file is a module, an interface file is essentially a module signature.

Tips & Tricks

You don't have to explicitly write an interface file; by default, one will be inferred from the implementation file (just like how a module's type can be inferred when you hover over it) and every binding from the file will be exported. We do encourage that, after you finish iterating on your project:

  • Explicitly add interface files to the files meant to be public

  • Add docblock comments on top of each binding to serve as documentation

  • Make some types abstract, and simply don't expose every binding from the interface file

Some types will have to be copy pasted from the implementation file, which gets tedious. This is why we let you automatically generate interface files, after which you can tweak whatever you want.

For a file src/, run:

bsc lib/bs/src/MyUtils-MyProject.cmi

Where MyProject is your project's namespace. If it's not enabled, it'll be just MyUtils.cmi). .cmi is the OCaml/BuckleScript file that contains some compiled type info.

The above command outputs a boilerplate .mli interface to stdout. If you're using Reason, turn it into .rei syntax:

bsc -bs-re-out lib/bs/src/MyUtils-MyProject.cmi

If you don't have bsc globally available, use the ones provided locally in node_modules/bs-platform/lib/bsc.exe.

Note: the generated boilerplate might contain the strings "BS-EXTERNAL" or "BuckleScript External". This happens when you've used @bs externals in your implementation file. It's a temporary flaw; you need to manually turn these "BS-EXTERNAL" back into the right @bs externals for now. We'll correct this in the future.