Grunt

Moodle 2.9

Grunt is a command line tool used to prepare our javascript and less-generated css for production usage. After making any change to javascript or less files in Moodle, you must run grunt to lint, minify and package the javascript/css properly so that it can be served by Moodle.

Install grunt

javascript and CSS in Moodle must be processed by some build tools before they will be visible to your web browser. We use "grunt" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "nodejs" environment. You will need to install NodeJS and the Grunt tools. For documentation on this process see Javascript_Modules#Install_grunt.

Running grunt

Typical commands:

grunt amd               # Short-cut for grunt jshint uglify, rebuild all AMD modules.
grunt shifter           # Run shifter
grunt js                # Short-cut for grunt amd shifter

grunt css               # Run less
grunt                   # Try to do the right thing:
                        # * If you are in a folder called amd, do grunt amd
                        # * If you are in a folder called yui/src/something, do grunt shifter
                        # * Otherwise build everything (grunt css js).

grunt watch             # Watch for changes and re-run grunt tasks depending on what file changes
grunt eslint --show-lint-warnings # Show pedantic lint warnings for JS

On Linux/Mac it will build everything in the current folder and below. You need to cd into the amd folder of your module root, i.e. dirroot/blocks/foo/amd before running grunt amd - this will compile only your plugins AMD source files. You can make output more verbose by adding -v parameter, if used with grunt shifter you will have to cd into the module/yui/src folder, and to show what your lint errors are you can also use the -v parameter. On Windows, you need to specify the path on the command line like --root=admin/tool/templatelibrary.

Using Grunt in additional plugins

You may want to use Grunt for performing tasks in your custom Moodle plugins. For building AMD and YUI modules in your plugin, the standard configuration Gruntfile.js located in the Moodle root should work well. For building CSS files from LESS templates, you will have to set up a separate Grunt installation in the root of your plugin.

If you do not have it yet, create the package.json file in the root of your plugin:

   {
       "name": "moodle-plugintype_pluginname"
   }

Install grunt, grunt less and grunt watch modules. Note that you should put the folder node_modules into your plugin's .gitignore file, too.

   $ cd /path/to/your/plugin/root
   $ npm install --save-dev grunt grunt-contrib-less grunt-contrib-watch grunt-load-gruntfile

Create a Gruntfile.js in the root of your plugin and configure the task for building CSS files from LESS:

"use strict";

module.exports = function (grunt) {

   // We need to include the core Moodle grunt file too, otherwise we can't run tasks like "amd".
   require("grunt-load-gruntfile")(grunt);
   grunt.loadGruntfile("../../Gruntfile.js");

   // Load all grunt tasks.
   grunt.loadNpmTasks("grunt-contrib-less");
   grunt.loadNpmTasks("grunt-contrib-watch");
   grunt.loadNpmTasks("grunt-contrib-clean");

   grunt.initConfig({
       watch: {
           // If any .less file changes in directory "less" then run the "less" task.
           files: "less/*.less",
           tasks: ["less"]
       },
       less: {
           // Production config is also available.
           development: {
               options: {
                   // Specifies directories to scan for @import directives when parsing.
                   // Default value is the directory of the source, which is probably what you want.
                   paths: ["less/"],
                   compress: true
               },
               files: {
                   "styles.css": "less/styles.less"
               }
           },
       }
   });
   // The default task (running "grunt" in console).
   grunt.registerTask("default", ["less"]);

};

Now running "grunt" or "grunt less" in your plugin root folder will compile the file less/styles.less and saves it as styles.css. Running "grunt watch" will watch the less/*.less files and if some is changed, it will immediately rebuild the CSS file.

If you are working on a custom theme, you may have multiple less/*.less files that you want to compile to their style/*.css counterparts. You can either define an explicit list all such file pairs, or let that list be created for you by making use of expand:true feature of gruntfile.js:

// This dynamically creates the list of files to be processed. files: [

   {   
       expand: true,
       cwd: "less/",
       src: "*.less",
       dest: "style/",
       ext: ".css"
   }   

]

See also

• YUI/Shifter
• Javascript Modules
• LESS
• Bitbucket pipeline to build YUI JS