This article will demonstrate how to setup Bucklescript to work with a stock Elixir Phoenix project and how to use example code in the project.
I seem to be making a template on how to setup various things with Phoenix... :-)
If you are adding Bucklescript to an existing phoenix project then feel free to skip this step.
First things first, let's make sure you already have nodejs (6+), npm, Erlang, Elixir, and Phoenix installed, all in the Phoenix instructions.
So lets start with a basic phoenix app, will be using normal integer IDs in the model, using brunch as that is what comes with Phoenix (feel free to adjust to your own if you use another bundler), and just fairly stock. Let's name it, oh, MyServer. So let's run this in your shell of choice:
Make sure to have it fetch and install dependencies to prepare the node files by answering Y to the Fetch and install dependencies? question.
At this point it should also be good to set it up as a git repo, it is never too early to make your repository:
Other than making sure your database is setup if you are using one and so forth, that should be all the basics. Now let's add Bucklescript to the project.
Adding Bucklescript to Phoenix via brunch
Make certain that you have the dependencies for bucklescript installed first as per its documentation, which for Windows is nothing (all self-included) or for linux it is making sure that ninja is already installed from your package manager.
First we need to actually acquire Bucklescript, so in the terminal run:
This will handle downloading and installation of bucklescript itself, including compiling if necessary.
Next we need to make a bsconfig.json file as that is the build definition file for the bsb build system, so in the project root directory put this content in a new bsconfig.json:
I've chosen "web/bucklescript" here to fit with the Phoenix style of putting front-end web code in to the web directory, but feel free to choose where-ever you want. The "generate-merlin" generates the .merlin file for bucklescript support, but it is optional if you are not going to use ocamlmerlin or are going to build it manually.
Next let's create a simple example file, just to make sure it works, so create the file web/bucklescript/my_file.ml and put this in it:
So the only thing we are doing is just printing the string Hello world when this file is loaded, this will be printed to the console in the web browser.
Telling Brunch where the Bucklescript output files are
Telling Phoenix to use Bucklescripts very fast watcher instead of the slow Brunch one for Bucklescript files
So now Brunch knows of the output files, however we do not want brunch to be the file watcher and recompile the files as it is just so-much-slower than bsb itself, so instead let's tell phoenix to start bsb -w for us, so open your config/dev.exs file and adjust your watchers entry to something like this:
Lastly let's just call the example file we made earlier from the normal Phoenix app.js file to test it, so open your web/static/js/app.js file and add this to the bottom of it (of course you can configure brunch to change the path as well):
Then launch the mix dev server via:
Then just launch the web browser, go to http://localhost:4000/ and then check your console, you will see printed there: Hello world. :-)
For note, you may not want to commit the cache files to your repository located at lib/bs and lib/ocaml, as well as if you are working in an existing instance with cache files and you update the compiler or a major library you depend on then be sure to run ./node_modules/.bin/bsb -clean-world -make-world, which will wipe the cache files and rebuild it all, which only takes a few seconds at most. :-)