Compile LESS using Grunt

The topic describes how to install, configure, and use Grunt JavaScript task runner to compile .less files in Magento 2.

Prerequisites

Adding themes to Grunt configuration

To compile .less files, add your theme to module.exports in the Grunt configuration, either in the default dev/tools/grunt/configs/themes.js or in the custom configuration file. For example:

module.exports = {
    ...
    %theme%: {
        area: 'frontend',
        name: '%Vendor%/%theme%',
        locale: '%language%',
        files: [
            '%path_to_file1%', //path to root source file
            '%path_to_file2%'
        ],
        dsl: 'less'
    ...
    },

Where:

  • %theme%: corresponds to your theme directory name.
  • %language%: the locale or language for the theme, such as en_US. Only one locale can be specified here. To debug the theme with another locale, create another theme declaration with another value for %language%.
  • %path_to_file%: path to the root source file, relative to the app/design/frontend/%Vendor%/%theme%/web directory. You need to specify all root source files of the theme. If your theme inherits from another theme, and does not contain its own root source files, specify the root source files of the parent theme.

Grunt commands

The following table describes the grunt commands you can use to perform different customization tasks. Run all commands from your Magento installation directory.

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

Use cases of tracking changes using Grunt

The following shows which Grunt tasks to use for debugging:

If you have LiveReload installed, run the grunt watch command, and the flow is even simpler:

CSS source maps

When using Grunt for styles preprocessing, you can enable the CSS source maps generation in your browser. It will make the theme styles debugging easier.

For each theme, Magento compiles all theme .less files into two CSS files: styles-m.css and styles-l.css. So when you debug a theme, your browser only sees styles-m.css and it might be difficult to define which .css or .less file requires corrections. For example:

node declaration autocomplete

CSS source maps solve this issue. They help to find the .less file, where the style is specified. For example:

node declaration autocomplete

CSS source maps are generated automatically when you compile CSS for your theme using the grunt less: <theme> command. To use them, you need to enable the display of source maps in your browser. For example, in Chrome, you would open the Developer Tools, go to the Settings panel, select Preferences, then check the Enable CSS source maps checkbox.