Compile LESS using Grunt

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

Prerequisites

• Make sure that you set your Magento application to the developer or default mode.
• Install and configure Grunt as described in Using Grunt for Magento tasks

Adding themes to Grunt configuration

To be able to perform .less files compilation, you need to add your them to Grunt configuration. To do this, in the default dev/tools/grunt/configs/themes.js or in the custom configuration file, add your theme to module.exports like following:

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 the following notation is used:

• %theme%: your theme code, conventionally should correspond to the theme directory name.
• %language%: specified in the ‘code_subtag’ format, for example en_US. Only one locale can be specified here. To debug the theme with another locale, create one more theme declaration, having specified 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 a certain 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 performing different customization tasks. Run all commands from your Magento installation directory.

grunt clean:<theme>

grunt clean:blank

grunt exec:<theme>

grunt less:<theme>

grunt watch

Use cases of tracking changes using Grunt

The following shows which Grunt tasks to use for debugging:

• After you switch the compilation mode from client-side to server-side, run the exec command.
• After you customize the content of any .less file, except the root source files, run the less task and reload the page.
• After you customize the root source files or move the files included to the root files, run the exec command and reload the page.

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

• After you customize the content of any .less file, changes are applied and the page reloads automatically. No additional changes are 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 browser page reloads automatically.

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 compliles all theme .less files into two CSS files: styles-m.css and styles-l.css. So when you debug a theme, you browser only sees styles-m.css and it might be difficult to define which exactly .css or .less file requires corrections. For example:

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

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 source maps displaying in your browser.

The path to the CSS source maps configuration differs, depending on the browser.

In Google Chrome, to enable source maps generation, go to Inspect > Settings > Preferences > Enable CSS source maps.