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

Make sure your Magento application is in developer mode before you begin.

Note: You might need root privileges for some commands. If a command fails, retry it with sudo.

Step 1 — Install Node.js

Example for Debian/Ubuntu:

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

sudo apt-get install -y nodejs

For other Node.js versions, see: NodeSource Distributions

Step 2 — Install the Grunt CLI globally

npm install -g grunt-cli

Step 3 — Enable Magento’s Grunt files

From the root of your Magento project, rename the sample files:

• package.json.sample → package.json
• Gruntfile.js.sample → Gruntfile.js
• grunt-config.json.sample → grunt-config.json

Step 4 — Install/refresh Node project dependencies

Run from the Magento root:

npm install

npm update

Step 5 — Verify Grunt is installed

grunt --version

You should see the installed version printed.

Step 6 — Point Grunt to the correct themes config

Open grunt-config.json and replace:

{

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

}

with:

{

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

}

Step 7 — Add your theme to the Grunt configuration

Edit dev/tools/grunt/configs/themes.js and add your theme under module.exports.

Example for the Pearl Child Theme:

pearl: {

area: 'frontend',

name: 'Pearl/weltpixel_custom',

locale: 'en_US',

files: [

'css/styles-m',

'css/styles-l'

],

dsl: 'less'

},

(Adjust name, locale, and files to match your setup.)

Step 8 — Run Grunt for your theme

From the Magento root:

• If you have the Pearl Theme configured:

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

• If you have the default Luma theme configured:

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

Step 9 (Optional) — Automatic browser reloads

To watch changes without manually reloading, install the LiveReload browser extension and enable it after grunt watch is running:

• Chrome extension: LiveReload

With LiveReload + grunt watch:

• After editing any .less file, changes compile and the page reloads automatically.
• After changing root source files or moving includes, run grunt clean and grunt exec to republish symlinks, then the page will reload.

To stop the watcher, press CTRL+C in the terminal.

What each Grunt task does

Updated on: 16/09/2025