How CSS and Less files are preprocessed and how to debug them
What’s in this topic
The topic describes how stylesheets are preprocessed and compiled to CSS in the Magento application. It provides the theoretical background a frontend developer needs to debug stylesheets effectively.
Root source files
<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>The root source files for the Blank theme:
Less compilation modes
In the Magento application, the following modes of compiling
.less files to CSS are implemented:
Server-side Less compilation.
Client-side Less compilation.
When your application is not in the production mode, you can set Magento to compile
.lessfiles in a browser, using the native
To set the compilation mode, do the following:
- In the Magento Admin, navigate to Stores > Settings > Configuration > ADVANCED > Developer.
- In the Store View drop-down field, select Default Config.
- Under Frontend development workflow, in the Workflow type field, select the compilation mode.
- To save the settings, click Save Config.
Server-side Less compilation
The following paragraph describes how the Less preprocessor works in server-side compilation mode. For each CSS file included in the layouts, Less preprocessor does the following:
- Checks if the requested
.cssfile is found. If it is found, the preprocessor stops its execution. Otherwise, it proceeds to the next step.
- Changes the extension of the requested file to
.lessand tries to find the file using the Magento fallback mechanism. If the
.lessfile is not found, Less preprocessor stops its execution. Otherwise, it proceeds to the next step.
.lessfile contents and resolves
@magento_importand default Less
Resolves all paths in
.lessfiles to relative paths in the system using the Magento fallback mechanism. All files resolved by the Less preprocessor are copied to
var/view_preprocessed/less. Imported files are processed recursively.
- All source files are passed to the PHP Less compiler. The resulting compiled
.cssfiles are published to
Styles debugging in server-side compilation mode
In server-side Less compilation mode, to have your changes applied, you need to do the following:
pub/static/frontend/<Vendor>/<theme>/<locale>by deleting the directory in the file system (excluding .htaccess).
- Clear the
var/view_preprocesseddirectories by deleting the directory in the file system. (if they already existed there).
Trigger static files compilation and publication. This can be done in one of the following ways:
- Reloading the page where the modified styles are applied.
- Running the static files deployment tool.
Reloading the page only triggers compilation and publication of the styles used on this very page, and does not give you the information about the errors if any. So if you made changes in
.less files used on many pages, and want to debug them, using the deployment tool is the better option.
Debugging using the static view files deployment tool
Once you save your changes, run the following command from your
The tool pre-processes (including compilation) and publishes the static view files.
Manual static content deployment is not required in “default” and “developer” modes. If you still want to deploy in these modes, use the -f option:
bin/magento setup:static-content:deploy -f
All errors occurring during
.less files compilation are handled by the
oyejorge/less.php third party library.
Errors are caught as exceptions and written to the system log (by default it is
var/log/system.log) and displayed on the screen. For each error, the following information is written:
- The path to the processed file in the
- The error description, including the path to file where the actual error occurred. It might be either the processed file, or the imported file.
- The error line and the column number.
- The content of the
.lesscode in the previous and following lines.
Example of an error message:
Compilation from source: /var/www/magento2/app/design/adminhtml/Magento/backend/web/css/styles.less variable @variable-x is undefined in file /var/www/magento2/var/view_preprocessed/css/adminhtml/Magento/backend/en_US/css/styles.less in styles.less on line 56, column 17 margin-left: 0; width: 100%; height: @variable-x; } .menu-wrapper,
Debugging using Grunt
Alternatively, to streamline the process of applying and debugging styles customizations, in server-side compilation mode, you can
See the Compile LESS with Grunt topic for details how to install, configure and use Grunt.
Client-side LESS compilation
The client-side compilation flow is similar to server-side. The difference is in the set of files, published to
pub/static on the last step. In the client-side mode, the following files are published to the
- root source (.less) files with resolved
- symlinks to the root source file that do not contain
- symlinks to all other `.less` files imported recursively by the
Symlink is not created, and a copy of the processed file is published to
pub/static instead, if the source file differs from the processed one. One of the reasons of this difference might be the usage of the
@import directive without file extension in the source file. See The @import directive usage for more details.
Styles debugging in client-side compilation mode
Client-side LESS compilation is implemented using the native
less.js library. The default configuration is set in
lib/web/less/config.less.js; you can change it as needed.
You can find the detailed information about the configuration and other options of the
less.js used in a browser at http://lesscss.org/usage/#using-less-in-the-browser.
In client-side compilation mode, most of the stylesheet customizations display immediately after you reload a page in a browser.
With client-side compilation mode enabled, LESS files are compiled on every page load. This reduces page-loading performance.
When you need to clean static view files
There are certain types of changes, that require you to clear the
pub/static/frontend/<Vendor>/<theme>/<locale> directory and trigger the compilation and publication processes anew.
This is required in the following cases:
- If you change the root source files that contain the
@magento_importdirective, or the
@importdirective where the imported file is specified without extension.
- If you rename, remove, or add a
.lessfile imported with a
@importdirective but you did not correct the directives accordingly.
To clear the
pub/static/frontend/<Vendor>/<theme>/<locale> directory, delete the directory in the file system, and reload the store pages in a browser to trigger compilation and publication.
@import directive rules of usage
You can import local and remote
.css files in your
.less Magento stylesheets by using the standard LESS
According to the
@import syntax, specifying the file extension for the imported file is not mandatory. For example, the following notation is allowed:
@import 'source/lib/_lib'; @import (css) 'styles';
But in process of resolving the file path, Magento adds the
.less extension for the imported files in all
@import entrees. So in the processed files, the statements from the previous example will look like following:
@import 'source/lib/_lib.less'; @import (css) 'styles.less';
As a result, the processed files are different from the source files. So in the client-side compilation mode or when using grunt commands, Magento cannot use symlinks to the source files. Instead it uses the copies of processed files, and they are published to the
pub/static directory. In case of importing CSS resources, this also results in not finding and not importing the required files.
Importing remote CSS files
If you need to import a remote CSS file in your
.less source, use
url() notation. For example, to import a Google font, use the following notation:
To include the font in your theme’s CSS files, use the
@font-face CSS rule for the fastest loading time.
This way Magento will skip the
@import directive while resolving paths to the local resources.
The @magento_import directive
@magento_import is a Magento-specific LESS directive that allows including multiple files by a name pattern. It is used to include files with the same name from the different locations, for example, different modules.
@import directive includes a single file, which is found according to the static files fallback.
@magento_import can be used in the root source files of a theme only.
@magento_import rules of usage
To include a
.less file using the
- To avoid any conflicts with the original LESS syntax,
@magento_importmust be commented out with two slashes. Otherwise, the LESS preprocessor ignores it. Example:
// Comment in a LESS document // Standard LESS import directive // --------------------------------------------- @import 'source/_reset'; @import '_styles'; // // Custom Magento LESS import directives // --------------------------------------------- //@magento_import 'source/_module.less'; // Theme modules //@magento_import 'source/_widgets.less'; // Theme widgets //@magento_import 'source/_extend.less'; // Extend for minor customization
@magento_importmust contain the file path. The path is specified relatively to the file, where the directive is called and put in either single (‘’) or double quotes (“”). The best practice is to specify the file extension in the path, though technically you can omit this.
In the scope of static resources preprocessing, the built-in LESS preprocessor does the following:
- Searches for all
- Replaces the original
@magento_importdirectives with the standard
@importdirectives. The latter specify the paths to the particular files that correspond to the pattern specified in
Example of how
@magento_import is used and processed in
.. //@magento_import 'source/_widgets.less'; // Theme widgets ..
| In the processed file, this results in the following:
@import '../Magento_Catalog/css/source/_widgets.less'; @import '../Magento_Cms/css/source/_widgets.less'; @import '../Magento_Reports/css/source/_widgets.less'; @import '../Magento_Sales/css/source/_widgets.less'; // Theme widgets