How to Use Grunt in Magento 2

- Magento 2

Magento 2 Grunt tutorial

Grunt is a contemporary JavaScript task runner which essentially simplifies repetitive tasks by automating compilation, minification, linting, unit testing, etc. It can do most of the aforementioned routine processes with zero effort, you only have to configure the task runner through a Gruntfile. And while the purpose of the tool looks quite intriguing, its versatility is even more promising, since you can easily utilize it within all possible platforms and projects. Below, we will explain how to use Grunt with Magento 2.

Although the ecosystem around Grunt is huge, it continues to grow every day. Hundreds of plugins are already available, so you can use the task runner to automate just about anything on your Magento website. Furthermore, if you cannot find what you need, it is extremely easy to publish your own Grunt plugin. Alternatively, you can hire someone to create missing functionality for you. By following the link below, you will discover all Grunt plugins: Grunt plugins

Magento 2 offers continuous integration with Grunt.js, and you can find out all basic aspects of this process having watched the following presentation:

Grunt.js in Magento 2

Magento 2 Theming with Grunt.js

A brand new theme management mechanism introduced in Magento 2 offers the following features:

  • Extended layout files. Instead of copying an entire xml layout file to a local folder you only need copy the part that you are going to change.
  • Organized layout structure. It is not possible to add layout files without module folder in Magento 2.
  • CSS and LESS inheritance. Now, you can change LESS files from a parent theme in custom themes.
  • Built in LESS compiler. Development in Magento 2 is easy, but you can make it even easier with Grunt.

In Magento 2, Grunt helps to streamline styles customizations while in a server-side compilation mode. Hence, you should understand how to install, configure, and use the task runner for styles debugging. The following section of our Grunt/Magento 2 tutorial describes these processes.

How to install and configure Grunt in Magento 2

Although Magento 2 introduces built-in Grunt tasks, there are still several steps you have to perform before using it:

  • First of all, you should install Node.js.
  • Then, it’s necessary to install Grunt CLI tool globally:

  • … as well as Grunt in your Magento 2 directory:

  •  Now, it’s time to work with the node.js project dependency for your Magento 2 instance: you have to refresh (or install) it:

  • The next step requires adding your theme to Grunt configuration. In the dev/tools/grunt/configs/theme.js file, add it to module.exports as in the example:


  • <theme> is your theme code which should correspond to the theme directory name;
  • <language> is specified in the ‘code_subtag’ format. For instance, t can be en_US. Please note that just one locale can be specified, so for debugging a theme with another locale, you have to create an additional theme declaration.
  • <path_to_file> is a path to the root source file. In case when your theme does not contain its own root source files and inherits them from a certain theme, you should specify the files of that parent theme.

This step is optional, but it can be very useful. By installing the LiveReload extension for your browser, you will be able to “watch” changes automatically without any need to reload pages.

Don’t forget to check the video below, since it describes how to install Grunt in Magento 2.

Magento 2 Grunt Commands

Use the Grunt commands described below to perform different customization tasks in your Magento 2 project. All commands should be run from the installation directory of Magento 2.

  • grunt clean:<theme>. This command removes static files related to your theme in both pub/static and var directories.
  • grunt exec:<theme>. This one republishes source files symlinks to pub/static/frontend/<Vendor>/<theme>/<locale>.
  • grunt less:<theme> should be used to compile .css files using symlinks from the aforementioned directory.
  • grunt watch. This command is designed for the LiveReload extension. It tracks changes in the source files, recompiles .css files, and reloads browser pages.

Tracking Changes in Magento 2 Using Grunt

If you don’t know which Grunt tasks to use for debugging Magento 2 styles, examine the following use cases:

  • You can run the exec task after switching the compilation mode from client-side to server-side.
  • Run the less command (and reload the page) after customizing the less file content. Note that root source files are the only exception.
  • After customizing root source files or move their contents, it is necessary to run the exec task and then reload the page.

With LiveReload installed all these actions look even simpler.

Simple Style Changes in Magento 2 Server-Side Compilation Mode via Grunt

  • Create and apply a new theme.
  • Go to your theme directory and, add web/css/source/_extend.less there.
  • Now, you should install Grunt as well as register your theme (the procedure is described abow).
  • Go to your Magento installation directory and run the following commands:

Please note that <your_theme> is the code of your theme that should coincide with the name of your theme directory.

  • To change the color of the buttons, add the following code in _extend.less:

  •  Now, you should refresh the page in order to see the changes applied.
  • To change the font of the buttons, add the following code in _extend.less:

  • Refresh the page once more to view the changes.

A Brief Magento 2 Grunt Manual

In addition to the aforementioned actions, it is also necessary to mention some core CSS tips for Magento 2.

How to clean CSS cache in Magento 2

To clean CSS cache or refresh less files, use the following command:

Alternatively, you can use dev mode during development:

  • Clear the var/generation and var/di directories:

  • Run the mode:

Source (Magento Stackexchange) (FireBear)

How to add new theme name to run Grunt in Magento 2?

Go to \dev\tools\grunt\configs, open your themes.js file, and change it according to the following example:

Now, it is necessary to open your less.js and change it as follows

After all these manipulation, you can run a Grunt less:luma2 task which will generate the pub static files for the theme.

Source (Magento Stackexchange) (Taral Patoliya)

Magento 2 LESS compilation with Grunt on Windows

First of all, you should install Grunt in in your Magento 2 project. Then, it i necessary to:

  • Add a theme to Grunt configuration. Add your theme to module.exports in dev/tools/grunt/configs/theme.js:

  •  Run CMD as an admin and go to the root directory of your Magento 2 project via cmd
  • Enter the following command :

  • …and this one:

  • Changes your Less file.
  • Refresh browser. As mentioned above, it is possible to see all changes without refreshing your browser with the aid of the LiveReload extension.

Patches for Master branch users are listed in the full article about Magento 2 Grunt. For further information, follow the link below.

Source (RG BLOG)

Grunt.js in Magento 2 Presentation

If you are going to master Grunt in Magento 2, Check this presentation, as it fully describes how to use the popular tool if you work with our favourite ecommerce platform.

Gulp Instead of Grunt

Some specialists recommend to use Gulp instead of Grunt, since it offers much faster building process. Therefore, Gulp should replace Grunt as a method for building static assets. Besides, it is better to use the tool for decoupling PHP calls from the Node.js build process: PHP calls from Node should be moved to ./bin/magento so node/js, while code is kept in Node.js only and PHP scripts are called from PHP. As a result, you can essentially streamline the deployment process.

 Gulp in Magento 2

It is also necessary to mention that Gulp focuses on code, while Grunt is all about configuration and it was developed around a set of commonly used tasks, while Gulp is based on the idea of connecting community-developed micro-tasks to each other. You can find the whole discussion about Grunt and Gulp in Magento on GitHub here: replace grunt with gulp.

And don’t forget to check a set of front-end tools for Magento 2 based on Gulp.js: Magento 2 Forntools.

That was our Magento 2 Grunt guide. Feel free to ask any questions via comments.