We reveal how to automatically build Moodle JavaScript modules with grunt watch

Developing JavaScript Module for Moodle 3.8 (and above) on Ubuntu

One gotcha for those of us used to debugging JavaScript in Moodle is the way JavaScript files are built for production compared with how they are loaded during development. For development, our old way of working was to turn off JavaScript caching. With JS caching turned off (referred to as 'development mode' from here on) Moodle then loaded the raw, non-minified JS files from the plugin's amd/src directory. These files were then concatenated into one single (and often very big!) first.js file. All this changed with Moodle 3.8.

Moodle and JavaScript - Background

From Moodle 3.8 onward, in development mode individual JavaScripts are sent to the browser. Note that these are sent from the amd/build directory and not the amd/src directory, meaning you'll see a 404 (file not found) error in your browser console if you haven't compiled your JavaScript files.

Moodle will only ever serve minified JavaScript to the browser, even in development mode. However, in development mode it will also send the corresponding source map files for each JavaScript. The source maps will tell your browser how to display the minified JavaScript in beautified form.

The impact of all this is that we'll need to compile our JavaScript every time we make a change and want to debug. However, there is a neat solution: grunt watch. This will run in the background and look out for any changes to your JavaScript files. If it notices a change it will go ahead and compile them. In this post we guide you through the set up.

Prerequisites

The watch task uses watchman (https://facebook.github.io/watchman/) to watch out for file changes. We'll need to build watchman from the original source and here are the commands you need:

Building watchman

We are currently developing on an Ubuntu 18.04 LTS platform using Eclipse 2020-03. We assume you have already installed grunt (see https://docs.moodle.org/dev/Javascript_Modules#Install_grunt)

$ cd ~
$ git clone https://github.com/facebook/watchman.git
$ cd watchman/
$ git checkout v4.9.0
$ sudo apt-get install -y autoconf automake build-essential python-dev libtool pkg-config
$ ./autogen.sh
$ ./configure
$ make
$ sudo make install
$ watchman --version

If watchman has built successfully then the correct version number will be output.

inotify is used to listen for file changes and it's worth increasing the number of inotify watchers (depending on your development environment, it's easy to run out of watchers). Run the following:

$ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Now navigate to your Moodle directory and run the following:

$ grunt watch

You'll see a message from the watch task telling you it's listening for changes to files. Try modifying a JavaScript and you'll see that both a compiled file and its corresponding map will be written to the amd/build directory.