Magento 2 Grunt based tasks management

After more than a year since its official stable release, Magento 2 can finally be used in production environments as it has passed the test of time. For us, old timers, working since the first versions of Magento 1, the new structure is at least puzzling and some things might need to be explained. One of those things is the tasks setup, with Grunt support, that Magento 2 comes with now.

Magento 2 Grunt based tasks management

Grunt is a JavaScript task runner which is used in automating specific tasks. Due to the fact that Magento comes with a number of console based tasks and a much more extensive shell than before, it was a good choice. It can be defined as an automation scripting engine built in JavaScript which makes use of multiple node.js plugins to run specific commands.


Setting it up is not very difficult and is done via NPM (node package manager).

# global install (root access required)
npm install -g grunt-cli

#local install
npm install grunt-cli

All based tasks are part of the existing Gruntfile.js project, which comes as Gruntfile.js.sample. You can use this file for all normal Magento 2 based tasks or you can extend from it and create your own. You will also need to use package.json.sample and rename it to package.json as it defines all required dependencies for the core tasks. Please make sure to understand that not all tasks are defined in Gruntfile.js, but also in /dev/tools/grunt, which are automatically imported in Gruntfile.js. You will have to know this if you need to debug anything from missing dependencies to tasks debugging.

Installing dependencies defined in pakage.json is done via npm as well:

# install all dependencies which are found in package.json. the command needs to be run in the root of your Magento setup
npm install

# update all packaged
npm update

Once this has been done your grunt tasks should be ready to run. Before everything is started, also it is also recommended that you do a full backend coding compilation from the console, as grunt only handles theme compilation. This is done by running:

php bin/magento setup:di:compile

Make sure to have the proper permissions on /var, pub/static, pub/media so that you will have no problems with running both backend compilation and frontend theme compilation.

In case you are building your own theme, make sure to define it as well in /dev/tools/grunt/configs/themes.js

module.exports = {
    your_theme_name: {
        area: 'frontend',
        name: 'Multidim/YourTheme',
        locale: 'en_US', 
        files: [
        dsl: 'less'

// your_theme_name  = the name of the theme identifiable by Grunt
// Multidim - your vendor name - as found in app/design/frontend
// YourTheme - your Magento theme  - as found in app/design/frontend/Multidim
// dls:'less' - the type of preprocessing you are using. less by default
// files - your less source files to be compiled from the theme

Base tasks:

grunt clean:your_theme_name

This task cleans all files linked to your theme from pub/static and also cleans any cache available in var.

grunt exec:your_theme_name

This task deploys your theme source files to /pub/static. It creates the appropriate arguments for:

php bin/magento dev:source-theme:deploy

such as the theme name, the files to be joined, the area the theme runs in (eg. frontend), the theme locale

grunt less:your_theme_name

This task generates the processed CSS files from the source less files gathered in the deployment. Make sure that the exec task is run before this, so that you have the latest less source files.

grunt deploy:your_theme_name

This task runs a full static content regeneration on the selected theme by running:

php bin/magento setup:static-content:deploy

which regenerates all static content including parent to child theme sources.

grunt mage-minify

This task minifies javascript files defined in /dev/tools/grunt/configs/mage-minify.json using node-minify. Java binaries are required for this operation.

grunt refresh

This task does a full refresh of all the available theme compilations. The task does the same as if running individually the following commands:

grunt clean
grunt exec:all

# A loop through all defined themes:
grunt less: [theme-name]

The refresh is required in case you suspect some sources are not properly handled.

grunt watch

This task can also be ran to track changes in the source files and automatically recompile CSS. It can also reload pages in your development browser by using LiveReload.


A number of errors which are often encountered:

error: >> [InvalidArgumentException]

There are no commands defined in the "dev:source-theme" namespace.
Exited with code: 1.

Warning: Task "exec:your_theme_name" failed. Use --force to continue.

This usually happens in case  a bad compilation generated issues. This type of errors comes directly from the magento shell console. The best way to handle this is to delete the folders /var/di and /var/generation and compile the backend again using:

php bin/magento setup:di:compile

Another error would be:

jit-grunt: Plugin for the “clean” task not found
If you have installed the plugin already, please setting the static mapping.

Warning: Task "clean" failed. Use --force to continue.

Aborted due to warnings.

In this case, you most likely lack a dependency required for the task to run. If this still happens after you have installed everything from package.json, you can debug everything starting from Gruntfile.js up to the file defining the task in /dev/tools/grunt and install/update any missing dependencies (underscore, path etc.)

Please comment if you have any other questions and I will try to answer as soon as possible.


Image source:

Leave a Reply

Your email address will not be published. Required fields are marked *