Skip to main content

NodeJS and Grunt

Moodle uses a NodeJS toolchain to perform a number of development actions, including linting, transpilation of JavaScript, compilation of the Component Library, and a number of other routine tasks.

Use of NVM for installation of NodeJS is highly recommended over direct installation.

Setup and installation

Install NVM and Node

The recommended way of installing NodeJS is via the Node Version Manager, or NVM. NVM allows you to have several different versions of NodeJS installed and in-use at once on your computer.

Checking that NVM is working

You can confirm that NVM is working by checking the version, for example:

$ nvm --version

Moodle provides a .nvmrc file which can be used to automatically install the correct version of NodeJS for the current directory.

After you have installed NVM, you can install the correct version of NodeJS by running the following commands from your Moodle directory:

Installing the version of NodeJS for the current directory
nvm install
nvm use
Using the correct NodeJS version for your current directory

Rather than remembering to update the system version of NodeJS, you can instead have your environment install and use the correct version when you change into a directory containing a .nvmrc.

The approach for this will depend on your environment and advice is available for a range of environments from the NVM project.

Install local development dependencies

The Moodle JavaScript toolchain currently uses the Grunt build tool, along with other common tooling including eslint. To install these build dependencies, you should use the Node Package Manager, or NPM.

Installing all dependencies
npm install

You may see mention of various vulnerabilities here. Moodle only uses these tools during development for activities including transpilation and to check code. These dependencies are not used in client code where these vulnerabilities are typically reported.


As part of its build stack, Moodle uses the Grunt task runner.

Grunt is composed of a set of tasks, defined within the Moodle code repository in the Gruntfile.js file, and a grunt CLI tool which must also be installed.

Once you have installed the local development dependencies, you can simply run grunt using npx, for example:

$ npx grunt stylelin

Common issues

A number of commons issues may be encountered depending on your environment.

MacOS issues

If you are using MacOS, you may need to ensure that xcode is up-to-date.

Resetting xcode
sudo xcode-select --reset

Issues install node-sass

The node-sass module must be compiled from C. In some instances MacOS setup is incomplete or out-of-date and must be updated.

The following is a typical error that may be reported in this situation:

Example error installing node-sass on MacOS
npm ERR! code 1
npm ERR! path /Users/jun/Work/moodles/integration_master/moodle/node_modules/node-sass
npm ERR! command failed
npm ERR! command sh /var/folders/87/fnlrch612m5d40trk64lrd480000gn/T/
npm ERR! Building: /Users/jun/.nvm/versions/node/v16.17.0/bin/node /Users/jun/Work/moodles/integration_master/moodle/node_modules/node-gyp/bin/node-gyp.js rebuild --verbose --libsass_ext= --libsass_cflags= --libsass_ldflags= --libsass_library=
npm ERR! make: Entering directory '/Users/jun/Work/moodles/integration_master/moodle/node_modules/node-sass/build'

To address this issue, you can run the following command to ensure that the xcode build system is fully configured:

Configuring xcodebuild
xcodebuild -runFirstLaunch