Magento 2 LESS Compilation

3rd August 2017

Magento makes use of CSS preprocessing using LESS. There are two modes of Magento 2 LESS Compilation: client side and server side. Both modes involve compiling .less files into .css files.

To learn more about writing LESS, view the Getting Started with LESS post.

Magento’s blank theme includes three main stylesheets that are included via layout XML.

// vendor/magento/theme-frontend-blank/Magento_Theme/layout/default_head_blocks.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <css src="css/styles-m.css"/>
        <css src="css/styles-l.css" media="screen and (min-width: 768px)"/>
        <css src="css/print.css" media="print"/>
    </head>
</page>

These files are compiled from their same named .less files. The LESS files themselves are located in the vendor/magento/theme-frontend-blank/web/css/ directory.

As we know, the compiled .css files are found within the directory levels of the pub/static folder, and it is these files that can be seen within the browser when using the developer tools available for that browser.

By default, Magento will not watch for automatic changes to the .less files and automatically compile them into updated versions of their .css counterparts.

This can be demonstrated by adding your own .less files and testing out the changes.

Please note that this example assumes that your Magento application is running in developer mode and the the Frontend Development Workflow option within Stores -> Configuration -> Advanced -> Developer in the admin is set to Server side less compilation.

Assuming you have already created your own theme, create a web/css directory and create a custom file.

Within this file, add syntax that will change the colour and borders of the primary buttons in Magento.

// app/design/[Vendor]/[theme]/web/css/custom.less

.action {
    &.primary {
        background-color: red;
        border-color: red;
    }
}

Now the file will need to be referenced within a layout file. Add a default_head_blocks.xml within the Magento_Theme/layout directory.

// app/design/[Vendor]/[theme]/Magento_Theme/layout/default_head_blocks.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="../../../../../../../lib/internal/Magento/Framework/View/Layout/etc/page_configuration.xsd">
    <head>
        <css src="css/custom.css"/>
    </head>
</page>

Refresh the cache and reload your store, and you should notice that the buttons with the primary class have been changed to red. This includes the buttons on the Sign In page.

Magento 2 LESS Compilation

Even though we defined custom.css within default_head_blocks.xml and actually added custom.less, Magento has recognised the LESS file and compiled it to CSS.

Magento will initially look for the custom.css file and this was defined in the layout. If Magento doesn’t find it, Magento will then look for the .less file with the same name, which is this example is custom.less.

If Magento finds the LESS file, Magento will transform the syntax into CSS, and generate a CSS file.

This is native Magento functionality, however as mentioned previously, Magento will not automatically watch for updates within .less files. If we were to change the colour of the buttons again, this time to blue, the changes will not be picked up when the cache has been refreshed.

// app/design/[Vendor]/[theme]/web/css/custom.less

.action {
  &.primary {
    background-color: blue;
    border-color: blue;
  }
}

The changes will will show if you delete the pub/static/frontend and var/view_proprocessed directories. This forces Magento to re-check and recompile the .less files to .css.

Magento 2 LESS Compilation

As deleting directories each time you want to make a change isn’t really feasible, you can change the Frontend Development Workflow option within Stores -> Configuration -> Advanced -> Developer in the admin to Client side less compilation.

Magento will then use the Less.js library to compile the CSS. Now after editing the .less files, the changes should show on the storefront after a simple page refresh, however there may be occasions where the static resources will need to be cleared.

If the Frontend Development Workflow option is set to Server side less compilation, you can use Grunt to watch for changes.

Simply install and configure it, and then run the following commands within the Magento 2 root directory.

grunt exec:<your_theme>
grunt less:<your_theme>
grunt watch

Where <your_theme> is replaced by the name of your theme. Grunt will then watch your Magento project for file changes.

Note: This article is based on Magento CE version 2.1.7.