How to use GRUNT for Magento 2 and Pearl Theme [step by step Tutorial]

Updated: January 2019.

Grunt is a contemporary JavaScript task runner. The purpose of Grunt is to simplify repetitive tasks. You only have to configure a task runner through a Gruntfile. This tool can easily be utilized within all possible platforms and projects.

Althrought Magento 2 introduces built-in Grunt tasks, there are still several steps that have to be passed in order to setup Grunt for Magento 2 and Pearl Theme.

First make sure that you set your Magento application to the developer mode.

Note: You might need to run below commands for installations with root privileges, using sudo in front of each command. So, you can rerun the commands with sudo if it needed.

 

1. Install NodeJs in your PC, an example on how to install NodeJS below:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -

sudo apt-get install -y nodejs

For other NodeJs versions check here: https://github.com/nodesource/distributions#debinstall

 

2. Go to your magento directory from your machine and run all following commands from that location.

 

3. Install and refresh the node.js project dependency, including Grunt, for your Magento instance

npm install

npm update

 

4. Install Grunt CLI tool globally

npm install -g grunt-cli

 

5. Check if grunt is correctly installed. It should return your installed version.

grunt --version

 

6. Rename the following files from your Magento root directory

package.json.sample to package.json

Gruntfile.js.sample to Gruntfile.js

grunt-config.json.sample to grunt-config.json

 

7. Open grunt-config.json file, and replace the following:

{

"themes": "dev/tools/grunt/configs/local-themes"

}

with:

{

"themes": "dev/tools/grunt/configs/themes"

}

8. Add your theme to Grunt configuration. The following block is a template:

module.exports = {

    <theme>: {
        area: 'frontend',
        name: '<Vendor>/<theme>',
        locale: '<language>',
        files: [
            '<path_to_file1>', //path to root source file
            '<path_to_file2>'
        ],
        dsl: 'less'
    },

 

For example to add the child theme of Pearl theme, open dev/tools/grunt/configs/themes.js file, and add pearl theme as follows:

pearl: {

  area: 'frontend',

  name: 'Pearl/weltpixel_custom',

  locale: 'en_US',

  files: [

      'css/styles-m',

      'css/styles-l'

  ],

  dsl: 'less'

},

9. If you want to use Grunt for “watching” changes automatically, without reloading pages in a browser each time, you can install the LiveReload chrome extension in your browser and start it by clicking the extension icon after grunt watching is started.

 

10. Start working with Grunt on customization Pearl Theme

To start the work you can run the following commands. Can be in one line as below.

If you have Pearl Theme configured just run:

grunt clean:pearl && grunt exec:pearl && grunt less:pearl && grunt watch:pearl

If you have Magento 2 default Luma theme run:

grunt clean:luma && grunt exec:luma && grunt less:luma && grunt watch:luma

 

Below you can find details about the grunt commands. Make sure you run the commands from your Magento installation directory.

Grunt task	Action
grunt clean	Removes the theme related static files in the pub/static and var directories.
grunt exec	Republishes symlinks to the source files to the pub/static/frontend/// directory.
grunt less	Compiles .css files using the symlinks published in the pub/static/frontend/// directory.
grunt watch	Tracks the changes in the source files, recompiles .css files, and reloads the page in the browser.

If you have LiveReload installed, run the Grunt watch command, and the flow is simple:

• After you customize the content of any .less file, changes are applied and the page should reload automatically. No additional changes required.
• After you [customize the root source files or move the files included to the root files], run the clean and exec commands, and the page should reload in the browser.

 

 

11. To stop watcher you can use CTRL+C, which closed the process on Linux environments.

If you have any suggestion, feel free to comment.